Create a Translation.io library
(for your own stack)

Introduction

Only 3 HTTP requests with a JSON body are needed to create a complete Translation.io library:

segments/init only needs to be called once just after the project configuration (following calls will be denied by the backend). source_edits/pull and segments/sync should ideally be called successively each time the translations are synchronized.

If you create a library for a framework, the command lines should look like this:

task translation:init → calls segments/init

task translation:sync → calls source_edits/pull followed by segments/sync

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 -X POST https://translation.io/api/v1/segments/init.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 -X POST https://translation.io/api/v1/segments/init.json?api_key=YOUR_API_KEY

HTTP header

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

curl -X POST https://translation.io/api/v1/segments/init.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

{
  "target_languages": ["nl"],
  "segments": {
    "fr": [],
    "nl": []
  }
}

{
  "errors": [
    "Missing param(s): source_language.",
    "'segments' must be a Hash with target_languages as keys and arrays of segments as values."
  ]
}

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.

There are two different types of segments: key segments and source segments. Segment types are immutable so an existing key segment can never become a source segment, and vice versa.

As a general rule of thumb, you should use:

• key segments if you localize in your code using a key: translate("some.custom.key").
• source segments if you localize in your code using the source text: translate("My source text").

If you have both syntaxes available in your framework, you should use both types at the same time in the HTTP requests.

Key segments

Type for segments that are in the key → translation format in your application. They are usually stored in YAML, JSON, PHP, INI or XML files.

Plural and context information are not part of the key segments. However, depending on the framework conventions, they can sometimes be deducted from the key or a special character in the source text.

They are uniquely identified by their key.

Required parameters

Optional parameters

Notes

• Segments are always encapsulated in a specific target language, so the language combination (en → fr in above example) doesn't need to be specified in every segment. See init parameters.

Source segments

Type for segments that are in the source → translation format in your application. They are usually stored in PO (GetText) or XLIFF files that have been specifically designed for translations.

Plural and context information are an integral part of the segments.

They are uniquely identified by the combination of context, source and source_plural.

Required parameters

Optional parameters

Notes

• Segments are always encapsulated in a specific target language, so the language combination (en → fr in above example) doesn't need to be specified in every segment. See init parameters.

Initialization

Populate a new Translation.io project by pushing all source and translated text into the backend. This call should only be executed one time per project.

Endpoint

Parameters

Response

{
  "name": "project_name",
  "url": "https://translation.io/owner_name/project_name"
}

Example

{
  "source_language": "en",
  "target_languages": ["fr", "es"],
  "segments": {
    "fr": [segment_1_fr, segment_2_fr, ...],
    "es": [segment_1_es, segment_2_es, ...]
  }
}

The segments could be translated or not, and look like this:

{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Au revoir le monde"
}

{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Adios al mundo"
}

{
  "type": "source",
  "source": "Hello world",
  "target": "Bonjour le monde"
}

{
  "type": "source",
  "source": "Hello world",
  "target": ""
}

The response from Translation.io would be:

{
  "project": {
    "name": "project_name",
    "url" : "https://translation.io/owner_name/project_name"
  },
  "segments": {
    "fr": [segment_1_fr, segment_2_fr, ...],
    "es": [segment_1_es, segment_2_es, ...]
  }
}

In this case, segment_1_fr, segment_2_fr, segment_1_es and segment_2_es are the same as above.

For some specific stacks, they may have been pre-translated by Translation.io (see here).

Synchronization

Synchronize your current branch with Translation.io by pushing all source text and receiving new translations from Translation.io. If a new source text is found in the application, it will be added to Translation.io

Endpoint

Parameters

Response

{
  "name": "project_name",
  "url": "https://translation.io/owner_name/project_name"
}

Example

{
  "source_language": "en",
  "target_languages": ["fr", "es"],
  "segments": [segment_1, segment_2, ...]
}

Where segments only contain the source (no translation!), and look like this:

{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world"
}

{
  "type": "source",
  "source": "Hello world"
}

The response will return the corresponding translated segments for each target language.

{
  "project": {
    "name": "project_name",
    "url" : "https://translation.io/owner_name/project_name"
  },
  "segments": {
    "fr": [segment_1_fr, segment_2_fr, ...],
    "es": [segment_1_es, segment_2_es, ...]
  },
  "unused_segment_ids": []
}

Note: an empty unused_segment_ids assumes that every segment from Translation.io is listed on the request.

If everything is translated on Translation.io, the segments in the response would be the following:

{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Au revoir le monde"
}

{
  "type": "key",
  "key": "goodbye.message",
  "source": "Goodbye world",
  "target": "Adios al mundo"
}

{
  "type": "source",
  "source": "Hello world",
  "target": "Bonjour le monde"
}

{
  "type": "source",
  "source": "Hello world",
  "target": "Hola mundo"
}

Source Editions

Update your code with the latest source editions that have been made on the Translation.io interface (more info here and here).

This step is only needed for key segments. If you only want to manage source segments, you can safely ignore this HTTP call.

Always call this endpoint before synchronization to always be up to date with the latest source editions.

Endpoint

Parameters

Response

{
  "name": "project_name",
  "url": "https://translation.io/owner_name/project_name"
}

Notes

• This endpoint is "read-only", it will not trigger any change on the backend.

Example

Let's assume the following source editions have been made in the project:

If the project timestamp stored in .translation_io is 1710000000, then the request should be:

{
  "timestamp": 1710000000
}

The response will only contain source editions #2 and #3. Source edition #1 was created before the timestamp from the request and should already have been updated in the project.

{
  "project": {
    "name": "project_name",
    "url" : "https://translation.io/owner_name/project_name"
  },
  "source_edits": [
    {
      "key": "home.welcome.intro",
      "old_source": "Hi everybody",
      "new_source": "Hello everybody",
      "created_at": 1720000000
    },
    {
      "key": "footer.legal",
      "old_source": "Term of service",
      "new_source": "Terms of service",
      "created_at": 1730000000
    }
  ],
  "timestamp": 1734782416
}