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 locales). 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
  • 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 private API key and is used to list strings.

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

Where format is one of xml, json, or yaml. Note that you can get a JSONP response by adding a ?callback=yourFunctionName parameter to the json API call.

Pagination

This resource is paginated and serves 150 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:

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:

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.
  • 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.

page: Page number.

locale (optional): The locale code in which the segments translations will be displayed. Example: locale=ru. You can also pass several locales, for instance: locale=en,de,fr. 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:

Example response in JSON with locale parameter:

Show String

This endpoint is only accessible by the private 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. Note that you can get a JSONP response by adding a ?callback=yourFunctionName parameter to the json API call.

You can optionally pass a locale parameter (the locale code in which the segments translations will be displayed).

Example response with JSON:

  • 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

Example Implementation in PHP

Create String

This endpoint is only accessible by the private API key and is used to create a new string.

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

Parameters

A JSON object modelled after the following:

or:

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:

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

Example Implementation in Ruby

Example Implementation in PHP

Update String

This endpoint is only accessible by the private API key and is used to update an existing string.

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

Parameters

A JSON object modelled after the following:

or:

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

Example Implementation in PHP

Example Implementation in curl

Delete String

This endpoint is only accessible by the private API key and is used to delete a string.

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

Example Implementation in Ruby

Example Implementation in PHP