Usage examples

Learn how to work more efficiently with Phrase Strings API v2 with these workflow-oriented examples.

Find excluded translations with a certain content

GET /v2/projects/:project_id/translations

List excluded translations for the given project which start with the term PhraseApp.

Parameters

Name	Type	Description
`sort` (optional)	`string`	Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`. Default: `key_name`
`order` (optional)	`string`	Order direction. Can be one of: `asc`, `desc`. Default: `asc`
`q` (optional)	`string`	Specify a query to find translations by content (including wildcards). Note: Search is limited to 10,000 results and may not include recently updated data (depending on the project size). Supported qualifiers: - `id:translation_id,...` – comma-separated list of IDs - `tags:XYZ` – tag on the translation - `unverified:{true\|false}` – verification status - `reviewed:{true\|false}` – reviewed status - `excluded:{true\|false}` – exclusion status - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries

Example Request

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>

Find unverified translations with a certain content

GET /v2/projects/:project_id/translations

List unverified translations for the given project which start with the term PhraseApp and are not verified.

Parameters

Name	Type	Description
`sort` (optional)	`string`	Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`. Default: `key_name`
`order` (optional)	`string`	Order direction. Can be one of: `asc`, `desc`. Default: `asc`
`q` (optional)	`string`	Specify a query to find translations by content (including wildcards). Note: Search is limited to 10,000 results and may not include recently updated data (depending on the project size). Supported qualifiers: - `id:translation_id,...` – comma-separated list of IDs - `tags:XYZ` – tag on the translation - `unverified:{true\|false}` – verification status - `reviewed:{true\|false}` – reviewed status - `excluded:{true\|false}` – exclusion status - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries

Example Request

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>

Verify translations selected by query

PATCH /v2/projects/:project_id/translations/verify

Verify all translations that are matching the query my dog.

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to find translations by content (including wildcards). Note: Search is limited to 10,000 results and may not include recently updated data (depending on the project size). Supported qualifiers: - `id:translation_id,...` – comma-separated list of IDs - `tags:XYZ` – tag on the translation - `unverified:{true\|false}` – verification status - `reviewed:{true\|false}` – reviewed status - `excluded:{true\|false}` – exclusion status - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries
`sort` (optional)	`string`	Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`. Default: `key_name`
`order` (optional)	`string`	Order direction. Can be one of: `asc`, `desc`. Default: `asc`

Example Request

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>

Find recently updated keys

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.

Parameters

Name	Type	Description
`sort` (optional)	`string`	Sort by field. Can be one of: `name`, `created_at`, `updated_at`. Default: `name`
`order` (optional)	`string`	Order direction. Can be one of: `asc`, `desc`. Default: `asc`
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in a job - `translated:{true\|false}` – requires `locale_id` - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range filtering - `unmentioned_in_upload:upload_id` – keys not mentioned in given upload
`locale_id` (optional)	`string`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

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>

Find keys with a certain tag

GET /v2/projects/:project_id/keys

Keys with certain tags can be filtered with the qualifier tags:.

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – requires `locale_id` - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date - `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=tags:admin" \
  -u USERNAME_OR_ACCESS_TOKEN

phrase keys list \
--project_id <project_id> \
--query "tags:admin" \
--access_token <token>

Add tags to collection of keys

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.

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – requires `locale_id` - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date - `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload
`tags`	`string`	Tag or comma-separated list of tags to add to the matching collection of keys
`locale_id` (optional)	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

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>

Remove tags from collection of keys

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.

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – requires `locale_id` - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date - `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload
`tags`	`string`	Tag or comma-separated list of tags to remove from the matching collection of keys
`locale_id` (optional)	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

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>

Find keys with broad text match

GET /v2/projects/:project_id/keys

Example query my dog.

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – requires `locale_id` - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range filter - `unmentioned_in_upload:upload_id` – keys not mentioned in specific upload

Matches

My dog is lazy my dog is lazy angry dog in my house

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=my%20dog" \
  -u USERNAME_OR_ACCESS_TOKEN

phrase keys list \
--project_id <project_id> \
--query "my dog" \
--access_token <token>

Find keys with exact text match

GET /v2/projects/:project_id/keys

Example query "my dog is lazy" (note backslashes before any whitespace character in the example query)

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). Supported qualifiers: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – requires `locale_id` to be specified - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries - `unmentioned_in_upload:upload_id` – filter keys unmentioned within upload

Matches

~~My dog is lazy~~ my dog is lazy ~~angry dog in my house~~

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=name:my%5C%20dog%5C%20is%5C%20lazy" \
  -u USERNAME_OR_ACCESS_TOKEN

phrase keys list \
--project_id <project_id> \
--query "name:my\ dog\ is\ lazy" \
--access_token <token>

Find keys with wildcard character matching

GET /v2/projects/:project_id/keys

Example query *dog is*

Parameters

Name	Type	Description
`q` (optional)	`string`	Specify a query to do broad search for keys by name (including wildcards). The following qualifiers are supported in the search term: - `ids:key_id,...` – queries on a comma-separated list of IDs - `name:key_name,...` – exact key names (comma-separated; escape spaces, commas, and colons with `\\`) - `tags:tag_name,...` – filter for keys with certain tags - `uploads:upload_id,...` – filter for keys with certain uploads - `job:{true\|false}` – filter for keys mentioned in an active job - `translated:{true\|false}` – filter by translation status (requires `locale_id`) - `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date range - `unmentioned_in_upload:upload_id` – filter keys unmentioned within specific upload

Matches

My dog is lazy my dog is lazy ~~angry dog in my house~~

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=*dog%20is*" \
  -u USERNAME_OR_ACCESS_TOKEN

phrase keys list \
--project_id <project_id> \
--query '*dog is*' \
--access_token <token>

Upload an Excel file with several translations

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!

Parameters

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.

Example Request

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>

Guides

API Documentation

Find excluded translations with a certain content

Parameters

Example Request

Find unverified translations with a certain content

Parameters

Example Request

Verify translations selected by query

Parameters

Example Request

Find recently updated keys

Parameters

Example Request

Find keys with a certain tag

Parameters

Example Request

Add tags to collection of keys

Parameters

Example Request

Remove tags from collection of keys

Parameters

Example Request

Find keys with broad text match

Parameters

Matches

Example Request

Find keys with exact text match

Parameters

Matches

Example Request

Find keys with wildcard character matching

Parameters

Matches

Example Request

Upload an Excel file with several translations

Parameters

Example Request

Guides

API Documentation

​Find excluded translations with a certain content

​Parameters

​Example Request

​Find unverified translations with a certain content

​Parameters

​Example Request

​Verify translations selected by query

​Parameters

​Example Request

​Find recently updated keys

​Parameters

​Example Request

​Find keys with a certain tag

​Parameters

​Example Request

​Add tags to collection of keys

​Parameters

​Example Request

​Remove tags from collection of keys

​Parameters

​Example Request

​Find keys with broad text match

​Parameters

​Matches

​Example Request

​Find keys with exact text match

​Parameters

​Matches

​Example Request

​Find keys with wildcard character matching

​Parameters

​Matches

​Example Request

​Upload an Excel file with several translations

​Parameters

​Example Request

Find excluded translations with a certain content

Parameters

Example Request

Find unverified translations with a certain content

Parameters

Example Request

Verify translations selected by query

Parameters

Example Request

Find recently updated keys

Parameters

Example Request

Find keys with a certain tag

Parameters

Example Request

Add tags to collection of keys

Parameters

Example Request

Remove tags from collection of keys

Parameters

Example Request

Find keys with broad text match

Parameters

Matches

Example Request

Find keys with exact text match

Parameters

Matches

Example Request

Find keys with wildcard character matching

Parameters

Matches

Example Request

Upload an Excel file with several translations

Parameters

Example Request