Usage examples - Phrase Developer Hub

Learn how to work more efficiently with Phrase Strings API v2 with these workflow-oriented examples. Most examples use the q parameter, which accepts a qualifier-based search syntax. Qualifiers let you filter keys and translations by tag, verification status, date range, and more. Qualifiers can be combined in a single query string (space-separated). Note that search results are drawn from an index and may lag behind recent writes by a few minutes on large projects. Use these examples as starting points for bulk operations such as verifying, tagging, or exporting filtered subsets of your localization data.

To authenticate, pass your access token in the Authorization header. See Authentication for how to obtain a token.

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/abcd1234abcd1234abcd1234abcd1234/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true' \
--access_token <token>

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "content": "PhraseApp welcome message",
    "unverified": false,
    "excluded": true,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234abcd1234abcd1234abcd1234",
      "name": "home.welcome"
    },
    "locale": {
      "id": "abcd1234abcd1234abcd1234abcd1234",
      "name": "en-US",
      "code": "en-US"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

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/abcd1234abcd1234abcd1234abcd1234/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true' \
--access_token <token>

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "content": "PhraseApp welcome message",
    "unverified": true,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234abcd1234abcd1234abcd1234",
      "name": "home.welcome"
    },
    "locale": {
      "id": "abcd1234abcd1234abcd1234abcd1234",
      "name": "en-US",
      "code": "en-US"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

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/abcd1234abcd1234abcd1234abcd1234/translations/verify" \
  -H "Authorization: token YOUR_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>

Response (200 OK)

{
  "records_affected": 23
}

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/abcd1234abcd1234abcd1234abcd1234/keys?sort=updated_at&order=desc&q=updated_at:%3E=2013-02-21T00:00:00Z&locale_id=abcd1234abcd1234abcd1234abcd1234" \
  -H "Authorization: token YOUR_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>

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "name": "home.welcome",
    "created_at": "2013-02-21T08:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "tags": ["landing-page"]
  }
]

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/abcd1234abcd1234abcd1234abcd1234/keys?q=tags:admin" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

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

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "name": "admin.dashboard.title",
    "tags": ["admin"],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

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`	Required. Tag or comma-separated list of tags to add to the matching collection of keys
`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/abcd1234abcd1234abcd1234abcd1234/keys/tag" \
  -H "Authorization: token YOUR_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>

Response (200 OK)

{
  "records_affected": 5
}

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`	Required. Tag or comma-separated list of tags to remove from the matching collection of keys
`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/abcd1234abcd1234abcd1234abcd1234/keys/untag" \
  -H "Authorization: token YOUR_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>

Response (200 OK)

{
  "records_affected": 5
}

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/abcd1234abcd1234abcd1234abcd1234/keys?q=my%20dog" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

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

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "name": "my.dog.is.lazy",
    "tags": [],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

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/abcd1234abcd1234abcd1234abcd1234/keys?q=name:my%5C%20dog%5C%20is%5C%20lazy" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

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

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "name": "my.dog.is.lazy",
    "tags": [],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

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/abcd1234abcd1234abcd1234abcd1234/keys?q=*dog%20is*" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

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

Response (200 OK)

[
  {
    "id": "abcd1234abcd1234abcd1234abcd1234",
    "name": "my.dog.is.lazy",
    "tags": [],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

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`	Required. File to be imported
`file_format`	`string`	Required. 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/abcd1234abcd1234abcd1234abcd1234/uploads" \
  -H "Authorization: token YOUR_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>

Response (200 OK)

{
  "id": "abcd1234abcd1234abcd1234abcd1234",
  "filename": "file.xlsx",
  "format": "xlsx",
  "state": "success",
  "summary": {
    "translation_keys_created": 10,
    "translation_keys_updated": 2,
    "translation_keys_unmentioned": 0,
    "translations_created": 20,
    "translations_updated": 4
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Errors

Status	Code	Cause	Remediation
400	`bad_request`	Malformed query string or invalid qualifier in `q` parameter.	Check the qualifier syntax; ensure date values use ISO 8601 format.
401	`unauthorized`	Missing or invalid access token.	Pass a valid token via `Authorization: token <token>`.
403	`forbidden`	The token does not have access to the specified project.	Verify the token has read/write access to the project.
404	`not_found`	The specified `project_id` does not exist or is not accessible.	Confirm the project ID is correct and the token has project access.
422	`unprocessable_entity`	Required parameter missing (e.g., `tags` not provided for tag operations).	Include all required parameters in the request body.

​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

​Errors

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

Errors