Page History

Description

The database -side storage way of terms storage is extended represented by the " TermCollection"(s), which makes so it's possible, for exampleamong other things, to group terms that belong to a specifc client. This way an end client can be assigned to one or more TermCollections.assign different TermCollections to different clients.

Note
If the API changes in an incompatible manner this is listed explicitly in the "important release notes" section of each releases changelog.

Table of Contents

Get

termcollections

list of TermCollections

Request

GET /editor/termcollection

Code Block

language	js
title	Response
collapse	true

{
    "rows": [
        {
            "id": "1",
            "entityVersion": "4",
            "langResUuid": "6860f07a-e09f-4822-b82d-30d1961665aa",
            "name": "Some termcollection",
            "color": "19737d",
            "resourceId": "editor_Services_TermCollection",
            "serviceType": "editor_Services_TermCollection",
            "serviceName": "TermCollection",
            "specificData": "{\"fileName\":\"terminology.tbx\",\"status\":\"available\",\"termEntry\":2727,\"term\":15813,\"attribute\":47439}",
            "timestamp": "2025-05-29 09:59:02",
            "resourceType": "termcollection",
            "writeSource": "0",
            "specificId": null
        },
        {
            "id": "2",
            "entityVersion": "3",
            "langResUuid": "c6c275e1-fd72-47f2-9f8d-47ce01f0510e",
            "name": "Some another termcollection",
            "color": "19737d",
            "resourceId": "editor_Services_TermCollection",
            "serviceType": "editor_Services_TermCollection",
            "serviceName": "TermCollection",
            "specificData": "{\"fileName\":\"160.tbx\",\"status\":\"available\",\"termEntry\":1656,\"term\":13218,\"attribute\":48330}",
            "timestamp": "2025-05-29 10:10:10",
            "resourceType": "termcollection",
            "writeSource": "0",
            "specificId": null
        },
    ],
    "total": 2
}

Get

an info

details for a certain

termcollection

TermCollection
Request	GET /editor/termcollection/ID
URI Params	ID Required. Id of a

termcollection

TermCollection

Code Block

language	js
title	Response
collapse	true

{
    "rows": {
        "id": "2",
        "entityVersion": "3",
        "langResUuid": "c6c275e1-fd72-47f2-9f8d-47ce01f0510e",
        "name": "Some another termcollection",
        "color": "19737d",
        "resourceId": "editor_Services_TermCollection",
        "serviceType": "editor_Services_TermCollection",
        "serviceName": "TermCollection",
        "specificData": "{\"fileName\":\"160.tbx\",\"status\":\"available\",\"termEntry\":1656,\"term\":13218,\"attribute\":48330}",
        "timestamp": "2025-05-29 10:10:10",
        "resourceType": "termcollection",
        "writeSource": "0",
        "specificId": null
    }
}

Create a

termcollection

TermCollection
Request	POST /editor/termcollection
Params	name Required. Human-readable name for the

termcollection

TermCollection, up to 1024 characters.
	customerIds Required. Comma-separated list of customers ids for this

termcollection

TermCollection to be associated with.

Code Block

language	js
title	Response
collapse	true

{
    "rows": {
        "id": 13,
        "entityVersion": "0",
        "langResUuid": "4df34ca9-5e2f-42ad-a31e-946990bb135a",
        "name": "Some new termcollection",
        "color": "19737d",
        "resourceId": "editor_Services_TermCollection",
        "serviceType": "editor_Services_TermCollection",
        "serviceName": "TermCollection",
        "specificData": null,
        "timestamp": "2025-06-17 12:18:31",
        "resourceType": "termcollection",
        "writeSource": "0",
        "specificId": null
    }
}

Delete

termcollection

TermCollection
Request	DELETE /editor/termcollection/ID
URI Params	ID Required. Id of a

termcollection

TermCollection to be deleted
Note: Deleting

term collection

TermCollection will remove all terms themselves, all term entries those terms are contained in, and all attributes on entry, language and term

entry attributes assigned to this term collection

levels

Code Block

language	js
title	Response
collapse	true

{
    "success": true
}

Import terms to the TermCollection via tbx-file(s)
Request	POST /editor/termcollection/import
Params	collectionId Required. Id of a TermCollection where terms should be imported to.
	tbxUpload Required. Tbx file(s) (or a zip file(s) containing TBX files) uploaded as multipart/form-data. If multiple tbx or zip files are given - they should be uploaded under tbxUpload[0], tbxUpload[1], etc params names.
	customerIds Optional. Comma-separated list of customers ids for this termcollection to be associated with.
	mergeTerms Optional. Boolean value to merge imported terms with terms already existing (if any) in the target termcollection. By default - false. The merge process is complex and completely described here.

importSource Optional. If given, should be either 'filesystem' or 'crossApi'

deleteTermsLastTouchedOlderThan Optional. If given, should be a date in YYYY-MM-DD format, so that any terms last updated before

the given

that date - will be deleted from the target TermCollection. 'Last updated' date for a term is initially set up

at

as a current date on import and then refreshed each time term is renamed and/or any of it's attributes created/updated/deleted.

'Last updated' date is maintained internally by translate5, and is not directly shown in TermPortal UI. However, it is replicated to 'Updated by'-field in 'Term attributes'-panel in TermPortal UI each time any further change happended to the term itself or it's attributes after initial import.

deleteTermsOlderThanCurrentImport Optional. Boolean value to delete all terms from the target TermCollection, that

are

were last updated before the the start of the current import, and if given as true - it will have the same affect as if the current date is used as a value for the previously described param.

deleteProposalsLastTouchedOlderThan Optional. If given, should be a date in YYYY-MM-DD format, so that any terms last updated before that date and having Process status = Unprocessed - will be deleted from the target TermCollection. Also, any attributes (for any remaining terms) initially imported from tbx and updated since then but before the given date - will be reverted to back to their original values. At the same time, any attributes that were not initially imported from tbx, i.e. created afterwards but before the given date - will be deleted for the any remaining terms in the target TermCollection.

deleteProposalsOlderThanCurrentImport Optional. Boolean value having the same affect as if the current date is used as a value for the previously described param.

Note: there are additional possibilities to import terms into the TermCollection.

Import tbx files via 'Language resources' tab for the resource of type 'TermCollection', manually, or
1. programmatically via /editor/languageresourceinstance/ID/import endpoint - you can read more here about it
Using the TermImport Plug-In

Code Block

language	js
title	Response
collapse	true

{
    "success": true
}

POST request parameters example(json):

...

{

"data":{

"collectionId": 1,

"customerId":1000,

"mergeTerms":true,

"tbxUpload": ,

"deleteTermsLastTouchedOlderThan": "2018-05-01",

"deleteTermsOlderThanCurrentImport": true,

"deleteProposalsLastTouchedOlderThan": 2018-05-01",

"deleteProposalsOlderThanCurrentImport" : true

}
}

tbxUpload

tbx file/files (or a zip file containing TBX files) uploaded as multipart/form-data

deleteProposalsLastTouchedOlderThan (date format Y-m-d)

Delete all proposals in a listed termCollections, that have a creation date older than this configs value.

deleteProposalsOlderThanCurrentImport (boolean)

Export TermCollection as TBX

Request

GET editor/languageresourceinstance/tbxexport

Params

collectionId Required. Id of a TermCollection to be exported.

tbxBasicOnly=(0|1) Required. Whether to export only TBX Basic standard attributes + processStatus, rather than all attributes.

exportImages=(0|tbx|zip) Required. Whether to export images:

0 - No. You should explicitly specify that value for this param if you don't want images (if any) to be exported.
tbx - Yes, in hex format, embedded in TBX
zip - Yes, in media/ folder inside ZIP-archive

Important: response for this endpoint comes with 'Content-Disposition: attachment' HTTP header to provide a direct download of an exported file.

Code Block

language	js
title	Response
collapse	true

raw text/binary contents, depending on whether TermCollection was exported into a tbx or zip file

Export TermCollection as XLSX

Request

GET editor/languageresourceinstance/xlsxexport

Params

collectionId Required. Id of a TermCollection to be exported.

Important: XSLX export is a two-step operation consisting of prepare-step and download-step.

Prepare-step may take a while depending on TermCollection size, and is implemented in a way that allows to track the preparation progress measured in percents of already exported term entries vs total term entries in that TermCollection, so progress is printed during the export.

Code Block

language	js
title	Response
collapse	true

Total number of term entries: 1
Starting export...
Progress: 0%
..
Progress: 95%
Progress: 100%
Preparing the download...
Done in 2.35 sec

Once export is Done, browser page is reloaded with javascript and the download is started - so yes - all this is intended to work via browser.
For getting the same result via REST API some important things need to be considered:

Example: REST API request via curl-command

Step 1: curl --no-buffer -H "Cookie: zfExtended=your_translate_session_coookie" http://yourTranslate5app.com/editor/languageresourceinstance/xlsxexport?collectionId=XXX

This is the first needed request, that starts and keeps session and shows the progress as pure HTML code during execution (see below)

Code Block

language	js
title	Response
collapse	true

<pre>Total number of term entries: 1</pre><pre>Starting export...</pre><pre>Progress: 100%</pre><pre>Preparing the download...</pre><pre>Done in 0.078 sec</pre><script>window.location=window.location</script>

Step 2: curl -H "Cookie: zfExtended=your_translate_session_coookie" -o file.xlsx http://yourTranslate5app.com/editor/languageresourceinstance/xlsxexport?collectionId=XXX

This is the second needed request that preserves the session and responses with 'Content-Disposition: attachment' header and raw file data as response body, which is saved into file.xlsx on your local computer from where you call the curl-command

Proposals export for a TermCollection, as XLSX

Request

GET editor/languageresourceinstance/export

Params

collectionId Required. Id of a TermCollection to be exported.

exportDate Optional.If given, should be a date in YYYY-MM-DD (or YYYY-MM-DD HH:MM:SS) format, so that only proposals happened after that date will be exported.

Important: response for this endpoint comes with 'Content-Disposition: attachment' HTTP header to provide a direct download of an exported file.

Code Block

language	js
title	Response
collapse	true

raw binary contents of an exported XLSX file

Important: If no proposals found, then the endpoint will respond with the following XML text

Code Block

language	js
title	Response
collapse	true

<?xml version="1.0"?>
<response><message>No results where found.</message></response>

Detect non-existing terms among the given ones - in any of accessible TermCollections

Request

GET editor/termcollection/searchtermexists

Params

searchTerms Required. Should be given as JSON-encoded array structured in the following way:

Code Block

language	js
title	JSON structure
collapse	true

[
    {
        "text": "Some existing term 1",
		"anyOtherProp1": "Some other value 1",
 		"anyOtherProp2": "Some other value 2", 
     },
     {
        "text": "Some non-existing term 1",
		"anyOtherProp1": "Some other value 3",
 		"anyOtherProp2": "Some other value 4", 
     },
     {
        "text": "Some non-existing term 2",
		"anyOtherProp1": "Some other value 5",
 		"anyOtherProp2": "Some other value 6", 
     }
 ]

targetLang Required. Should be given as RFC5646 language code representing a major language (e.g. 'en') or with sublanguage (e.g. 'en-US'), but keep in mind that sublanguage will be ignored.

Important: this endpoint is currently used internally by Translate5's InstantTranslate plugin only - to show 'Propose as new term in TermPortal'-button for translations that are not existing in terminology so far

Code Block

language	js
title	Response
collapse	true

{
    "rows: [
	     {
    	    "text": "Some non-existing term 1",
			"anyOtherProp1": "Some other value 3",
	 		"anyOtherProp2": "Some other value 4", 
    	 },
 	     {
    	    "text": "Some non-existing term 2",
			"anyOtherProp1": "Some other value 5",
	 		"anyOtherProp2": "Some other value 6", 
    	 }
     ]
}

Delete all proposals in a listed termCollections, that have a creation date older than the start of the current import.

Important: with the import call, one or multiple tbx files must be provided. Importing additional files in term collection is also available via the general language resource import route: /editor/languageresourceinstance/[ID]/import. More info can be found here.

There can be additional possibility to import terms to the term collection.

...

Page tree

Versions Compared

Old Version 26

New Version Current

Key

Description

Get

list of TermCollections

Get

details for a certain

TermCollection

Create a

TermCollection

Delete

TermCollection

Import terms to the TermCollection via tbx-file(s)

deleteProposalsLastTouchedOlderThan (date format Y-m-d)

deleteProposalsOlderThanCurrentImport (boolean)

Export TermCollection as TBX

Export TermCollection as XLSX

Proposals export for a TermCollection, as XLSX

Detect non-existing terms among the given ones - in any of accessible TermCollections