Docs API

API Reference

Translation.io is designed to help developers localize and translate applications that are constantly evolving. Many out of the box synchronization libraries exist to help them with this task and we also explain how to create a new library.

To complement these solutions, we also provide this official API that can be used to create or improve your own translation workflows.

— API changes —

The API is considered stable in its current state. We will do our best not to introduce breaking changes.

Need help, have a question or found a bug?

Introduction

Our API has been built with REST principles and conventions in mind. It's only accessible through HTTPS and receives JSON parameters and returns JSON responses.

The current version of the API is v1 and the base URL is https://translation.io/api/v1/.

Authentication

There are three ways to authenticate through Translation API: JSON parameter, URL query parameter and HTTP header.

If several authentications are used at the same time, the priority order is the following:

  • JSON parameter.
  • URL query parameter.
  • HTTP header.

JSON parameter

Add the project API key as api_key parameter in the JSON body of your request.

cURL request 
curl -X GET https://translation.io/api/v1/segments.json \
  -H 'Content-Type: application/json' \
  -d '{
        "api_key": "YOUR_API_KEY"
      }'

URL query parameter

Add the project API key as api_key parameter in the request URL:

cURL request 
curl -X GET https://translation.io/api/v1/segments.json?api_key=YOUR_API_KEY

HTTP header

Add the project API key as x-api-key in the request header.

cURL request 
curl -X GET https://translation.io/api/v1/segments.json \
  -H 'x-api-key: YOUR_API_KEY'

Errors

Translation.io uses conventional HTTP codes to indicate if a request is successful (2xx) or if it failed (4xx). Errors will be returned with a JSON body warning you about missing params, extra params or erroneous values in params.

errors is an array of strings, so if many errors are triggered at the same time, all of them will be returned in the response.

Example

request (list segments) 
{
  "target_language": "er",
  "type": "both"
}
response 
{
  "errors": [
    "Invalid 'target_language': er. Please use one of the project target languages: fr.",
    "Invalid 'type': both. Please use 'key', 'source' or 'all'."
  ]
}

Segments

segment is the most important model of Translation.io. Each segment corresponds to a single unit of translation from a source language to a target language.

Interactions with the segments API are reflected in real-time on the translation interface and working translators will see them directly.

There are two different types of segments: key segments and source segments. They use the same model but some of their properties are distinct. Segment types are immutable. An existing key segment can never become a source segment, and vice versa.

The following table summarizes the differences between them:

Key segments Source segments
Use key → translation internal structure. Use source → translation internal structure.
Are localized using translate("some.custom.key") in your code. Are localized using translate("My source text") in your code.
Are usually stored in key-value YAML, JSON, PHP, INI or XML files. Are usually stored in PO (GetText) or XLIFF files that have been specifically designed for translations.
Don't encapsulate plural information (but one key segment can be the plural of another). Encapsulate plural and context information.
key property exists only for key segments. source_plural, target_plural, target_plural_2, target_plural_3, target_plural_4, target_plural_5 and context properties exist only for source segments.
Are uniquely identified by their key. Are uniquely identified by their context, source and source_plural

The segment object

Name Type Description
id integer Unique identifier for this segment.
source_id string Unique source identifier for this segment. source_id helps to detect segments that have the same origin and are translated into different target languages.
  • For key segments, the source identifier is based on key.
  • For source segments, the source identifier is based on a combination of context, source and source_plural.
target_language string Target language code (from here).
Example: "en".
type string Segment type. Should be "key" or "source".
key only for key segments string Key associated with the text to be translated.
Example: "home.call_to_action.bottom"
source string Source text.
Example: "Click here to subscribe"
target string Translated target text.
Example: "Cliquez ici pour vous inscrire"
source_plural only for source segments string Plural form of source text.
Note: only if segment is plural.
Example: "products in the cart"
target_plural only for source segments string Plural form of target text.
Note: only if segment is plural.
Example: "articles dans le panier"
target_plural_2 only for source segments string Second plural form of target text.
Note: only if segment is plural and has 3 plural forms or more (target included). See list of languages.
target_plural_3 only for source segments string Third plural form of target text.
Note: only if segment is plural and has 4 plural forms or more (target included). See list of languages.
target_plural_4 only for source segments string Fourth plural form of target text.
Note: only if segment is plural and has 5 plural forms or more (target included). See list of languages.
target_plural_5 only for source segments string Fifth plural form of target text.
Note: only if segment is plural and has 6 plural forms or more (target included). See list of languages.
context only for source segments string Used to differentiate 2 segments that have the same source but need different translations because of their context.
Note: "orange" with context="fruit" and "orange" with context="color" should coexist and have distinct translations when needed.
comment string Comment to help translate this segment.
Example: "Homepage call-to-action (the bottom one)."
references array of strings File(s) where this key is stored or called inside the source code. May provide more context for translators.
Example:  ["config/locales/fr.yml", "app/home/index.html:33"]
tags array of strings List of associated tags.
Example:  ["to proofread", "fixed"]

Notes

  • The source language of a segment is always the one of the project.

Create a segment

POST https://translation.io/api/v1/segments(.json)

Create a new segment of key or source type.

Parameters

Name Type Description
target_language string Target language code (from here).
Example: "en".
type string Segment type. Should be "key" or "source".
key only for key segments string Key associated with the text to be translated.
Example: "home.call_to_action.bottom"
source string Source text.
Example: "Click here to subscribe"
target optional string Translated target text.
Example: "Cliquez ici pour vous inscrire"
source_plural only for source segments optional string Plural form of source text.
Note: only if segment is plural.
Example: "products in the cart"
target_plural only for source segments optional string Plural form of target text.
Note: only if segment is plural.
Example: "articles dans le panier"
target_plural_2 only for source segments optional string Second plural form of target text.
Note: only if segment is plural and has 3 plural forms or more (target included). See list of languages.
target_plural_3 only for source segments optional string Third plural form of target text.
Note: only if segment is plural and has 4 plural forms or more (target included). See list of languages.
target_plural_4 only for source segments optional string Fourth plural form of target text.
Note: only if segment is plural and has 5 plural forms or more (target included). See list of languages.
target_plural_5 only for source segments optional string Fifth plural form of target text.
Note: only if segment is plural and has 6 plural forms or more (target included). See list of languages.
context only for source segments optional string Used to differentiate 2 segments that have the same source but need different translations because of their context.
Note: "orange" with context="fruit" and "orange" with context="color" should coexist and have distinct translations when needed.
comment optional string Comment to help translate this segment.
Example: "Homepage call-to-action (the bottom one)."
references optional array of strings File(s) where this key is stored or called inside the source code. May provide more context for translators.
Example: ["config/locales/fr.yml", "app/home/index.html:33"]

Response

Name Type Description
segment hash Created segment.

Examples

Create a new key segment

We use only required parameters in this example.

request 
{
  "type": "key",
  "target_language": "fr",
  "key": "homepage.title",
  "source": "Welcome to the application"
}
response 
{
  "segment": {
    "id": 1,
    "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
    "target_language": "fr",
    "type": "key",
    "key": "homepage.title",
    "source": "Welcome to the application",
    "target": ""
  }
}

Create a new source segment

We use required and optional parameters in this example.

request 
{
  "type": "source",
  "target_language": "fr",
  "source": ":count product in the cart",
  "target": ":count produit dans le panier",
  "source_plural": ":count products in the cart",
  "target_plural": ":count articles dans le panier",
  "context": "cart",
  "comment": "Please keep ':count' as placeholder in the translations",
  "references": ["views/cart.html"]
}
response 
{
  "segment": {
    "id": 1,
    "source_id": "9f38aa51fc3131277fc4abb4dd9cd42513336745720b7f7a487be605ee5ff3c0",
    "target_language": "fr",
    "type": "source",
    "source": ":count product in the cart",
    "target": ":count produit dans le panier",
    "source_plural": ":count products in the cart",
    "target_plural": ":count articles dans le panier",
    "context": "cart",
    "comment": "Please keep ':count' as placeholder in the translations",
    "references": ["views/cart.html"]
  }
}

Retrieve a segment

GET https://translation.io/api/v1/segments/:id(.json)

Get a single segment using its id.

Response

Name Type Description
segment hash Corresponding segment for this id.
Notes
  • Returns 404 HTTP code and a JSON error message if no segment was found.

Examples

Existing segment
request 
GET https://translation.io/api/v1/segments/2.json?api_key=<YOUR_API_KEY>
response 
{
  "segment": {
    "id": 2,
    "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
    "target_language": "fr",
    "type": "source",
    "source": "Good afternoon",
    "target": "Bon après-midi",
    "tags": [
      "proofread"
    ]
  }
}
Not found segment
request 
GET https://translation.io/api/v1/segments/99.json?api_key=<YOUR_API_KEY>
response With 404 error code 
{
  "errors": [
    "Could not find any segment with this id."
  ]
}

Update a segment

PATCH https://translation.io/api/v1/segments/:id(.json)

Update an existing segment of key or source type.

Parameters

Name Type Description
target optional string Translated target text.
Example: "Cliquez ici pour vous inscrire"
target_plural only for source segments optional string Plural form of target text.
Note: only if segment is plural.
Example: "articles dans le panier"
target_plural_2 only for source segments optional string Second plural form of target text.
Note: only if segment is plural and has 3 plural forms or more (target included). See list of languages.
target_plural_3 only for source segments optional string Third plural form of target text.
Note: only if segment is plural and has 4 plural forms or more (target included). See list of languages.
target_plural_4 only for source segments optional string Fourth plural form of target text.
Note: only if segment is plural and has 5 plural forms or more (target included). See list of languages.
target_plural_5 only for source segments optional string Fifth plural form of target text.
Note: only if segment is plural and has 6 plural forms or more (target included). See list of languages.
comment optional string Comment to help translate this segment.
Example: "Homepage call-to-action (the bottom one)."
references optional array of strings File(s) where this key is stored or called inside the source code. May provide more context for translators.
Example:  ["config/locales/fr.yml", "app/home/index.html:33"]
Notes
  • Other properties cannot be updated through the API. If you want to update the type, key, source, source_plural, target_language or context values, create a new segment instead.
  • The source of an existing key segment can only be updated using the SourceEdit model. Segments with the same key from other target languages will also be updated accordingly.
  • If a source segment was created plural (source_plural is present), it must stay plural and cannot be changed to singular. The opposite is also true.

Response

Name Type Description
segment hash Updated segment.

Examples

Update an existing key segment
request 
// PATCH https://translation.io/api/v1/segments/3.json?api_key=<YOUR_API_KEY>

{
  "target": "Au revoir",
  "comment": "When the user leave the website.",
  "references": ["view/shared/flash.html"]
}
response 
{
  "segment": {
    "id": 3,
    "source_id": "6c8e8a8f5a483490d0ca0cb2eb73f710cc7e1c918cf435bfcb4cf9441a4ecf91",
    "target_language": "fr",
    "type": "key",
    "key": "goodbye.message",
    "source": "Goodbye",
    "target": "Au revoir",
    "comment": "When the user leave the website.",
    "references": ["view/shared/flash.html"]
  }
}
Update an existing source segment
request 
// PATCH https://translation.io/api/v1/segments/1.json?api_key=<YOUR_API_KEY>

{
  "target": "Bonjour!"
}
response 
{
  "segment": {
    "id": 1,
    "source_id": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
    "target_language": "fr",
    "type": "source",
    "source": "Hello",
    "target": "Bonjour!"
  }
}

Delete a segment

DELETE https://translation.io/api/v1/segments/:id(.json)

Delete an existing segment using its id.

Response

Name Type Description
segment hash Removed segment.
Notes
  • Returns 404 HTTP code and a JSON error message if no segment was found.

Examples

Existing segment
request 
DELETE https://translation.io/api/v1/segments/1.json?api_key=<YOUR_API_KEY>
response 
{
  "segment": {
    "id": 1,
    "source_id": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
    "target_language": "fr",
    "type": "source",
    "source": "Hello",
    "target": "Bonjour"
  }
}
Not found segment
request 
DELETE https://translation.io/api/v1/segments/99.json?api_key=<YOUR_API_KEY>
response With 404 error code 
{
  "errors": [
    "Could not find any segment with this id."
  ]
}

List all segments

GET https://translation.io/api/v1/segments(.json)

List all segments for a given project and target language.

Optional parameters can be added to the request to filter the segments list.

Parameters

Name Type Description
target_language string Target language code (from here).
Example: "es"
query optional string Query segments to returns only the ones that contain query value in their key, source, target (with plurals), context, comment or references properties.
Note: that query is case-insensitive.
type optional string Filter by type of segments. Should be key, source or all.
Default: "all"
state optional string Filter by state of segments. Should be translated, untranslated or all.
Default: "all"
tag optional string Filter by tag. Only returns segments that are tagged with tag value.
warning optional boolean Filter the segments that have a warning with true, or that doesn't have any warning with false.
Note: a warning is usually a missing interpolation or some HTML inconsistency between source and target.

Response

Name Type Description
segments array Array of segments for the corresponding target_language, filtered by the optional type, state, tag, query and warning filters.
Example: see below.
Notes
  • For your convenience, HTTP query parameters instead of JSON parameters are also accepted for this request.

Examples

Complete list of French segments
request 
{
  "target_language": "fr"
}
response 
{
  "segments": [
    {
      "id": 1,
      "source_id": "0cf3a1558cf1a203e8843e4f53bbab6ab7ec4bf3df075b166a21965f33e25dc3",
      "target_language": "fr",
      "type": "source",
      "source": "Hello <b>world</b>",
      "target": "Bonjour <i>le monde</i>"
    },
    {
      "id": 2,
      "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
      "target_language": "fr",
      "type": "source",
      "source": "Good afternoon",
      "target": "Bon après-midi",
      "tags": [
        "proofread"
      ]
    },
    {
      "id": 3,
      "source_id": "6c8e8a8f5a483490d0ca0cb2eb73f710cc7e1c918cf435bfcb4cf9441a4ecf91",
      "target_language": "fr",
      "type": "key",
      "key": "goodbye.message",
      "source": "Goodbye",
      "target": ""
    }
  ]
}
List only key segments
request 
{
  "target_language": "fr",
  "type": "key"
}
response 
{
  "segments": [
    {
      "id": 3,
      "source_id": "6c8e8a8f5a483490d0ca0cb2eb73f710cc7e1c918cf435bfcb4cf9441a4ecf91",
      "target_language": "fr",
      "type": "key",
      "key": "goodbye.message",
      "source": "Goodbye",
      "target": ""
    }
  ]
}
List only segments with the "proofread" tag.
request 
{
  "target_language": "fr",
  "tag": "proofread"
}
response 
{
  "segments": [
    {
      "id": 2,
      "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
      "target_language": "fr",
      "type": "source",
      "source": "Good afternoon",
      "target": "Bon après-midi",
      "tags": [
        "proofread"
      ]
    }
  ]
}
List only untranslated segments
request 
{
  "target_language": "fr",
  "state": "untranslated"
}
response 
{
  "segments": [
    {
      "id": 3,
      "source_id": "6c8e8a8f5a483490d0ca0cb2eb73f710cc7e1c918cf435bfcb4cf9441a4ecf91",
      "target_language": "fr",
      "type": "key",
      "key": "goodbye.message",
      "source": "Goodbye",
      "target": ""
    }
  ]
}
List only segments with the word "Hello".
request 
{
  "target_language": "fr",
  "query": "hello"
}
response 
{
  "segments": [
    {
      "id": 1,
      "source_id": "0cf3a1558cf1a203e8843e4f53bbab6ab7ec4bf3df075b166a21965f33e25dc3",
      "target_language": "fr",
      "type": "source",
      "source": "Hello <b>world</b>",
      "target": "Bonjour <i>le monde</i>"
    }
  ]
}
List only segments that have a warning.
request 
{
  "target_language": "fr",
  "warning": true
}
response 
{
  "segments": [
    {
      "id": 1,
      "source_id": "0cf3a1558cf1a203e8843e4f53bbab6ab7ec4bf3df075b166a21965f33e25dc3",
      "target_language": "fr",
      "type": "source",
      "source": "Hello <b>world</b>",
      "target": "Bonjour <i>le monde</i>"
    }
  ]
}

Tags

tags can be added to or removed from a segment.

Tags have their own endpoint and cannot be updated using segments#create or segments#update.

Adding and removing tags will be reflected in real-time in the translation interface and working translators will see them directly. You can read more about tags in this blog article .

Add a tag

POST https://translation.io/api/v1/segments/:id/add_tag(.json)

Add a new tag to the segment corresponding to id.

Parameters

Name Type Description
name string Tag name.
Note: a unique color will be attributed to the tag. If this tag already exists in the project, the same color will be reused.
Note 2: if this tag is already added to the segment, nothing will change and no error will be triggered.

Response

Name Type Description
segment hash Updated segment with the added tag.

Example

request URL 
POST https://translation.io/api/v1/segments/1/add_tag.json?api_key=<YOUR_API_KEY>
request JSON 
{
  "name": "need review"
}
response 
{
  "segment": {
    "id": 1,
    "source_id": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
    "target_language": "fr",
    "type": "source",
    "source": "Hello",
    "target": "Bonjour",
    "tags": ["need review"]
  }
}

Remove a tag

POST https://translation.io/api/v1/segments/:id/remove_tag(.json)

Remove a tag from the segment corresponding to id.

Parameters

Name Type Description
name string Tag name.
Note: if this tag doesn't exist or is not linked to this segment, nothing will change and no error will be triggered.

Response

Name Type Description
segment hash Updated segment without the removed tag.

Example

request URL 
POST https://translation.io/api/v1/segments/2/remove_tag.json?api_key=<YOUR_API_KEY>
request JSON 
{
  "name": "proofread"
}
response 
{
  "segment": {
    "id": 2,
    "source_id": "b9d78193f955836a4ffd2ace3d06c725f605a8fdf142522908dc5605fce30f72",
    "target_language": "fr",
    "type": "source",
    "source": "Good afternoon",
    "target": "Bon après-midi"
  }
}

Source Editions

A source_edit is a change that will update the source text of all the key segments that have a specific key value. The corresponding segments will be updated for all the active target languages.

The main purpose or source editions is to allow the copywriting feature.

If one of the updated segments is already translated, a new tag named source changed is added so that translators have the opportunity to check the existing translation against the new source value.

Source editions will appear in real-time in the translation interface and working translators will see them directly.

Create a source edition

POST https://translation.io/api/v1/source_edits(.json)

Create a new source edition for the corresponding key.

Parameters

Name Type Description
key string Key corresponding to the segments that need their source updated.
Example: "home.call_to_action.bottom"
new_source string New source text.
Example: "Click here to subscribe"

Response

Name Type Description
segments array Array of updated segments with their new source.
Note: if a segment has already source with the same value as new_source, it will not be returned.
Example: see below.
Notes
  • If you need to list all the previous source editions of a project, use the source_edits/pull endpoint with timestamp = 0 as parameter.

Examples

Create a new source edition
request 
{
  "key": "homepage.title",
  "new_source": "Welcome to this fantastic application!" // old source was "Welcome to the application"
}
response 
{
  "segments": [
    {
      "id": 1,
      "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
      "target_language": "fr",
      "type": "key",
      "key": "homepage.title",
      "source": "Welcome to this fantastic application!",
      "target": "Bienvenue dans cette application",
      "tags": [
        "source changed"
      ]
    },
    {
      "id": 2,
      "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
      "target_language": "nl",
      "type": "key",
      "key": "homepage.title",
      "source": "Welcome to this fantastic application!",
      "target": ""
    },
    {
      "id": 3,
      "source_id": "8976a51c2a5a74be9bdabc07c29c10cb9e69b86c719ce071052e9b7adf25d0a7",
      "target_language": "de",
      "type": "key",
      "key": "homepage.title",
      "source": "Welcome to this fantastic application!",
      "target": "Willkommen zu dieser Anwendung",
      "tags": [
        "source changed"
      ]
    }
  ]
}

Need help or have a question?