Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account.
https://api.phrase.com/v2/
https://api.us.app.phrase.com/v2
The API is only accessible via HTTPS and the current version is v2, which results in a base URL like: https://api.phrase.com/v2/ depending on the datacenter.
curl is used primarily to send requests to Phrase Strings in the examples. On most you'll find a second variant using the Phrase Strings API v2 client that might be more convenient to handle. For further information check its documentation.
Phrase Strings API v2 tries to use the appropriate HTTP verb for accessing each endpoint according to REST specification where possible:
| Verb | Description |
|---|---|
| GET | Retrieve one or multiple resources |
| POST | Create a resource |
| PUT | Update a resource |
| PATCH | Update a resource (partially) |
| DELETE | Delete a resource |
You must include the User-Agent header with the name of your application or project. It might be a good idea to include some sort of contact information as well, so that we can get in touch if necessary (e.g. to warn you about Rate-Limiting or badly formed requests). Examples of excellent User-Agent headers:
User-Agent: Example Mobile App ([email protected])
User-Agent: ACME Inc Python Client (http://example.com/contact)
If you don't send this header, you will receive a response with 400 Bad Request.
When you request a list of resources, the API will typically only return an array of resources including their most important attributes. For a detailed representation of the resource you should request its detailed representation.
Lists are usually paginated.
Many endpoints support additional parameters, e.g. for pagination. When passing them in a GET request you can send them as HTTP query string parameters:
$ curl -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects?page=2"
When performing a POST, PUT, PATCH or DELETE request, we recommend sending parameters that are not already included in the URL, as JSON body:
$ curl -H 'Content-Type: application/json' -d '{"name":"My new project"}' -u EMAIL_OR_ACCESS_TOKEN https://api.phrase.com/v2/projects
Encoding parameters as JSON means better support for types (boolean, integer) and usually better readability. Don't forget to set the correct Content-Type for your request.
The Content-Type header is omitted in some of the following examples for better readbility.
If a request contains invalid JSON or is missing a required parameter (besides resource attributes), the status 400 Bad Request is returned:
{
"message": "JSON could not be parsed"
}
When the validation for a resource fails, the status 422 Unprocessable Entity is returned, along with information on the affected fields:
{
"message": "Validation Failed",
"errors": [
{
"resource": "Project",
"field": "name",
"message": "can't be blank"
}
]
}
Times and dates are returned and expected in ISO 8601 date format:
YYYY-MM-DDTHH:MM:SSZ
Instead of 'Z' for UTC time zone you can specify your time zone's locale offset using the following notation:
YYYY-MM-DDTHH:MM:SS±hh:mm
Example for CET (1 hour behind UTC):
2015-03-31T13:00+01:00
Please note that in HTTP headers, we will use the appropriate recommended date formats instead of ISO 8601.
There are two different ways to authenticate when performing API requests:
- E-Mail and password
- Oauth Access Token
To get started easily, you can use HTTP Basic authentication with your email and password:
$ curl -u username:password "https://api.phrase.com/v2/projects"
You can create and manage access tokens in your profile settings in Translation Center or via the Authorizations API.
Simply pass the access token as the username of your request:
$ curl -u ACCESS_TOKEN: "https://api.phrase.com/v2/projects"
or send the access token via the Authorization header field:
$ curl -H "Authorization: token ACCESS_TOKEN" https://api.phrase.com/v2/projects
As JSONP (and other) requests cannot send HTTP Basic Auth credentials, a special query parameter access_token can be used:
curl "https://api.phrase.com/v2/projects?access_token=ACCESS_TOKEN"
You should only use this transport method if sending the authentication via header or Basic authentication is not possible.
Users with Two-Factor-Authentication enabled have to send a valid token along their request with certain authentication methods (such as Basic authentication). The necessity of a Two-Factor-Authentication token is indicated by the X-PhraseApp-OTP: required; :MFA-type header in the response. The :MFA-typefield indicates the source of the token, e.g. app (refers to your Authenticator application):
X-PhraseApp-OTP: required; app
To provide a Two-Factor-Authentication token you can simply send it in the header of the request:
curl -H "X-PhraseApp-OTP: MFA-TOKEN" -u EMAIL https://api.phrase.com/v2/projects
Since Two-Factor-Authentication tokens usually expire quickly, we recommend using an alternative authentication method such as OAuth access tokens.
Some endpoints require the account ID to be specified if the authenticated user is a member of multiple accounts. You can find the eight-digit account ID inside Translation Center by switching to the desired account and then visiting the account details page. If required, you can specify the account just like a normal parameter within the request.
Endpoints that return a list or resources will usually return paginated results and include 25 items by default. To access further pages, use the page parameter:
$ curl -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects?page=2"
Some endpoints also allow a custom page size by using the per_page parameter:
$ curl -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects?page=2&per_page=50"
Unless specified otherwise in the description of the respective endpoint, per_page allows you to specify a page size up to 100 items.
We provide you with pagination URLs in the Link Header field. Make use of this information to avoid building pagination URLs yourself.
Link: <https://api.phrase.com/v2/projects?page=1>; rel="first", <https://api.phrase.com/v2/projects?page=3>; rel="prev", <https://api.phrase.com/v2/projects?page=5>; rel="next", <https://api.phrase.com/v2/projects?page=9>; rel="last"
Possible rel values are:
| Value | Description |
|---|---|
| next | URL of the next page of results |
| last | URL of the last page of results |
| first | URL of the first page of results |
| prev | URL of the previous page of results |
All API endpoints are subject to rate limiting to ensure good performance for all customers. The rate limit is calculated per user:
- 1000 requests per 5 minutes
- 4 concurrent (parallel) requests
For your convenience we send information on the current rate limit within the response headers:
| Header | Description |
|---|---|
X-Rate-Limit-Limit |
Number of max requests allowed in the current time period |
X-Rate-Limit-Remaining |
Number of remaining requests in the current time period |
X-Rate-Limit-Reset |
Timestamp of end of current time period as UNIX timestamp |
If you should run into the rate limit, you will receive the HTTP status code 429: Too many requests.
If you should need higher rate limits, contact us.
Note: Conditional GET requests are currently only supported for locales#download and translations#index
We will return an ETag or Last-Modified header with most GET requests. When you request a resource we recommend to store this value and submit them on subsequent requests as If-Modified-Since and If-None-Match headers. If the resource has not changed in the meantime, we will return the status 304 Not Modified instead of rendering and returning the resource again. In most cases this is less time-consuming and makes your application/integration faster.
Please note that all conditional requests that return a response with status 304 don't count against your rate limits.
$ curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download"
HTTP/1.1 200 OK
ETag: "abcd1234abcdefefabcd1234efab1234"
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 200 OK
$ curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download" -H 'If-None-Match: "abcd1234abcdefefabcd1234efab1234"'
HTTP/1.1 304 Not Modified
ETag: "abcd1234abcdefefabcd1234efab1234"
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 304 Not Modified
$ curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download" -H "If-Modified-Since: Wed, 28 Jan 2015 15:31:30 UTC"
HTTP/1.1 304 Not Modified
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 304 Not Modified
The Phrase Strings API supports JSONP for all GET requests in order to deal with cross-domain request issues. Just send a ?callback parameter along with the request to specify the Javascript function name to be called with the response content:
$ curl "https://api.phrase.com/v2/projects?callback=myFunction"
The response will include the normal output for that endpoint, along with a meta section including header data:
myFunction({
{
"meta": {
"status": 200,
...
},
"data": [
{
"id": "1234abcd1234abc1234abcd1234abc"
...
}
]
}
});
To authenticate a JSONP request, you can send a valid access token as the ?access_token parameter along the request:
$ curl "https://api.phrase.com/v2/projects?callback=myFunction&access_token=ACCESS-TOKEN"
GET /v2/projects/:project_id/translations
List excluded translations for the given project which start with the
term PhraseApp.
| Name | Type | Description |
|---|---|---|
sortoptional |
string |
Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name |
orderoptional |
string |
Order direction. Can be one of: asc, desc. Default: asc |
qoptional |
string |
Specify a query to find translations by content (including wildcards). Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size). The following qualifiers are supported in the query:
|
curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true" \
-u USERNAME_OR_ACCESS_TOKEN
phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true' \
--access_token <token>
GET /v2/projects/:project_id/translations
List unverified translations for the given project which start with the
term PhraseApp and are not verified.
| Name | Type | Description |
|---|---|---|
sortoptional |
string |
Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name |
orderoptional |
string |
Order direction. Can be one of: asc, desc. Default: asc |
qoptional |
string |
Specify a query to find translations by content (including wildcards). Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size). The following qualifiers are supported in the query:
|
curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true" \
-u USERNAME_OR_ACCESS_TOKEN
phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true' \
--access_token <token>
PATCH /v2/projects/:project_id/translations/verify
Verify all translations that are matching the query my dog.
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to find translations by content (including wildcards). Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size). The following qualifiers are supported in the query:
|
sortoptional |
string |
Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name |
orderoptional |
string |
Order direction. Can be one of: asc, desc. Default: asc |
curl "https://api.phrase.com/v2/projects/:project_id/translations/verify" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"my dog unverified:true","sort":"updated_at","order":"desc"}' \
-H 'Content-Type: application/json'
phrase translations verify \
--project_id <project_id> \
--data '{"query":""my dog unverified:true"", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
GET /v2/projects/:project_id/keys
Find updated keys with with the updated_at qualifier like
updated_at:>=2013-02-21T00:00:00Z. This example returns keys that have
been updated on or after 2013-02-21.
| Name | Type | Description |
|---|---|---|
sortoptional |
string |
Sort by field. Can be one of: name, created_at, updated_at. Default: name |
orderoptional |
string |
Order direction. Can be one of: asc, desc. Default: asc |
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
locale_id |
curl "https://api.phrase.com/v2/projects/:project_id/keys?sort=updated_at&order=desc&q=updated_at:%3E=2013-02-21T00:00:00Z&locale_id=abcd1234abcd1234abcd1234abcd1234" \
-u USERNAME_OR_ACCESS_TOKEN
phrase keys list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query "updated_at:>=2013-02-21T00:00:00Z" \
--locale_id abcd1234abcd1234abcd1234abcd1234 \
--access_token <token>
GET /v2/projects/:project_id/keys
Keys with certain tags can be filtered with the qualifier tags:.
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
PATCH /v2/projects/:project_id/keys/tag
Add the tags landing-page and release-1.2 to all keys that start
with dog and are translated in the locale
abcd1234abcd1234abcd1234abcd1234.
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
tags |
string |
Tag or comma-separated list of tags to add to the matching collection of keys |
locale_idoptional |
id |
Locale used to determine the translation state of a key when filtering for untranslated or translated keys. |
curl "https://api.phrase.com/v2/projects/:project_id/keys/tag" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
-H 'Content-Type: application/json'
phrase keys tag \
--project_id <project_id> \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
PATCH /v2/projects/:project_id/keys/untag
Remove the tags landing-page and release-1.2 from all keys that
start with dog and are translated in the locale
abcd1234abcd1234abcd1234abcd1234.
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
tags |
string |
Tag or comma-separated list of tags to remove from the matching collection of keys |
locale_idoptional |
id |
Locale used to determine the translation state of a key when filtering for untranslated or translated keys. |
curl "https://api.phrase.com/v2/projects/:project_id/keys/untag" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
-H 'Content-Type: application/json'
phrase keys untag \
--project_id <project_id> \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
GET /v2/projects/:project_id/keys
Example query my dog
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
My dog is lazy my dog is lazy angry dog in my house
GET /v2/projects/:project_id/keys
Example query "my dog is lazy" (note backslashes before any whitespace
character in the example query)
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
My dog is lazy
my dog is lazy
angry dog in my house
GET /v2/projects/:project_id/keys
Example query *dog is*
| Name | Type | Description |
|---|---|---|
qoptional |
string |
Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are also supported in the search term:
|
My dog is lazy
my dog is lazy
angry dog in my house
POST /v2/projects/:project_id/uploads
Suppose you have an excel file where the 'A' column contains the key names, the 'B' column contains English translations, the 'C' column contains German translations and the 'D' column contains comments. Furthermore, the actual content starts in the second row, since the first row is reserved for a header. You can upload this file and import all translations at once!
| Name | Type | Description |
|---|---|---|
file |
file |
File to be imported |
file_format |
string |
File format. Auto-detected when possible and not specified. |
locale_mapping[en] |
string |
Name of the column containing translations for locale en. |
locale_mapping[de] |
string |
Name of the column containing translations for locale de. |
format_options[comment_column] |
string |
Name of the column containing descriptions for keys. |
format_options[tag_column] |
string |
Name of the column containing tags for keys. |
format_options[key_name_column] |
string |
Name of the column containing the names of the keys. |
format_options[first_content_row] |
string |
Name of the first row containing actual translations. |
curl "https://api.phrase.com/v2/projects/:project_id/uploads" \
-u USERNAME_OR_ACCESS_TOKEN \
-X POST \
-F file=@/path/to/my/file.xlsx \
-F file_format=xlsx \
-F locale_mapping[en]=B \
-F locale_mapping[de]=C \
-F format_options[comment_column]=D \
-F format_options[tag_column]=E \
-F format_options[key_name_column]=A \
-F format_options[first_content_row]=2
phrase uploads create \
--project_id <project_id> \
--file /path/to/my/file.xlsx \
--file_format xlsx \
--locale_id abcd1234cdef1234abcd1234cdef1234 \
--tags awesome-feature,needs-proofreading \
--locale_mapping '{"en": "B", "de": "C"}' \
--format_options '{"comment_column": "D", "tag_column": "E", "key_name_column": "A", "first_content_row": "2"}' \
--access_token <token>