• Documentation
  • API
  • Translation Strings

Translation Strings

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

The translation strings of a resource are identified by two parts: 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, in case of 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 (a list of contexts).

Identifying strings using 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 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 = [source_entity] + context
    else:
        keys = [source_entity, '']
else:
    if context == 'None':
        keys = [source_entity, '']
    else:
        keys = [source_entity, 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, like the translation string itself. By default, it returns only a few fields for the translations.

  • 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.

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:

  • 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 without including the variables.
  • tags - List of tags that can be used to filter out and group strings.

Additionally, there are two more parameters the user can specify in a request:

  • key - An identifier for a string. Transifex will return all matching translations. The key must be urlencoded.
  • context - The context of the translations to return. Transifex will return all translations that have the specified context. The context must be urlencoded.

The two parameters can be combined to limit the results.

Example:

$ curl -i -L --user username:password -X GET https://www.transifex.com/api/2/project/transifex/resource/core/translation/pt_BR/strings/?details&key=day

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 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.

Example:

$ curl -i -L --user username:password -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 indentified 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 username:password -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 in apply here, too.

Example:

$ curl -i -L --user username:password -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 in the corresponding section.

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 username:password -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 (http://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"
}