Create a CLI Configuration File (Strings)

Content is machine translated from English by Phrase Language AI.

Prerequisites

API access token with read write scope
Strings project ID shown in the API tab of the project settings
Basic YAML knowledge, including indentation
Git read and write permissions if the repository will run phrase push or phrase pull in CI

To automatically create a configuration file, follow these steps:

From the command line, type phrase init to create a .phrase.yml file.

The configuration wizard starts in the CLI.
Provide:
- Access token
  
  Paste or hit Enter to let $PHRASE_ACCESS_TOKEN be used
- Strings Project ID (e.g. abcdef1234567890abcdef1234567890)
- Locale file format (e.g. json, rails_yaml, ios_strings)
- Local path
  
  Glob or exact path to locale files in the project codebase (e.g. config/locales/*.json)

A basic .phrase.yml file is created in the current directory.

Tip

Supply flags to skip the wizard entirely, for example phrase init --access_token=$PHRASE_ACCESS_TOKEN --project_id=... --file_format=ios_strings --path='ios/*.strings'.

If using a manually created or copied configuration file, place it in one of these locations:

The current working directory (pwd) in which the CLI client is called.
The home directory of the current user ($HOME in Unix, $HomePath in Windows).
The path specified in the PHRASEAPP_CONFIG environment variable.
Path to configuration file via the --config flag (e.g. /some/path/to/phrase.yml).

CLI Options Overview

Sample configuration file.

Global Settings

Key	Type	Required	Description
`phrase.access_token`	string	Yes	Personal access token.
`phrase.project_id`	string	Yes	Public project ID shown in Strings project settings.
`phrase.file_format`	string	Yes	Default locale file format (API extension).
`phrase.locale_mapping`	object	No	Maps Phrase locale IDs to custom names for use in file paths with the `<locale_name>` placeholder. This is useful for platforms with non-standard naming conventions, like Android. If a locale is not specified in the mapping, its standard Phrase locale name is used by default.

Push: Sources

Key	Type	Required	Description
`push.sources[].file`	path	Yes	Relative path to file(s) to push, e.g. `./path/to/file/<locale_code>.json`. Supports `<locale_name>`, `<locale_code>`, `<tags>`.
`push.sources[].project_id`	string		Override the global `project_id` for this specific file source. Useful when pushing files to multiple Phrase projects from the same configuration file.

Push: Parameters

Parameter	Type	Default	Description
`file_format`	string	header	Override file format for this source.
`locale_id`	string	—	Locale name (e.g. `en-US`) or public locale ID.
`tags`	string	—	Comma-separated tags for new keys.
`update_translations`	boolean	`false`	Update existing translations with file content.
`update_translation_keys`	boolean	`true`	Pass `false` here to prevent new keys from being created and existing keys updated.
`update_descriptions`	boolean	`false`	Update key descriptions; empty descriptions overwrite existing.
`skip_upload_tags`	boolean	`false`	Upload tags are not created.
`skip_unverification`	boolean	`false`	Updated translations are not unverified.
`file_encoding`	string	—	File encoding: `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, or `ISO-8859-1`.
`locale_mapping`	object	—	(Excel/CSV only) Map locale codes to column names, e.g. `{"en": "C", "de": "D"}` for parsing translations. This is distinct from the top-level `locale_mapping` used for file paths.
`autotranslate`	boolean	`false`	Auto-fetch translations for the uploaded language.
`mark_reviewed`	boolean	`false`	Mark imported translations as reviewed (advanced review workflow must be enabled).

Push: Format Options

All available format options are supported in the CLI configuration. See Sample configuration file for examples.

Pull: Targets

Key	Type	Required	Description
`pull.targets[].file`	path	Yes	Relative path for pulled locale files, e.g. `./Radio.de/<locale_code>.lproj/Localizable.strings`.
`pull.targets[].project_id`	string		Override the global `project_id` for this specific pull target. Enable pulling translations from multiple Phrase projects using the same configuration file.

Pull: Parameters

Parameter	Type	Default	Description
`file_format`	string	—	Must be `strings`.
`locale_id`	string	—	Locale name (e.g. `en-US`) or public locale ID.
`tags`	string	—	Comma-separated tags to filter which keys to pull.
`include_empty_translations`	boolean	`false`	Include keys without any translations.
`exclude_empty_zero_forms`	boolean	`false`	Exclude zero-form plurals when empty.
`include_translated_keys`	boolean	`true`	Include keys that already have translations.
`keep_notranslate_tags`	boolean	`false`	Preserve `[NOTRANSLATE]` tags in output.
`encoding`	string	—	File encoding: `UTF-8`, `UTF-16`, `UTF-16BE`, `UTF-16LE`, or `ISO-8859-1`.
`include_unverified_translations`	boolean	`true`	If `false`, exclude unverified translations.
`use_last_reviewed_version`	boolean	`false`	If `true`, use the last reviewed version (requires advanced review workflow).
`fallback_locale_id`	string	—	Fallback locale to use for missing translations.

Pull: Format Options

All available format options are supported in the CLI configuration. See Sample configuration file for examples.

Multiple configurations

In monorepos, place one configuration file in each package and run the CLI from the corresponding subfolder, or point CI jobs to different configuration files with the --config option.

Git integration

GitLab:

The .phrase.yml configuration file must be present in the repository. The file defines which files to import (pull) or export (push) from the repository.
Read and write access are required for the repository.
Incorrectly defined configuration files may cause errors. Ensure that the file contains at least one push and one pull target, correct file formats and the correct setting of the update_translations parameter.
Use GitLab 9.5 or newer to ensure API compatibility.

GitHub:

The .phrase.yml configuration file must be present in the repository. The file defines which files to import (pull) or export (push) from the repository.
Read and write access are required for the repository.
Incorrectly defined configuration files may cause errors. Ensure that the file contains at least one push and one pull target, correct file formats and the correct setting of the update_translations parameter.
A GitHub access token for the scope of the repository (public_repo if synchronizing with a public repository).
If SSO is enabled in GitHub, it must also be enabled for the access token.
The phrase_translations branch cannot be protected.
Ensure repository settings do not require signed commits.

BitBucket:

The .phrase.yml configuration file must be present in the repository. The file defines which files to import (pull) or export (push) from the repository.
Read and write access are required for the repository.
Incorrectly defined configuration files may cause errors. Ensure that the file contains at least one push and one pull target, correct file formats and the correct setting of the update_translations parameter.

phrase_configuration_overview.yml
(8 KB)