• Documentation
  • API
  • Examples of API Calls

Examples of API Calls

Before you begin, here are a few things to keep in mind about the Transifex API.

All API calls should use the following URL prefix:

https://www.transifex.com/api/2/

All projects are handled under this URL schema:

https://www.transifex.com/api/2/project/project_slug/

Any resource content is handled under this URL schema:

https://www.transifex.com/api/2/project/project_slug/resource/resource_slug/content/

Note

You can find project_slug and resource_slug in your project's URL.

e.g.

slugs.png#asset:3608

Creating a project

In order to create a new project on Transifex using Transifex's API, use the following API call:

$ curl -i -L --user username:password -d '{"slug":"documentation", "name":"Transifex Documentation", "source_language_code":"en", "private": true}' \
-H "Content-Type: application/json" -X POST https://www.transifex.com/api/2/projects/

After the new project "Transifex Documentation" is created, it can be accessed via the following URL:

https://www.transifex.com/api/2/project/documentation/

Uploading a new source file to Transifex

Let's assume that you would like to upload a new source file to Transifex under the project you just created with the following information:

  • organization_slug: transifex
  • project_slug: documentation
  • slug: api_doc,
  • name: API-Documentation

All you need to do is to type the following command line (note that slug and name above are example values specified by you):

$ curl -i -L --user username:password -H "Content-tye: multipart/form-data" \
-F slug=api_doc -F name=API-Documentation -F i18n_type=XLIFF -F content=@path_to_the_file \
-X POST https://www.transifex.com/api/2/project/documentation/resources/

Updating the source file

Now, let's assume that you have a new version of your source file and you need to update its content on Transifex. So, use the following API call in order to achieve what you want:

$ curl -i -L --user username:password -F file=@path_to_the_file \
-X PUT https://www.transifex.com/api/2/project/documentation/resource/api_doc/content/

Regarding the above case, please check this link in order to have an overall view of how Transifex handles updates of a source file.

Generally:

  • New strings are being added.
  • Modified strings are considered new ones and are being added as well.
  • Strings which do not exist in the new source file (including ones which have been modified) are being removed from the database, along with their translations.

Uploading translation files to Transifex

Now, let's upload, for example, a French translation file under the "API-Documentation" resource. You can simply do that, by using the following command line:

​$ curl -i -L --user username:password -F file=@path_to_the_file \
-X PUT https://www.transifex.com/api/2/project/documentation/resource/api_doc/translation/fr/

Adding a translation to a specific source string

Let's assume now that you want to translate a specific string of the "API-Documentation" resource to French.

Step 1

The first thing you need to do is to get the whole information of the desired string by typing the following command line:

$ curl -i -L --user username:password \
-X GET https://www.transifex.com/api/2/project/documentation/resource/api_doc/translation/fr/strings/?details&key=the_key_of_the_string

Note

You need to know the key of the string you are interested in.

Please note that if you use the above URL without adding the key at the end of it: https://www.transifex.com/api/... then you will get the information for all the existing strings of the resource.

So, the above GET request will return something like this (example):

{
"comment": "",
"context": "",
"tags": null,
"character_limit": null,
"reviewed": false,
"user": "nelefth",
"key": "Trans_definition",
"source_string": "Transifex is a localization platform.",
"translation": "Transifex est une plate-forme de localisation.",
"last_update": "2015-10-16T16:17:19.307",
"pluralized": false,
"occurrences": "forms.py:189"
}

Step 2

After that, you need to calculate the hash of the string by using the following Python commands:

from hashlib import md5
keys = ["Trans_definition", '']
print( md5(':'.join(keys).encode('utf-8')).hexdigest() );
2a7cc1619ef9ae8b1274470301153ded (the hash will look like this)

In case the "context": is not None then please check this link in order to calculate the string hash correctly

Step 3

The final step is to upload the translation on Transifex by using the following API call:

$ curl -i -L --user your_username:your_password \
-H "Content-Type: application/json" --data ‘{"translation": "Transifex est une plate-forme de localisation."}' \
-X PUT https://www.transifex.com/api/2/project/documentation/resource/api_doc/translation/fr/string/2a7cc1619ef9ae8b1274470301153ded/

Adding instructions to a specific source string

In order to add translation instructions to the above source string of the "API-Documentation" resource, your API call should look like this:

$ curl -i -L --user your_username:your_password \
-X PUT -H "Content-Type: application/json" \
--data '{"comment": "add any instruction here"}' \
https://www.transifex.com/api/2/project/documentation/resource/api_doc/source/2a7cc1619ef9ae8b1274470301153ded

Adding/editing your resource's categories

Resources in Transifex can be grouped into categories. 

So, in order to add/edit the categories of the API-Documentation resource (previous example), the following API call should be used:

curl -i -L --user your_username:your_password \ 
-X PUT -H "Content-Type: application/json" \
--data '{"categories": ["tag_1", "tag_2"]}' \
https://www.transifex.com/api/2/project/documentation/resource/api_doc
curl -i -L --user your_username:your_password -X POST -H "Content-Type: application/json" \
--data '{"content": "{\"key1\": \"Check this\",\"key2\": \"Check that\",\"key3\": \"Check this and that\"}", "i18n_type":"KEYVALUEJSON", "name": "JSON FILE", "slug": "define_a_slug_for_your_resource"}' \
https://www.transifex.com/api/2/project/your_project's_slug/resources/

Put request:

curl -i -L --user your_username:your_password -X PUT -H "Content-Type: application/json" \
--data '{"content": "{\"key1\": \"Check this\",\"key2\": \"Check that\",\"key3\": \"Check this and that\", \"key4\": \"One more additional string\"}"}' \
https://www.transifex.com/api/2/project/your_project's_slug/resource/your_resource's_slug/content

Note

Every time you update your source content in Transifex, the strings that are included in the last PUT API request, will be the only ones that will be available in your resource in Transifex.

This means that the content of a PUT request overwrites the current content that is stored in the specific resource. So, strings that are not included in your API call but they are available in Transifex due to a previous request, will no longer be available after the new request is submitted. 

Translating a pluralized string

Let's assume that you want to submit an Arabic translation for a pluralized string via API.

In order to successfully submit such a request, you need to define the translation for all the plural forms of the Arabic language as follows:

curl -i -L --user your_username:your_password -X PUT -H "Content-Type: application/json" \
--data '{"translation": {"0":"this is the translation for the 1st plural form", "1":"this is the translation for the 2nd plural form", "2": "this is the translation for the 3rd plural form", "3": "this is the translation for the 4th plural form", "4": "this is the translation for the 5th plural form", "5": "this is the translation for the 6th plural form"}}' https://www.transifex.com/api/2/project/project's_slug/resource/resource's_slug/translation/language_code/string/source_entity_hash