Skip to main content
POST
/
projects
/
{project_id}
/
locales
/
{locale_id}
/
downloads
cURL
curl "https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","file_format":"yml","tags":"feature1,feature","custom_metadata_filters":{"tone":"friendly"}}' \
  -H 'Content-Type: application/json'
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "status": "completed",
  "result": {
    "url": "https://example.com/locales/abcd1234cdef1234abcd1234cdef1234/download?file_format=yml"
  },
  "params": {
    "file_format": "yml",
    "locale_id": "abcd1234cdef1234abcd1234cdef1234",
    "tags": "feature1,feature2",
    "branch": "my-feature-branch",
    "include_empty_translations": true,
    "include_translated_keys": true,
    "include_unverified_translations": true
  },
  "created_at": "2015-01-28T09:52:53Z",
  "completed_at": "2015-01-28T09:52:53Z"
}

Authorizations

​
Authorization
string
header
required

Enter your token in the format token TOKEN

Headers

​
X-PhraseApp-OTP
string

Two-Factor-Authentication token (optional)

​
If-Modified-Since
string

Last modified condition, see Conditional GET requests / HTTP Caching (optional)

​
If-None-Match
string

ETag condition, see Conditional GET requests / HTTP Caching (optional)

Path Parameters

​
project_id
string
required

Project ID

​
locale_id
string
required

Locale ID

Body

application/json
​
file_format
string
required

File format name. See the format guide for all supported file formats.

Example:

"yml"

​
branch
string

specify the branch to use

Example:

"my-feature-branch"

​
tags
string

Limit results to keys tagged with a list of comma separated tag names.

Example:

"feature1,feature2"

​
include_empty_translations
boolean

Indicates whether keys without translations should be included in the output as well.

Example:

true

​
exclude_empty_zero_forms
boolean

Indicates whether zero forms should be included when empty in pluralized keys.

Example:

true

​
include_translated_keys
boolean

Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys.

Example:

true

​
keep_notranslate_tags
boolean

Indicates whether [NOTRANSLATE] tags should be kept.

Example:

true

​
format_options
object

Additional formatting and render options. See the format guide for a list of options available for each format. Specify format options like this: ...&format_options[foo]=bar

​
encoding
string

Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".

Example:

"UTF-8"

​
include_unverified_translations
boolean

if set to false unverified translations are excluded

Example:

true

​
use_last_reviewed_version
boolean

If set to true the last reviewed version of a translation is used. This is only available if the review workflow is enabled for the project.

Example:

null

​
locale_ids
string[]

Locale IDs or locale names

Example:
["de", "en"]
​
fallback_locale_id
string

If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to true. Mutually exclusive with use_locale_fallback.

Example:

"abcd1234abcd1234abcd1234abcd1234"

​
use_locale_fallback
boolean

If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used. Fallback locale is defined in locale's settings. Requires include_empty_translations to be set to true. Mutually exclusive with fallback_locale_id.

Example:

false

​
source_locale_id
string

Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a tag parameter indicating a specific job.

Example:

"abcd1234abcd1234abcd1234abcd1234"

​
custom_metadata_filters
object

Custom metadata filters. Provide the name of the metadata field and the value to filter by. Only keys with matching metadata will be included in the download.

​
updated_since
string

Only include translations and keys that have been updated since the given date. The date must be in ISO 8601 format (e.g., 2023-01-01T00:00:00Z).

Example:

"2023-01-01T00:00:00Z"

Response

Created

​
id
string
​
status
enum<string>

The status of the download request. Possible values are processing, completed, and error.

Available options:
processing,
completed,
error
​
result
object
​
params
object

The parameters of the download request.

​
error
string
​
created_at
string<date-time>
​
completed_at
string<date-time>