Table of contents

API Reference BETA

This API and related documentation are still under active development. We are doing our best to avoid introducing breaking changes. We plan to release the final version before the end of 2019.

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.

You need some help? You found a bug?
CONTACT US

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

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': aa. 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 only exists for key segments. source_plural, target_plural, target_plural_2, target_plural_3 and context properties only exist 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 2 plural forms or more. 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 3 plural forms. 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"]

Note

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 2 plural forms or more. 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 3 plural forms. 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.

Note

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 2 plural forms or more. 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 3 plural forms. 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"]

Note

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.

Note

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.

Response

Name Type Description
segments array Array of segments for the corresponding target_language, filtered by the optional type, state, tag and query filters.
Example: see below.

Note

Examples

Complete list of French segments

request
{
  "target_language": "fr"
}
response
{
  "segments": [
    {
      "id": 1,
      "source_id": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
      "target_language": "fr",
      "type": "source",
      "source": "Hello",
      "target": "Bonjour"
    },
    {
      "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": "85af68954641ff0400756bc3b93de505680e621e834040a63732621e659c1d82",
      "target_language": "fr",
      "type": "source",
      "source": "Hello",
      "target": "Bonjour"
    }
  ]
}

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"
  }
}