Transifex API v2.1¶

Note

This document describes the latest stable version of the API. There are also docs for the development version development version.

This is the API provided by Transifex 1.2 and is now the default API version to use. Version 2.1 mostly adds extra API calls to expose to clients more information.

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 three main entities in the API: projects, resources and translations. Each project has a number of resources and each resource some content in a source language and is translated in some other languages. Transifex also defines releases, which represent a specific release for a project.

Using the API¶

You can use a variety of tools (desktop or web-based) to test the API. A quick way 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:

http://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.

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"}' \
-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/

Authentication¶

All of the API calls on Transifex require the user to be authenticated with Transifex in order to complete them. Currently, the API supports HTTP Basic Authentication and it’s also sharing login information with django’s built in authentication system that’s being used on Transifex. 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 character ‘-‘.
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 and source_language_code of the project as a JSON string. Additionally, the user may submit values for the following fields:

description
long_description
private
homepage
feed
anyone_submit
hidden
bug_tracker
trans_instructions
tags
maintainers
outsource

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

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"}' \
-H "Content-Type: application/json" https://www.transifex.com/api/2/p/projects

HTTP/1.1 409 CONFLICT
...
Conflict/Duplicate

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 fields:

long_description
homepage
feed
created
anyone_submit
bug_tracker
trans_instructions
a list of tags
outsource
a list of the maintainers’ username
the username of the owner of the project
a list of the resources of the project containing the fields slug and name.
a list of language codes for the teams created for the project.

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.

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:

slug
name
accept_translations
source_language_code
i18n_type
category
content (in case of sending the content as one string)

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:

created
available_languages
project_slug
wordcount
total_entities
accept_translations
last_update

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"
        },
        ...
    ],
}

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.

Translations¶

The Translations application handles CRUD operations for the translations of a specific resource (identified by resource_slug) of a specific project (identified by resource_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.

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.

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:

completed: the percentage of the resource that has been translated for the language.
translated_entities: the number of entities that have been translated for the language.
untranslated_entities: the number of entities that have not been translated for the language.
translated_words: the number of words that have been translated for the language.
untranslated_words: the number of words that have not been translated for the language.
last_update: the date and time that the last update for this translation took place.
last_committer: the username of the last user to have updated the translation for the language.
reviewed: the number of entities which have been reviewed for the language.
reviewed_percentage: the percentage of entities that have been reviewed for the language.

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.

INDEX

TABLE OF CONTENTS

DOCS HOME

Transifex API v2.1¶

Using the API¶

Authentication¶

Terminology¶

Projects¶

Project set methods¶

Project instance methods¶

Releases¶

Release instance methods¶

Resources¶

Resources set methods¶

Resource instance methods¶

Source language methods¶

Translations¶

Statistics¶

i18n Formats¶

Formats methods¶

Table Of Contents

You are here:

INDEX

TABLE OF CONTENTS

DOCS HOME

Transifex API v2.1¶

Using the API¶

Authentication¶

Terminology¶

Projects¶

Project set methods¶

Project instance methods¶

Releases¶

Release instance methods¶

Resources¶

Resources set methods¶

Resource instance methods¶

Source language methods¶

Translations¶

Statistics¶

i18n Formats¶

Formats methods¶

Table Of Contents

You are here:

Quick search