Transifex

  • Documentation
  • API
  • Translation Strings

Translation Strings

The Translation Strings endpoint handles READ/UPDATE operations for the translations in a language of a specific resource.

Translation strings in a resource are identified by two elements: the key and the context. The key is the actual identifier for a translation. Each file format has its own way to specify keys. For instance, for PO files the key is the msgid attribute for each entry. The context, on the other hand, defines a namespace for the translations. Most formats do not use one. However, PO files use the attribute msgctxt to define the context for each string. Other formats might use more than one and have a list of context.

Identifying strings using hashes

There is also a 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's no context defined, you should use an empty string as it.

So, in Python, the string hash would be calculated by the following program:

from hashlib import md5

if isinstance(context, list):
    if context:
        keys = [string_key] + context
    else:
        keys = [string_key, '']
else:
    if context == 'None':
        keys = [string_key, '']
    else:
        keys = [string_key, context]
return md5(':'.join(keys).encode('utf-8')).hexdigest()

Or, in JavaScript:

// Array with source string content and context.
// If context doesn't exists, it should be empty.
var content = ["Source string", ""]; 
var string_hash = md5(content.join(':'));

Finding the hexdigest of Transifex Live strings

If you are creating a hexdigest of Transifex Live strings, the digest must be created from the key.

from hashlib import md5
key = md5(source_string.encode('utf-8')).hexdigest()
return md5(':'.join([key,''])).hexdigest()

String Hash Exceptions involving JSON and RequireJS

Both JSON and RequireJS require an additional step to ensure we can accurately match a hash. You must first escape all . and \ characters. In addition, special care must be taken when using any form of nesting (lists and other documents). An example Python program and detailed explanation can be found in the JSON format section.

Uploading and downloading a collection of strings

URL: /project/<project_slug>/resource/<resource_slug>/translation/<language_code>/strings

GET

The response is a JSON list of the available translations. For each translation, there is a dictionary with the data of the translation, including the translation string itself and the following fields.

  • key - The identifier for each translation.
  • context - The context of the translation, usually a string. In case of multiple contexts, it is a list of strings.
  • comment - The developer comment for the translation.
  • source_string - The source string. If the string is pluralized, a dictionary is returned which maps plural rules to the corresponding translation string.
  • translation - The translation string in the particular language. If the string is pluralized, this will instead be a dictionary. The keys of the dictionary will be the plural rule the translation corresponds to and the values the translation string.
  • reviewed - Whether the translation has been reviewed or not.
  • pluralized - Whether the string is pluralized or not.

You can also get more details for the translations by specifying the details parameter. The extra fields returned in this case are the following:

  • last_update - The date and time each translation was last translated.
  • user - The user who last updated the translation.
  • occurrences - The occurrences of the source string in the source file.
  • character_limit - Maximum number of characters permitted in a translation excluding the variables.
  • tags - List of tags that can be used to filter and group strings.

Additionally, there are four more parameters you can specify in a request:

  • key - An identifier for a string. Transifex will return all matching translations. The key must be URL encoded.
  • context - The context of the translations to return. Transifex will return all translations that have the specified context. The context must be URL encoded.
  • last_update_from - When this parameter is submitted (yyyy-mm-dd format), the response contains only strings that were translated from the specified date onward (strings translated on the specified date are included).
  • last_update_to - When this parameter is submitted (yyyy-mm-dd format), the response contains only strings that were translated before the specified date (strings translated on the specified date are included).

These parameters can be combined to limit the results.

Example:

$ curl -i -L --user api:<token> -X GET https://www.transifex.com/api/2/project/transifex/resource/core/translation/pt_BR/strings/?details&key=day&last_update_from=2017-05-04

HTTP/1.0 200 OK
...
[
    {
        "comment": "",
        "context": "",
        "character_limit": 55,
        "tags": ["foo"],
        "key": "Remember me for 30 days",
        "reviewed": false,
        "user": "diegobz",
        "pluralized": false,
        "source_string": "Remember me for 30 days",
        "translation": "Lembrar de mim por 30 dias",
        "last_update": "2012-11-04T10:06:47.809",
        "occurrences": "accounts/forms.py:138"
    },
    {
        "comment": "",
        "context": "",
        "character_limit": 25,
        "tags": ["foo"],
        "key": "%s day",
        "reviewed": false,
        "user": "diegobz",
        "pluralized": true,
        "source_string": {
            "1": "%s day",
            "5": "%s days"
        },
        "translation": {
            "1": "%s dia",
            "5": "%s dias"
        },
        "last_update": "2012-06-25T20:30:24.807",
        "occurrences": "app/utils.py:132"
    }
]

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 are errors, no updates will take place. In other words, the call is atomic. Instead, an HTTP status code and an error message will be returned.

Only Project Maintainer and 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, for 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.

Example:

$ curl -i -L --user api:<token> -X PUT -H "Content-Type: application/json" \
--data '[{"source_entity_hash": "e9fbd679f07d178744bfa80344080962", \
"translation": "Lembrar de mim por um mês", "user": "diegobz", "reviewed": true}]' \
https://www.transifex.com/api/2/project/transifex/resource/core/translation/pt_BR/strings/

HTTP/1.0 200 OK
...
OK

Uploading and downloading a translation for a single string

URL: /project/<project_slug>/resource/<resource_slug>/translation/<language_code>/string/<source_hash>/

As in the call above the source_hash is calculated as described at String Hashes.

GET

Return a JSON dictionary with the relevant translation data of the specified entry identified by its source hash. The fields returned are the following:

  • key - The key of the translation string.
  • context - The context of the translation, usually a string. In case of multiple contexts, it is a list of strings.
  • comment - The developer comment of the translation string.
  • source_string - The source string. If the string is pluralized, a dictionary is returned which maps plural rules to the corresponding translation string.
  • translation - The actual translation string. If the string is pluralized, a dictionary is returned instead, which maps plural rules to the corresponding translation string.
  • reviewed - Whether the translation string has been reviewed or not.
  • pluralized - Whether the string is pluralized or not.
  • last_update - The date and time the translation string was last updated.
  • user - The last user to have updated the translation string.
  • occurrences - The occurrences of the source string in the project.
  • character_limit - Maximum number of characters permitted in a translation without including the variables.
  • tags - List of tags that can be used to filter out and group strings.

Example:

$ curl -i -L --user api:<token> -X GET https://www.transifex.com/api/2/project/transifex/resource/core/translation/pt_BR/string/e9fbd679f07d178744bfa80344080962/

HTTP/1.0 200 OK
...
{
    "comment": "",
    "context": "",
    "character_limit": 95,
    "tags": ["foo"],
    "key": "Remember me for %(days)s days",
    "reviewed": false,
    "user": "diegobz",
    "pluralized": false,
    "source_string": "Remember me for %(days)s days",
    "translation": "Lembrar de mim por %(days)s dias",
    "last_update": "2012-11-04T10:06:47.809",
    "occurrences": "accounts/forms.py:138"
}

PUT

Update the translation of a source string. Only the translationreviewed, and user fields are available.

The rules that apply to String Collections apply here too.

Example:

$ curl -i -L --user api:<token> -X PUT -H "Content-Type: application/json" --data '{"translation": {"1": "%s dia", "5": "%s dias"}}' https://www.transifex.com/api/2/project/transifex/resource/core/translation/pt_BR/string/33a30c465eb0831701799d28b1e98e20/

HTTP/1.0 200 OK
...
OK

{
    "mimetype": "text/x-po"
    "mimetype": "text/x-po"
}

Downloading pseudolocalization files

URL: /project/<project_slug>/resource/<resource_slug>/pseudo/?pseudo_type=MIXED

Generates pseudolocalization files. You can find more information on the topic here.

GET

Returns a JSON dictionary containing the content of the pseudolocalization file and the mimetype of the corresponding source file.

Example:

$ curl -i -L --user api:<token> -X GET https://www.transifex.com/api/2/project/transifex/resource/core/pseudo/?pseudo_type=MIXED

HTTP/1.0 200 OK
...
{
    "content": '# Translation file for Transifex.\n# Copyright (C) 2007-2010 Indifex Ltd.\n# This file is distributed under the same license as the Transifex package.\n# \n# Translators:\n# Translators:\nmsgid ""\nmsgstr ""\n"Project-Id-Version: Transifex\n"\n"Report-Msgid-Bugs-To: \n"\n"POT-Creation-Date: 2014-09-22 22:59+0000\n"\n"PO-Revision-Date: 2014-09-16 11:46+0000\n"\n"Last-Translator: Themis Savvidis <themhs@gmail.com>\n"\n"Language-Team: English (https://www.transifex.com/projects/p/transifex/language/en/)\n"\n"MIME-Version: 1.0\n"\n"Content-Type: text/plain; charset=UTF-8\n"\n"Content-Transfer-Encoding: 8bit\n"\n"Language: en\n"\n"Plural-Forms: nplurals=2; plural=(n != 1);\n"\n\n#: accounts/forms.py:28\nmsgid "Full name is required."\nmsgstr "[Ƒŭŀŀ ƞȧḿḗ īş řḗɋŭīřḗḓ. ςſDžDž ΰNjςϱ Nj]"\n\n#: accounts/forms.py:37\nmsgid "Transifex does not support this role."\nmsgstr "[Ŧřȧƞşīƒḗẋ ḓǿḗş ƞǿŧ şŭƥƥǿřŧ ŧħīş řǿŀḗ. ıϐϐ鶱衋LjΐDžDz]"\n\n#: accounts/forms.py:51 accounts/forms.py:293\nmsgid "Username"\nmsgstr "[Ŭşḗřƞȧḿḗ ϕ靐ẛẛ靐衋ı鶱]"',
    "mimetype": "text/x-po"
}