Transifex API v2.1-devel¶
Note
This document describes the development version of the API, which is currently live at https://www.transifex.com. There are also docs for the older versions.
Transifex offers an extensive Application Programmable Interface. It is used, among others, by Transifex itself and the Transifex Client to perform some of the most common operations, such as pulling information about projects and translation resources and uploading or downloading translation files.
The API calls are ReST compliant and make use of the most common HTTP methods such as GET, POST, PUT and DELETE.
There are four main entities in the API: projects, resources, translation files and translation strings. Each project has a number of resources and defines which language is the source language for the project. In the case of a software project, the source language is the language used for the strings in the source code of the project. Each resource in turn has some content in the source language and translations of the content in some other languages. Transifex also defines releases, which represent a specific release for a project. More specifically, releases are a group of resources that are used in a specific version of the project.
Using the API¶
You can use a variety of tools (desktop or web-based) to test the API. A quick way to do it is through the command-line tool cURL.
Here are some handy switches:
| --user: | Pass a username and password for HTTP basic auth. |
|---|---|
| -L: | Follow HTTP redirections |
| -i: | Show response headers |
| -X: | Pass a HTTP method name |
| -d: | Pass in parameters enclosed in quotes; multiple parameters are separated by ‘&’. |
The URLs used should be prepended with the full API URL, which should include the API version as well, as follows:
https://www.transifex.com/api/2/...
Note
The version 2.1 of the API is mostly an extension of the previous one; there were just a few things added. The only thing that has changed is that we now use the i18n_type field in resources instead of relying on the mimetype of the file, so that we can support much more formats. For this reason, we keep the same numbering in the URL.
Examples:
GET:
curl -i -L --user username:password -X GET \
https://www.transifex.com/api/2/projects/
POST:
curl -i -L --user username:password -X POST \
-d '{"slug":"foo","name":"Foo","source_language_code":"en","description":"Description"}' \
-H "Content-Type: application/json" https://www.transifex.com/api/2/projects/
curl -i -L --user username:password -X POST -H "Content-Type: application/json"
-d '{"slug": "bar", "name": "Bar", "i18n_type": "XHTML", "content": "<p>Bar</p>"}' \
https://www.transifex.com/api/2/project/resources/
PUT:
curl -i -L --user username:password -X PUT -d '{"name":"Foo2"}' \
-H "Content-Type: application/json" https://www.transifex.com/api/2/project/foo/
DELETE:
curl -i -L --user username:password -X DELETE \
https://www.transifex.com/api/2/project/foo/
Note
The trailing slash in the URLs is necessary to avoid any redirects. This is especially true, for POST requests, where the redirect will not work correctly.
Authentication¶
Transifex allows only authenticated requests to the API. Currently, the authentication method supported is the HTTP Basic Authentication. The credentials to access the API are the same as those used to access Transifex itself. All external applications should make use of the HTTP Basic Authentication, if they need to perform some operations through the Transifex API.
Part of the development roadmap for Transifex is to add support for other authentication methods as well, such as authentication tokens in order to avoid forcing users to share their login credentials with third party applications. Until then, the only available method is the one stated above.
Terminology¶
- slug
- A small string that will be used in the URL of the project. The allowed characters are the alphanumeric characters as well as the characters ‘_’ and ‘-‘.
- source language
- The language that the content is originally written into. For instance, in a software program, this is the language used for the strings in the source code.
- i18n type
- The format used in a resource for internationalization (i18n). For example, PO, TS, PROPERTIES etc. See Supported File Formats for a list of formats supported and i18n formats for the API support for those.
Projects¶
The Projects application handles CRUD operations on projects. It is accessed under the following two URLs.
Project set methods¶
- URL:
- /projects/
Available methods
| GET: | Returns a list of (slug, name, description, source_language_code) for all projects the user has access to in JSON format. This method supports pagination through the GET parameters start and end. |
|---|---|
| POST: | Creates a new project. The user must submit the necessary values for the name, slug, description and source_language_code of the project as a JSON string. Additionally, the user may submit values for the following fields:
|
The only available characters for the slug field are alphanumeric ones, the underscore and the dash.
The maintainers field is a list of comma-separated usernames. If it is not set, then the owner of the project will be also set as the maintainer of the project.
The source_language_code field specifies the source language that will be used for all resources of the project. A list of the supported languages and their respective codes can be found at https://www.transifex.com/languages/.
The available options for the license field are “proprietary”, “permissive_open_source” and “other_open_source”. If a license is not specified, one is chosen automatically based on whether the project is set to private or not.
Example
The following POST call will attempt to create a project with the id ‘transifex’ and fail, since there is an existing project with that id:
curl -i -L --user user:pass -X POST \
-d '{"slug":"transifex","name":"Transifex","source_language_code":
"en","description":"Description"}' \
-H "Content-Type: application/json" https://www.transifex.com/api/2/projects/
HTTP/1.0 400 BAD REQUEST
...
{'slug': [u'Project with this Slug already exists.']}
Project instance methods¶
- URL:
- /project/<project_slug>/
Available methods
| GET: | Returns the fields slug, name, description and source_language_code for the project of the specified slug in JSON format. If the keyword details is used as a GET parameter, a more complete list of fields is returned. This includes the above fields as well as the following ones:
|
|---|---|
| PUT: | Updates the details for the specified project. Parameters should be given as a JSON-encoded string, like in the POST request above. The available fields are the same as those in the POST request above. However, the field source_language_code is not allowed, if the project has resources, since that would create issues with existing resources. Additionally, the client of the API cannot modify the slug of the project. |
| DELETE: | Deletes the project of the specified slug. The slug should be given as a JSON-encoded field. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/transifex/
HTTP/1.1 200 OK
...
{
"name": "Transifex"
"slug": "transifex",
"description": "Social Localization Platform",
"created": "2009-04-21 08:12:16",
"tags": "translations,l10n,i18n",
"teams": [
"eu",
"lv",
...
],
"resources": [
{
"slug": "txo",
"name": "Transifex core"
},
...
],
}
Releases¶
The Releases application allows one to fetch the resources that belong to a particular release of a project.
Release instance methods¶
- URL:
- /project/<project_slug/release/<release_slug>/
Available methods
| GET: | The answer to the request is JSON-encoded and contains the fields release_date, slug, name and a list of the resources that belong to the release. |
|---|
Resources¶
The Resources application handles CRUD operations on resources for a specific project, identified by project_slug.
Resources set methods¶
- URL:
- /project/<project_slug>/resources/
Available methods
| GET: | Returns a JSON-encoded list with the fields slug, name, i18n_type, source_language_code and the category of the resources that belong to the specified project. |
|---|---|
| POST: | Creates a new resource with the specified slug. The fields slug, name and i18n_type must be specified. The user must also upload the file with the strings in the source language or send the content as a string. In case of a file, the content type of the request must be multipart/form-encode. Otherwise, it must be application/json. The available fields are:
|
Note that the current maximum value for the field slug is 50 characters.
Resource instance methods¶
- URL:
- /project/<project_slug>/resource/<resource_slug>/
Available methods
| GET: | Returns a JSON encoded string with the details for the resource. The default fields returned are the name, the slug, the i18n_type and a dictionary with the details for the source_language of the resource. If the keyword details is given as a GET parameter, then extra fields are returned:
|
|---|---|
| PUT: | Updates the details for the specified resource (not the content in the source language). The same restrictions about the allowed fields as in POST requests apply here as well. |
| DELETE: | Deletes a resource. If the resource does not exist, an error is returned. The user must be authenticated. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/transifex/resource/txo/?details
HTTP/1.1 200 OK
...
{
"slug": "txo"
"mimetype": "text/x-po",
"source_language_code": "en",
"wordcount": 6160,
"total_entities": 1017,
"last_update": "2011-12-05 19:59:55",
"available_languages": [
{
"code_aliases": " ",
"code": "sq",
"name": "Albanian"
},
...
],
}
Upload a file for a translation
curl -i -L --user user:password -F file=@hi_IN/django.po -X PUT https://www.transifex.com/api/2/project/transifex/resource/txo/translation/hi_IN/
Source language methods¶
The translation of the source language is handled under this url:
- URL:
- /project/<project_slug>/resource/<resource_slug>/content/
Available methods
| GET: | Returns the translation in the source language of the resource. If the parameter file is specified in the GET request, the translation is sent as a file, else as a json encoded string. |
|---|---|
| PUT: | Puts a new translation for the source language of the resource. If the content type of the request is application/json, the content must be sent as a json-encoded string. Else, if the content type is multipart/form-data, the content must be sent as a file. In the case of using JSON, the JSON data must be a dictionary with the key being the word “content” and the value being the content of the file. |
Language management¶
The Languages application supports CRUD operation on the languages of a project (identified by a project_slug).
Language set method¶
- URL:
- /project/<project_slug>/languages/
Available methods
| GET: | Returns a JSON encoded list with the fields language_code, coordinators, translators and reviewers that are responsible and work on the languages that belong to the project. Only the project owner or the project maintainers have access to this method. |
|---|---|
| POST: | Adds a new language to the project. The fields language_code and coordinators must be specified. The available optional fields are:
Only the project owner or the project maintainers can perform this action. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/
transifex/languages/
HTTP/1.1 200 OK
[
{
'language_code': 'el',
'coordinators': [
'kbairak',
'glezos'
],
'translators': [
'mpessas',
'jkal',
],
reviewers: [
'sawidis',
'ilias'
]
},
{
'language_code': 'hi',
'coordinators': [
'rajeshr',
'rtnpro'
],
'translators': [
'sayan'
],
reviewers: [
'chandankumar'
]
}
]
Language instance method¶
- URL:
- /project/<project_slug>/language/<language_code>/
Available methods
| GET: | Returns a JSON encoded string with the fields language_code, coordinators, translators and reviewers for the specified language. If the keyword details is given as a GET parameter, then extra fields are returned:
Only the project owner, the maintainers and the people working on the translations for that language may access this method. |
|---|---|
| PUT: | Updates an existing language of a project. The fields language_code, coordinators, translators, reviewers and list are allowed to be updated using this method. One must ensure that the coordinators field is not empty, because there must be a coordinator managing the translations for a language. Only the project owner, the project maintainers and the coordinators for the language can perform this operation. |
| DELETE: | Deletes an existing language of the project. Only the project owner, the project maintainers and the coordinators of the language can perform this operation. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/
transifex/language/el/?details
HTTP/1.1 200 OK
[
{
'coordinators': [
'kbairak',
'glezos'
],
'translators': [
'mpessas',
'jkal',
],
reviewers: [
'sawidis',
'ilias'
],
'translated_segments': 1518,
'untranslated_segments': 96,
'reviewed_segments': 1325,
'total_segments': 1614,
'translated_words': 10022,
'list': '',
'creator': 'glezos',
'date_created': '2010-01-28 12:35:48',
'date_modified': '2012-09-21 08:07:59'
}
Managing coordinators, reviewers and translators¶
For coordinators¶
- URL:
- /project/<project_slug>/language/<language_code>/coordinators/
Available methods
| GET: | Returns a JSON list of the username of coordinators for the language of the project. Only the project owner, the maintainers and the people working on the translations for that language may access this method. |
|---|---|
| PUT: | Updates the list of coordinators for a language of a project. It accepts a JSON encoded list of usernames. This list cannot be empty. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/
transifex/language/el/coordinators/
HTTP/1.1 200 OK
[
'glezos',
'kbairak'
]
For reviewers¶
- URL:
- /project/<project_slug>/language/<langauge_code>/reviewers/
Available methods
| GET: | Returns a JSON list of the username of reviewers for the language of the project. Only the project owner and the maintainers may access this method. |
|---|---|
| PUT: | Updates the list of reviewers for the language of the project. It accepts a JSON encoded list of usernames. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/
transifex/language/el/reviewers/
HTTP/1.1 200 OK
[
'sawidis',
'ilias'
]
For translators¶
- URL:
- /project/<project_slug>/language/<langauge_code>/translators/
Available methods
| GET: | Returns a JSON list of the usernames of the translators for the language of the project. Only users who can submit translations for the language have access to this method. |
|---|---|
| PUT: | Updates the list of translators for a language of the project. It accepts a JSON encoded list of usernames. |
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/
transifex/language/el/translators/
HTTP/1.1 200 OK
[
'mpessas',
'jkal'
]
Translation files¶
The Translation files application handles CRUD operations for the translations of a specific resource (identified by resource_slug) of a specific project (identified by project_slug).
- URL:
- /project/<project_slug>/resource/<resource_slug>/translation/<lang_code>/
Available methods
| GET: | Returns the requested translation, if it exists. The translation is returned as a serialized string, unless the GET parameter file is specified. Moreover, you can specify the mode of the downloaded file with the GET parameter mode. The available modes are:
|
|---|---|
| PUT: | Creates or updates the translation for the specified language. Either the translation is JSON encoded or the request has multipart/form-encode as content type and the file is attached. In the case of using JSON, the JSON data must be a dictionary with the key being the word “content” and the value being the content of the file. |
Translation Memory Exchange (TMX)¶
Using TMX files it is possible to update or get the entries from the Translation Memory (TM) of a project (identified by a project_slug).
- URL:
- /project/<project_slug>/tm/exchange/
Available methods
| GET: | Returns a TMX file for the project with all its TM entries in all languages available (by default). It also accepts some extra GET parameters:
|
|---|---|
| PUT: | Update the TM for the project with the entries of the uploaded TMX file. |
Upload a TMX file for a project
curl -i -L --user user:password -F file=@tm/memory1.tmx -X PUT https://www.transifex.com/api/2/project/transifex/tm/exchange/
Translation strings¶
The Translation strings application handles READ/UPDATE operations for the translations in a language (identified by a language_code) of a specific resource (identified by resource_slug) of a specific project (identified by project_slug).
The translation strings of a resource are identified by two things: the key and the context. The key is the actual identifier for a translation. It depends on the format, what the key is. For instance, for PO files the key is the msgid field. The context, on the other hand, defines a namespace for the translations. Most formats do not use one. PO files, for instance, use the field msgctxt to define the context. Other formats might use more than one (a list of contexts).
String hashes¶
There is another (Transifex specific) way to identify a translation string. You can calculate the md5 hash of the concatenation of the key and the context and take the hexadecimal digest of the result. In case there is no context defined, you should use the string “None”.
So, in Python, the string hash would be calculated by the following program:
from hashlib import md5
if isinstance(context, list):
if context:
keys = [source_entity] + context
else:
keys = [source_entity, '']
else:
if context:
keys = [source_entity, context]
else:
keys = [source_entity, '']
return md5(':'.join(keys).encode('utf-8')).hexdigest()
Translations for a collection of strings¶
- URL:
- /api/2/project/<project_slug>/resource/<resource_slug>/translation/<language_code>/strings/
Available methods
| GET: | The response is a JSON list of the available translations. For each translation there is a dictionary with the data of the translation, like the translation string itself. By default, it returns only a few fields for the translations.
The user may also ask for more details for the translations by specifying the details parameter. The extra fields returned in this case are the following:
Additionally, there are two more parameters the user can specify in his request:
The two parameters can be combined to limit the results. |
|---|---|
| PUT: | The request updates the translations of the resource. A JSON file must be sent in the same format as returned by the above GET method. In case there were errors, no updates will take place. That is, the call is atomic. Instead, a suitable HTTP status code and an error message will be returned. Only a project maintainer or language team members can update translations through the API. Note that source strings cannot be updated. The fields each dictionary in the request must have are the source_entity_hash and the translation string. Project maintainers can use the user attribute to specify the author of those translations, as long as that user would be able to contribute translations to the project. In all other cases, the user sending the translations is set as the author. The author for a translation is updated, only when the translation string itself is updated (not when it is reviewed/unreviewed). Another thing to note is that a translation string that has already been reviewed cannot be updated by team members. Instead, only reviewers, coordinators and project maintainers can edit those. If a request includes such translation strings, they will be ignored, but the response message will have a list of those translations. Additionally, in case of pluralized translations, if the plural forms do not match those defined by the language or some of the plural forms are missing, an error is returned. |
Examples
curl -i -L --user user:password -X GET http://www.transifex.com/api/2/project/p1/resource/testspot/translation/ar/strings/?details\&key=action
HTTP/1.0 200 OK
Date: Thu, 03 May 2012 10:52:54 GMT
Server: WSGIServer/0.1 Python/2.7.2
Vary: Authorization, Host, Accept-Language, Cookie
Content-Type: application/json; charset=utf-8
Content-Language: en
[
{
"comment": "",
"context": "",
"key": "Action",
"wordcount": 1,
"last_update": "2012-05-03 10:43:33",
"user": "admin",
"pluralized": false,
"position": 1,
"source_string": "Action",
"translation": "عمل",
"reviewed": false,
"occurrences": "actionlog/templates/object_action_list.html:8"
},
{
"comment": "",
"context": [
"foo",
"bar"
],
"key": "Actions",
"wordcount": 1,
"last_update": "2012-05-03 10:43:33",
"user": "admin",
"pluralized": false,
"position": 1,
"source_string" "Actions",
"translation": "عمل",
"reviewed": false,
"occurrences": "actionlog/templates/object_action_list.html:9"
}
]
curl -i -L --user user:password -X GET http://www.transifex.com/api/2/project/p1/resource/testspot/translation/ar/strings/?details\&key=result
HTTP/1.0 200 OK
Date: Thu, 03 May 2012 11:53:52 GMT
Server: WSGIServer/0.1 Python/2.7.2
Vary: Authorization, Host, Accept-Language, Cookie
Content-Type: application/json; charset=utf-8
Content-Language: en
[
{
"comment": "",
"context": "",
"key": "{0} result",
"wordcount": 11,
"last_update": "2012-05-03 10:43:33",
"user": "admin",
"pluralized": true,
"position": 1,
"source_string": {
"1": "{0} result",
"5": "{0} results"
},
"translation": {
"0": "لا نتائج",
"1": "نتيجة واحدة",
"2": "نتيجتين",
"3": "{0} نتائج",
"4": "{0} نتيجة",
"5": "{0} نتيجة"
},
"reviewed": false,
"occurrences": "foo/templates/bar.html:180"
}
]
curl -i -L --user user:password -X PUT -H "Content-Type: application/json" --data '[{"source_entity_hash": "85896a744f6fd84cbcd7bddb31fae8d7", "translation": "action", "user": "rtnpro"}]' http://www.transifex.com/api/2/project/p1/resource/testspot/translation/ar/strings/
HTTP/1.0 200 OK
Date: Mon, 11 Jun 2012 07:47:02 GMT
Server: WSGIServer/0.1 Python/2.7.3
Vary: Authorization, Host, Accept-Language, Cookie
Content-Type: text/plain
Content-Language: en
OK
Translation for a single string¶
- URL:
/api/2/project/<project_slug>/resource/<resource_slug>/translation/<language_code>/string/<source_hash>/
where source_hash is calculated as described at String hashes.
Available methods
| GET: | Returns a JSON dictionary with the relevant data for translation of the specified source entity. The fields returned are the following:
|
|---|---|
| PUT: | Updates the translation of a source string. Only the translation, reviewed and user fields are available. The rules that apply to Translations for a collection of strings apply here, too. |
Examples
curl -i -L --user user:password -X GET http://www.transifex.com/api/2/project/p1/resource/testspot/translation/ar/string/fbb05a9f1ad844fcd1740ce9bf8f2574/
HTTP/1.0 200 OK
Date: Thu, 03 May 2012 14:16:26 GMT
Server: WSGIServer/0.1 Python/2.7.2
Vary: Authorization, Host, Accept-Language, Cookie
Content-Type: application/json; charset=utf-8
Content-Language: en
{
"comment": "foo",
"context": "",
"key": "{0} result",
"wordcount": 11,
"last_update": "2012-05-03 10:43:33",
"occurrences": "foo/templates/bar.html:180",
"pluralized": true,
"position": 1,
"source_string": {
"1": "{0} result",
"5": "{0} results"
},
"translation": {
"0": "لا نتائج",
"1": "نتيجة واحدة",
"2": "نتيجتين",
"3": "{0} نتائج",
"4": "{0} نتيجة",
"5": "{0} نتيجة"
},
"reviewed": false,
"user": "admin"
}
curl -i -L --user user:password -X PUT -H "Content-Type: application/json" --data '{"translation": {"0": "zero", "1": "one", "2": "two", "3": "few", "4": "many", "5": "other"}}' http://www.transifex.com/api/2/project/p1/resource/testspot/translation/ar/string/fbb05a9f1ad844fcd1740ce9bf8f2574/
HTTP/1.0 200 OK
Date: Mon, 11 Jun 2012 07:47:02 GMT
Server: WSGIServer/0.1 Python/2.7.3
Vary: Authorization, Host, Accept-Language, Cookie
Content-Type: text/plain
Content-Language: en
OK
Statistics¶
There are some available statistics for each resource, like the translated and untranslated entities per translation. These statistics can be accessed under the following URLs:
- URLs:
/project/project_slug>/resource/<resource_slug>/stats/
/project/project_slug>/resource/<resource_slug>/stats/lang_code/
The latter should be used, if one is interested in the statistics for a particular language.
Available methods
| GET: | Returns the statistics for the specified resource. If the lang_code part is given, statistics are returned only for that specific language. Otherwise, statistics are returned for all available languages. The specific data returned per language are:
|
|---|
Example
curl -i -L --user user:pass -X GET http://www.transifex.com/api/2/project/transifex/resource/txo/stats/
HTTP/1.1 200 OK
...
{
"en": {
"completed": "100%",
"untranslated_words": 0,
"last_commiter": "mpessas",
"last_update": "2011-12-05 19:59:52",
"translated_entities": 1017,
"translated_words": 6160,
"untranslated_entities": 0
},
"gu": {
"completed": "43%",
"untranslated_words": 4572,
"last_commiter": "mpessas",
"last_update": "2011-12-05 19:59:53",
"translated_entities": 439,
"translated_words": 1588,
"untranslated_entities": 578
},
...
}
i18n Formats¶
The Formats application allows one to fetch the details of all the i18n formats supported by Transifex.
Formats methods¶
- URL:
- /formats/
Available methods
| GET: | The answer to the request is JSON-encoded and contains the fields description, mimetype and file-extensions for each i18n format supported by Transifex. |
|---|
Other Transifex API versions¶
Next Section: Transifex API v2.1 »