The database way of terms storage is represented by TermCollection(s), so it's possible, among other things, to 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. |
Description
The database-side storage of terms is extended by the "TermCollection", which makes it possible, for example, to group terms that belong to a specifc client. This way an end client can be assigned to one or more TermCollections.
Provides access to the Term collections available in the application.
| Table of Contents |
|---|
Get list of TermCollections | |
|---|---|
| Request | GET |
URL:
| /editor/termcollection |
Available Methods:
GET / POST / DELETE
Specialities:
- Deleting term collection will remove all terms, terms attributes and term entry attributes assigned to this term collection
Resource Layout
...
Name
...
Type
...
Info
...
id
...
int
...
GET only
...
name
...
string
...
The name of the term collection (unique)
...
timestamp
...
customerId
...
integer
...
Foreign key to the customers table
POST request parameters example :
- create new empty term collection
...
{
data:{
"name":"The name of the term collection",
"customerId":"the id of the customer to whom this collection is associated"
}}
GET request parameters example :
- return the term collection name,timestamp and customerId for the termcollection with id = 1
...
{
data:{
"id":1
}}
Search term in term collection.
...
URL:
...
editor/termcollection/search
...
Available Methods:
...
Specialities:
...
- Find term/terms in the given term collection by searched string
Resource Layout
...
Name
...
Type
...
Info
...
term
...
string
...
language
...
array
...
Term language/s ids from lek_languages table
...
disableLimit
...
boolean
...
Disable the result limit configured in searchTermsCount config variable.
Search term entry and term attributes in term collection.
...
URL:
...
editor/termcollection/searchattribute
...
Available Methods:
...
Specialities:
...
- Find term entry and term attributes by groupId(termEntry id).
- The result array will return term attributes and term entry attribute values
Info: For search and searchatribute actions, will search in the collection assigned to the customers which customers are assigned to the currently logged user assigned customers.
...
Name
...
Type
...
Info
...
groupId
...
string
...
- Response array example
| Code Block |
|---|
{
"rows":{
"termAttributes":[
{
"definition":"",
"groupId":"001",
"label":"gravure printing",
"value":"11413",
"desc":"gravure printing",
"termId":"11413",
"collectionId":"122",
"languageId":"5",
"labelId":"323",
"attributeId":"73178",
"parentId":null,
"internalCount":null,
"name":"transac",
"attrType":"origination",
"attrTarget":null,
"attrId":null,
"attrLang":"en",
"attrValue":"origination",
"attrCreated":"2018-05-07 17:32:07",
"attrUpdated":"2018-05-07 17:32:07",
"attrDataType":null,
"language":"en"
}
],
"termEntryAttributes":[
{
"id":"8737",
"labelId":"331",
"collectionId":"122",
"termEntryId":"4965",
"parentId":null,
"internalCount":"1",
"language":null,
"name":"note",
"attrType":null,
"attrDataType":null,
"attrTarget":null,
"attrId":null,
"attrLang":null,
"value":"Aleksandar",
"created":"2018-05-07 17:32:07",
"updated":"2018-05-07 17:32:07",
"attributeId":"8737",
"attrValue":"Aleksandar",
"attrCreated":"2018-05-07 17:32:07",
"attrUpdated":"2018-05-07 17:32:07"
}
]
}
} |
Import terms to the term collection
...
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
}}
| ||||||||||
Get details for a certain TermCollection | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Request | GET /editor/termcollection/ID | |||||||||
| URI Params | ID Required. Id of a TermCollection | |||||||||
| ||||||||||
Create a TermCollection | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Request | POST /editor/termcollection | |||||||||
| Params | name Required. Human-readable name for the TermCollection, up to 1024 characters. | |||||||||
| customerIds Required. Comma-separated list of customers ids for this TermCollection to be associated with. | ||||||||||
| ||||||||||
Delete TermCollection | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Request | DELETE /editor/termcollection/ID | |||||||||
| URI Params | ID Required. Id of a TermCollection to be deleted | |||||||||
Note: Deleting TermCollection will remove all terms themselves, all term entries those terms are contained in, and all attributes on entry, language and term levels
| ||||||||||
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. | ||||||||||
deleteTermsLastTouchedOlderThan Optional. If given, should be a date in YYYY-MM-DD format, so that any terms last updated before that date - will be deleted from the target TermCollection. 'Last updated' date for a term is initially set up 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 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.
| ||||||||||
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:
| ||||||||||
Important: response for this endpoint comes with 'Content-Disposition: attachment' HTTP header to provide a direct download of an exported 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.
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. 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)
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.
Important: If no proposals found, then the endpoint will respond with the following XML text
| |||||||||||||||||||
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:
| |||||||||
| 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
| ||||||||||
Details for the resource parameters:
collectionId
The id of the term collection where those terms from the tbx file are going to
customerId
Customer to that this term collection is associated
mergeTerms
The merging of terms into an existing term collection is controlled by this boolean parameter.
The merge process is complex and completely described here.
tbxUpload
tbx file/files (or a zip file containing TBX files) uploaded as multipart/form-data
deleteTermsLastTouchedOlderThan (date format Y-m-d)
Deletes all terms in all listed termCollections, that have a updated date older than the date configured for "deleteTermsLastTouchedOlderThan". Every term in a termCollection has a creation date, a modification date and an updated dated. The creation date and the modification date are taken from the dates as they appear in the TBX file.
The updated date is not shown in the GUI and is changed every time a user changes the term through touching it in the GUI or through an import.
deleteTermsOlderThanCurrentImport (boolean)
Deletes all terms in all listed termCollections, that have an "updated date" older than the start of the current import. To learn, what the "updated date" is, please read above possible values: true or false.
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)
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.
...