Help

Management
Translation
Integration
API
← Back to the API overview

String API

The String API is composed of 5 endpoints:

Anatomy of a String

A String is a data structure representing a segment on which several translations in different languages are aligned. A String has many Translation (in different languages). A Translation belongs to a String. A String is composed of:

  • id: ID number of a String. This ID is attributed by WebTranslateIt.com
  • key: Key name of a String. The Key name is unique within a same file and attributed by the user.
  • status: Status of a String. Can be one of current (not hidden nor obsolete), hidden or obsolete.
  • category: Category of a String
  • label: Label name of a String
  • context: Context of a String (used by XLIFF files)
  • file: File ID in which a String can be located. Can be left blank if you want to host your Strings only in database.
  • type: If not blank, can be one of string, plural, array, boolean. Will filters segments querying these attributes.

List String

This endpoint is accessible by the read-only and read-write Project API key and is used to list strings.

/api/projects/:project_token/strings.format [GET]

Where format is one of xml, json, or yaml.

Pagination

This resource is paginated and serves 250 Strings per page (this amount of items per page can change at any time). You can specify further page using the ?page parameter. Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination information is included in the Link header. You can use the Link Header in order to know which page is next and which page is the last one, instead of constructing your own URLs.

For instance, let’s make a curl request to the String API:

$ curl -I "https://webtranslateit.com/api/projects/api_token/strings.json"

The -I parameter indicates that we only care about the headers, not the actual content. In examining the result, you’ll notice some information in the Link header that looks like this:

Link: <https://webtranslateit.com/api/projects/api_key/strings.json?page=2>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/strings.json?page=20>; rel="last"

The possible rel values are:

  • next: Shows the URL of the immediate next page of results.
  • last: Shows the URL of the last page of results.
  • first: Shows the URL of the first page of results.
  • prev: Shows the URL of the immediate previous page of results.

Here’s another example of the Link Header when browsing the 3rd page:

$ curl -I "https://webtranslateit.com/api/projects/api_token/strings.json?page=3"

Link: <https://webtranslateit.com/api/projects/api_key/strings.json?page=4>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/strings.json?page=9>; rel="last",
  <https://webtranslateit.com/api/projects/api_key/strings.json?page=1>; rel="first",
  <https://webtranslateit.com/api/projects/api_key/strings.json?page=2>; rel="prev"

Parameters

filters:

  • key: Name of the keys to fetch
  • original_key (use instead of key): Name of the original_key to fetch (Used when resname is set in XLIFF files).
  • regex: (optional) if set to true, perform a regex search
  • ignore_case: (optional) if set to true and regex is also set to true, perform a non case sensitive regex search
  • status: Fetch String having a specific status. This filter is case insensitive and can be one of:
    • option left blank: fetch strings independently of status,
    • current: fetch strings that are not hidden or obsolete,
    • hidden: fetch hidden strings,
    • obsolete: fetch obsolete strings.
    • to_translate: fetch untranslated segments for a language. Must be used with filters[locale]=xx filter.
    • to_verify: fetch unverified segments for a language. Must be used with filters[locale]=xx filter.
    • to_proofread: fetch unproofread segments for a language. Must be used with filters[locale]=xx filter.
    • done: fetch proofread segments for a language. Must be used with filters[locale]=xx filter.
  • category: Category name of a String. If set to none will return all segments with no categories.
  • label: Label name of a String. If set to none will return all segments with no labels.
  • context: Context of a String, only used by XLIFF files.
  • created_at: List String added at of after date
  • instructions: Can be one of yes or no or left blank. Will list segment containing instructions or segments not containing any instructions.
  • file: File ID of a String. If you don’t have the File ID you can optionally pass the file_name parameter instead.
  • no_follow_redirects: Set it to anything to not use language inheritance.

page: Page number.

locale (optional): The locale code (or language code) in which the segments translations will be displayed. Example: locale=ru. You can also pass several locales, for instance: locale=en,de,fr or use a wildcard to get all locales at once: locale=*. The API will return an array of translations instead of a translation object.

Example query:

https://webtranslateit.com/api/projects/api_key/strings?filters[key]=date&filters[status]=current

Example response with JSON:

[
  {
    "id": 1234,
    "key": "activerecord.errors.models.invitation.attributes.email.user_already_invited",
    "plural": false,
    "type": "String",
    "dev_comment" :null,
    "status": "Current",
    "labels": "",
    "word_count": 6,
    "character_count": 24,
    "attachments": [{"id":9391,"created_at":"2015-12-15T10:12:04Z","url":"https://s3.amazonaws.com/users0-webtranslateit/production/file_attachments/original/389283928327.png?1450174324"}],
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
    "project": {
      "id": 406,
    },
    "file": {
      "id": 1943
    },
    "has_discussions": false
  },
  {
    "id": 1235,
    "key": "activerecord.errors.models.invitation.attributes.email.user",
    "plural": false,
    "type": "String",
    "dev_comment" :null,
    "status": "Current",
    "labels": "",
    "word_count": 6,
    "character_count": 24,
    "attachments": []
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
    "project": {
      "id": 406,
    },
    "file": {
      "id": 1943
    },
    "has_discussions": true
  }
]

Example response in JSON with locale parameter:

[
    {
        "id": 140067,
        "key": "activerecord.errors.models.invitation.attributes.email.user_already_invited",
        "project": {
            "id": 406
        },
        "file": {
            "id": 1943
        },
        "plural": false,
        "type": "String",
        "dev_comment": "",
        "status": "Current",
        "labels": "",
        "categories": "",
        "word_count": 6,
        "character_count": 34,
        "attachments": [],
        "created_at": "2010-02-09T23:23:45Z",
        "updated_at": "2014-03-13T08:18:10Z",
        "translations": {
            "id": 564959,
            "locale": "fr",
            "text": "Cet utilisateur a déjà été invité",
            "status": "status_proofread",
            "created_at": "2010-02-11T21:14:19Z",
            "updated_at": "2012-02-10T19:24:33Z",
            "version": 17
        },
        "has_discussions": false
    },
    {
        "id": 140068,
        "key": "activerecord.errors.models.invitation.attributes.email.user_already_member",
        "project": {
            "id": 406
        },
        "file": {
            "id": 1943
        },
        "plural": false,
        "type": "String",
        "dev_comment": null,
        "status": "Current",
        "labels": "",
        "categories": "",
        "word_count": 6,
        "character_count": 29,
        "attachments": [],
        "created_at": "2010-02-09T23:23:45Z",
        "updated_at": "2014-03-13T08:18:10Z",
        "translations": {
            "id": 564960,
            "locale": "fr",
            "text": "Cet utilisateur est déjà membre",
            "status": "status_proofread",
            "created_at": "2010-02-11T21:14:40Z",
            "updated_at": "2011-12-09T15:59:58Z",
            "version": 7
        },
        "has_discussions": false
    }
]

Show String

This endpoint is accessible by the read-only and read-write Project API key and is used to show a string.

/api/projects/:project_token/strings/:string_id.format [GET]

Where format is one of xml, json or yaml.

You can optionally pass a locale parameter (the locale code in which the segments translations will be displayed). You can also pass several locales, for instance: locale=en,de,fr or use a wildcard to get all locales at once: locale=*. The API will return an array of translations instead of a translation object.

You can optionally pass a no_follow_redirects parameter: Set it to anything to bypass language inheritance.

Example response with JSON:

{
  "key": "activerecord.errors.models.invitation.attributes.email.user_already_invited",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "attachments": [],
  "created_at": "2010-02-09T23:23:45Z",
  "updated_at": "2011-10-28T13:54:13Z",
  "project": {
    "id": 406,
  },
  "file": {
    "id": 1943
  },
  "has_discussions": false
}
  • key: unique string identifier. The key name is unique within a file.
  • plural: true if plural string, or else false (default: false)
  • type: Type (or cast) or a string. Can be String, Integer, Array, Symbol. (default: String)
  • dev_comment: Developer comment
  • status: String status. Can be Current, Obsolete, Hidden
  • labels: Comma-delimited labels for a string.
  • word_count: Word count for the source translation.
  • character_count: Character count for the source translation.

Example Implementation in Ruby

require 'net/http'
http = Net::HTTP.new('webtranslateit.com', 443)
request = Net::HTTP::Get.new('/api/projects/:api_token/strings/:string_id')
http.request(request)

Example Implementation in PHP

<?php
  $api_key = "sekret";
  $string_id = "1234";
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/strings/". $string_id . ".json");
  $response = curl_exec($ch);
  $p = json_decode($response, true);
  print_r($p);
  curl_close($ch);
?>

Create String

This endpoint is only accessible by the read-write Project API key and is used to create a new string.

/api/projects/:project_token/strings [POST]

Parameters

A JSON object modelled after the following:

{
  "key": "key_name",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "file": {
    "id": 1943
  }
}

or:

{
  "key": "key_name",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "file": {
    "file_name": "path/to_file.xml"
  }
}

All fields are optional. If no key is provided, WebTranslateIt will name the string using the current time.
If everything goes Well, WebTranslateIt will respond with 201 Created in the header and a JSON representation of the string just created in the body.

You can also create one or several Translations while creating a String by passing an optional array of Translation:

{
  "key": "key_name",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "translations": [
    {
      "locale": "en",
      "text": "Some text",
      "status": "status_proofread"
    },
    {
      "locale": "fr",
      "text": "Du texte",
      "validation": "false"
    }
  ]
}

In this array of Translation, locale and text are mandatory. status is optional.

Example Implementation in Ruby

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Post.new('/api/projects/:api_token/strings', {'Content-Type' => 'application/json' })
request.body = {key: 'string_key', dev_comment: 'This is a comment' }.to_json
http.request(request)
# creating a plural segment
request.body = {key: 'string_key', plural: true, translations: [{locale: 'en', text: {'one' => '%{count} translation', 'other' => '%{count} translations'} }] }.to_json
http.request(request)

Example Implementation in PHP

<?php
  $api_key = "sekret";

  $new_string = Array();
  $new_string["key"] = "TESTSTRING";
  $new_string["type"] = "String";
  $new_string["dev_comment"] = "test";
  $new_string["status"] = "Current";
  $new_string["file"]["id"] = 116156;

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/strings");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($new_string));
  curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));

  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Update String

This endpoint is only accessible by the read-write Project API key and is used to update an existing string.

/api/projects/:project_token/strings/:string_id [PATCH]

Parameters

A JSON object modelled after the following:

{
  "key": "key_name",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "file": {
    "id": 1943
  }
}

or:

{
  "key": "key_name",
  "plural": false,
  "type": "String",
  "dev_comment" :null,
  "status": "Current",
  "labels": "",
  "categories": "",
  "word_count": 6,
  "character_count": 24,
  "file": {
    "file_name": "path/to_file.xml"
  }
}

All fields are optional. Only provided fields will be modified. Don’t forget to pass a Content-Type: application/json header in your request.
If everything goes Well, WebTranslateIt will respond with 202 Accepted in the header and a JSON representation of the string just updated in the body.

Example Implementation in Ruby

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Put.new('/api/projects/:api_token/strings/:string_id', {'Content-Type' => 'application/json' })
request.body = {key: 'string_key_updated', dev_comment: 'This is an updated comment' }.to_json
http.request(request)

Example Implementation in PHP

<?php
  $api_key = "sekret";
  $string = array();
    $string["key"] = "string_key";
    $string["dev_comment"] = "A developer comment";
    $string_id = "1234";
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/strings/" . $string_id);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($string));
  curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>

Example Implementation in curl

$ curl -i -H "Content-Type: application/json" -X PATCH -d "{"dev_comment": "abc”}" https://webtranslateit.com/api/projects/sekret/strings/1234

Delete String

This endpoint is only accessible by the read-write Project API key and is used to delete a string.

/api/projects/:project_token/strings/:string_id [DELETE]

Example Implementation in Ruby

require 'net/http'
http = Net::HTTP.new('webtranslateit.com', 443)
request = Net::HTTP::Delete.new('/api/projects/:api_token/strings/:string_id')
http.request(request)

Example Implementation in PHP

<?php
  $api_key = "sekret";
  $string_id = "1234";
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/strings/" . $string_id);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
  $response = curl_exec($ch);
  print_r($response);
  curl_close($ch);
?>