« Transifex API v2.1 | up | Transifex API v1 (deprecated) »

Transifex API v2

With Transifex 1.1 a new ReSTful API has been implemented, which is easier to use and more consistent. The new API will become the default in a future version of Transifex.

Transifex offers an extensive Application Programmable Interface which is currently being used 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 new API: projects, resources and translations. Each project has a number of resources and each resource some content in a source language and translated in other languages.

The URLs shown below should be prepended with the full API URL, which should include the API version as well:

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

For example, here’s a cURL command which fetches the details of a project with a slug “foo”:

curl -i --user username:password http://www.transifex.com/api/2/project/foo/

For more examples, please refer to the Examples section below.

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.

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) 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 and slug 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

If the maintainers field is not set, then the owner of the project will be set as the maintainer of the project.

Project instance methods

URL:
/project/<project_slug>/

Available methods:

GET:

Returns the fields slug, name and description for the project of the specified slug in JSON format. If the keyword full is used as a GET parameter, a more complete list of fields is returned. This includes the name, the slug and the description of the project, as well as the fields:

  • long_description
  • homepage
  • feed
  • created
  • anyone_submit
  • bug_tracker
  • trans_instructions
  • 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.
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.
DELETE:

Deletes the project of the specified slug. The slug should be given as a JSON-encoded field.

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, mimetype, and a dictionary with details for the source_language of the resources that belong to this project.
POST:

Creates a new resource with the specified slug. 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
  • mimetype
  • content (in case of sending the content as one string)
  • category

For a list of the supported content types, please refer to the Supported File Formats section.

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 mimetype 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
  • category
PUT:

Updates the details for the specified resource (not the file/string with the source strings). 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.

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.

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.

Examples

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:Follows HTTP redirections
-i:Show response headers
-X:Pass a HTTP method name
-d:Pass in parameters enclosed in quotes; multiple parameters are separated by ‘&’.

GET:

curl -i -L --user username:password -X GET \
http://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" http://www.transifex.com/api/2/projects/

PUT:

curl -i -L --user username:password -X PUT -d '{"name":"Foo2"}' \
-H "Content-Type: application/json" http://www.transifex.com/api/2/project/foo/

DELETE:

curl -i -L --user username:password -X DELETE \
http://www.transifex.com/api/2/project/foo/
Next Section: Transifex API v1 (deprecated) »
« Transifex API v2.1 | up | Transifex API v1 (deprecated) »
© Copyright Transifex. Last updated on Apr 16, 2013 using Sphinx.