> ## Documentation Index > Fetch the complete documentation index at: https://developers.phrase.com/llms.txt > Use this file to discover all available pages before exploring further. # Download a locale > Download a locale in a specific file format. ## OpenAPI ````yaml /openapi/phrase-strings.json get /projects/{project_id}/locales/{id}/download openapi: 3.0.3 info: title: Phrase Strings API Reference version: 2.0.0 description: >- 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. contact: name: Phrase Support url: https://developers.phrase.com/api/ email: support@phrase.com x-logo: url: https://developers.phrase.com/images/phrase-logo.svg backgroundColor: '#03eab3' altText: Phrase Strings termsOfService: https://phrase.com/terms/ license: name: MIT url: https://choosealicense.com/licenses/mit/ servers: - url: https://api.phrase.com/v2 description: EU production server - url: https://api.us.app.phrase.com/v2 description: US production server security: - Token: [] - Basic: [] tags: - name: Accounts - name: Authorizations description: > The endpoints provided by the Authorizations API are **only accessible via Basic authentication with email and password**. When creating a new authorization, the new access token for this authorization will be returned in the immediate response but not later, due to security reasons. When accessing authorizations later, you will only see the last eight chars of the token in plain text (`token_last_eight`) and the SHA256 digest of the token for reference (`hashed_token`). For instructions on how authorization in general works, see our [Auth Guide](#overview--authentication). ### Scopes When creating or updating an OAuth authorization, you can define a list of scopes to limit the access that can be performed by that authorization. #### Available Scopes
Scope Description
read Read projects, locales, keys, translations, orders
write Write projects, locales, keys, translations but not orders
orders.create Create and confirm orders
team.manage Manage invitations and members
- name: Blacklisted Keys - name: Branches description: > ### Branch creation Branches will be created asynchronously. State of branch creation is returned as state. #### Available States
State Description
initialized Data received.
processing Branch is currently creating.
success Branch was created successfully
error Branch creation failed.
- name: Comments - name: Comment Reactions - name: Comment Replies - name: Custom Metadata - name: Distributions - name: Documents - name: Figma Attachments - name: Formats - name: Glossaries - name: Glossary Terms - name: Glossary Term Translations - name: ICU - name: Invitations description: > With the invitation endpoint you can [manage and invite users](https://support.phrase.com/hc/en-us/articles/5709742418716) to Phrase Strings via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. - name: Job Annotations description: > The job annotations endpoints allow you to create, update and delete annotations for jobs and job locales. Annotations are used to add metadata to a job or job locale. - name: Job Comments - name: Job Locales - name: Job Template Locales - name: Job Templates - name: Jobs - name: Keys - name: Linked Keys - name: Locales - name: Locale Downloads - name: Members description: > With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. - name: Notifications - name: Notification Groups - name: Orders description: > ### List of categories [TextMaster] When ordering translations from TextMaster, you need to specify a category ID along with your order. See this list for information on the category ID and their equivalent description.
Category ID Description
C001Agriculture
C002Aerospace
C003Animals/Pets/Plants
C004Arts/Culture/Literature
C005Automotive/Transportation
C006Computers/Technology/Software
C007Telecom
C008Real Estate/Construction/Building
C009Consumer Goods
C010Education
C011Entertainment
C012Ecology/Environment
C013Health/Biotechnology/Pharma
C014Internet
C015Policy/Government/Public
C016Publishing/Media/Communication
C017Religion
C018Food/Beverages
C019Retail
C020Fashion/Luxury/Textiles
C021Travel/Tourism
C022Natural Resources/Energy
C023Banking/Financial Services/Insurance
C024Legal Affairs/Tax/Law
C025Raw Materials/Industrial Goods
C026Lifestyle/Leisure/Hobbies
C027Sports
C028Home/Family/Friends/Children
C029Economy/Financial Markets
C030Science
C031Human Resources/Employment
C032Adult (Pornography, Violence, etc.)
- name: Organization Job Template Locales - name: Organization Job Templates - name: Projects - name: Quality - name: Releases - name: Release Triggers - name: Repo Syncs description: > The Repo Syncs API allows you to synchronize your Phrase projects with your code repositories. You can import translations from your repository to Phrase and export translations from Phrase to your repository. - name: Repo Sync Events - name: Reports - name: Search - name: Screenshot Markers - name: Screenshots - name: Spaces - name: Style guides - name: Tags - name: Teams - name: Translations - name: Uploads description: > ### Formats We support all common localization file formats. For a detailed overview, see our [Format Guide](https://support.phrase.com/hc/en-us/sections/6111343326364). ### Processing Uploads will be processed asynchronously and thus the data might not be imported yet although the upload is completed. Therefore we recommend to evaluate the returned state field for information on the import progress. #### Available States
State Description
initialized Data received.
waiting_for_preview Upload is waiting for preview to be finished.
waiting Upload is waiting for processing.
processing Upload is being processed, data is currently imported.
success Upload is complete and all data is imported.
error Upload or import process failed.
- name: Users - name: Variables - name: Versions / History - name: Webhooks - name: Webhook Deliveries paths: /projects/{project_id}/locales/{id}/download: get: tags: - Locales summary: Download a locale description: Download a locale in a specific file format. operationId: locale/download parameters: - $ref: '#/components/parameters/X-PhraseApp-OTP' - $ref: '#/components/parameters/If-Modified-Since' - $ref: '#/components/parameters/If-None-Match' - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/locale_id_as_id' - description: specify the branch to use example: my-feature-branch name: branch in: query schema: type: string - description: >- File format name. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364) for all supported file formats. example: yml name: file_format in: query schema: type: string - description: >- Limit results to keys tagged with a list of comma separated tag names. example: feature1,feature2 name: tags in: query schema: type: string - description: >- Limit download to tagged keys. This parameter is deprecated. Please use the "tags" parameter instead example: feature deprecated: true name: tag in: query schema: type: string - description: >- Indicates whether keys without translations should be included in the output as well. example: null name: include_empty_translations in: query schema: type: boolean - description: >- Indicates whether zero forms should be included when empty in pluralized keys. example: null name: exclude_empty_zero_forms in: query schema: type: boolean - description: >- Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys. example: null name: include_translated_keys in: query schema: type: boolean - description: Indicates whether [NOTRANSLATE] tags should be kept. example: null name: keep_notranslate_tags in: query schema: type: boolean - description: >- This option is obsolete. Projects that were created on or after Nov 29th 2019 or that did not contain emoji by then will not require this flag any longer since emoji are now supported natively. example: null deprecated: true name: convert_emoji in: query schema: type: boolean - description: >- Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364) for a list of options available for each format. Specify format options like this: `...&format_options[foo]=bar` example: null name: format_options in: query schema: type: object properties: {} style: deepObject explode: true - description: >- Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1". example: null name: encoding in: query schema: type: string - description: >- Indicates whether the locale file should skip all unverified translations. This parameter is deprecated and should be replaced with `include_unverified_translations`. example: null deprecated: true name: skip_unverified_translations in: query schema: type: boolean - description: if set to false unverified translations are excluded example: null name: include_unverified_translations in: query schema: type: boolean - description: >- 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 name: use_last_reviewed_version in: query schema: type: boolean - name: fallback_locale_id description: > 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`. in: query schema: type: string example: null - name: use_locale_fallback description: > 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](/en/api/strings/locales/update-a-locale#body-fallback-locale-id). Requires `include_empty_translations` to be set to `true`. Mutually exclusive with `fallback_locale_id`. in: query schema: type: boolean example: true - description: >- 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: null name: source_locale_id in: query schema: type: string - description: >- 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. example: prefix_ name: translation_key_prefix in: query schema: type: string - description: >- Only download translation keys containing the specified prefix, and remove the prefix from the generated file. example: null name: filter_by_prefix in: query schema: type: boolean - name: custom_metadata_filters in: query description: > 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. schema: type: object properties: {} style: deepObject explode: true - name: locale_ids description: Locale IDs or locale names in: query schema: type: array items: type: string example: - de - en - name: updated_since description: > 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`). in: query schema: type: string example: '2023-01-01T00:00:00Z' responses: '200': description: OK content: '*': schema: type: string format: binary headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' x-code-samples: - lang: Curl source: >- curl "https://api.phrase.com/v2/projects/:project_id/locales/:id/download?branch=my-feature-branch&file_format=yml&tags=feature1,feature2&tag=feature&custom_metadata_filters[tone]=friendly" \ -u USERNAME_OR_ACCESS_TOKEN - lang: CLI v2 source: |- phrase locales download \ --project_id \ --id \ --branch my-feature-branch \ --file_format yml \ --tags feature1,feature2 \ --tag feature \ --access_token components: parameters: X-PhraseApp-OTP: in: header name: X-PhraseApp-OTP description: Two-Factor-Authentication token (optional) required: false allowEmptyValue: false schema: type: string If-Modified-Since: description: >- Last modified condition, see [Conditional GET requests / HTTP Caching](/en/api/strings/pagination#conditional-get-requests-%2F-http-caching) (optional) explode: false in: header name: If-Modified-Since required: false schema: type: string style: simple If-None-Match: description: >- ETag condition, see [Conditional GET requests / HTTP Caching](/en/api/strings/pagination#conditional-get-requests-%2F-http-caching) (optional) explode: false in: header name: If-None-Match required: false schema: type: string style: simple project_id: in: path name: project_id description: Project ID required: true schema: type: string locale_id_as_id: in: path name: id description: Locale ID or locale name required: true schema: type: string headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: >- Timestamp of end of current time period as UNIX timestamp, see [Rate Limiting](/en/api/strings/pagination#rate-limiting) schema: type: integer responses: '400': description: Bad request headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '404': description: Not Found headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': description: Rate Limiting headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' securitySchemes: Token: type: apiKey in: header name: Authorization description: Enter your token in the format `token TOKEN` Basic: type: http scheme: basic ````