Sign in

v1

latestOpenAPI 3.0.0Proprietary2026-07-26316155742.7 KB
Locale Downloads

Initiate async download of a locale

Prepare a locale for download in a specific file format.

post/projects/{project_id}/locales/{locale_id}/downloads

Path parameters

project_idstring required

Project ID

locale_idstring required

Locale ID

Headers

X-PhraseApp-OTPstring

Two-Factor-Authentication token (optional)

If-Modified-Sincestring

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

If-None-Matchstring

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

Request body

file_formatstring required

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

branchstring

specify the branch to use

tagsstring

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

include_empty_translationsboolean

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

exclude_empty_zero_formsboolean

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

include_translated_keysboolean

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

keep_notranslate_tagsboolean

Indicates whether [NOTRANSLATE] tags should be kept.

format_optionsobject

Additional formatting and render options. See the format guide for a list of options available for each format. Pass format options as a JSON object with key-value pairs corresponding to the option name and value. For example, to include comments in a Gettext file, pass {"include_comments": true}.

encodingstring

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

include_unverified_translationsboolean

if set to false unverified translations are excluded

use_last_reviewed_versionboolean

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.

locale_idsstring[]

Locale IDs or locale names

fallback_locale_idstring

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 unless fallback_for_unverified_translations is also set to true. Mutually exclusive with use_locale_fallback.

use_locale_fallbackboolean

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 unless fallback_for_unverified_translations is also set to true. Mutually exclusive with fallback_locale_id.

fallback_for_unverified_translationsboolean

If set to true, translations in a non-final state are replaced by the fallback locale's translation at export time. In the simple workflow, "non-final" means unverified. In the review workflow, it additionally includes translated (awaiting review). No stored translations are modified. Requires fallback_locale_id or use_locale_fallback to be set; a 422 validation error is returned otherwise.

source_locale_idstring

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.

custom_metadata_filtersobject

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.

translation_key_prefixstring

Download all translation keys, and remove the specified prefix where possible. Warning: this may create duplicate key names if other keys share the same name after the prefix is removed.

filter_by_prefixboolean

Only download translation keys containing the prefix specified by translation_key_prefix, and remove that prefix from the generated file. Requires translation_key_prefix to be set.

updated_sincestring

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 request

{
  "file_format": "yml",
  "branch": "my-feature-branch",
  "tags": "feature1,feature2",
  "include_empty_translations": true,
  "exclude_empty_zero_forms": true,
  "include_translated_keys": true,
  "keep_notranslate_tags": true,
  "format_options": {
    "format_options": {
      "foo": "bar"
    }
  },
  "encoding": "UTF-8",
  "include_unverified_translations": true,
  "locale_ids": [
    "de",
    "en"
  ],
  "fallback_locale_id": "abcd1234abcd1234abcd1234abcd1234",
  "source_locale_id": "abcd1234abcd1234abcd1234abcd1234",
  "translation_key_prefix": "prefix_",
  "updated_since": "2023-01-01T00:00:00Z"
}

Response

Created

idstring
status'processing' | 'completed' | 'error'

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

errorstring
created_atstring date-time
completed_atstring date-time

Example response

{
  "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"
}