The Phrase Strings CLI tool helps navigate the API to manage projects and translations quickly from the command line instead of from curl requests.
If using the US data center, pass the host with phrase init --host https://api.us.app.phrase.com/v2
. If the configuration has already been generated, add this code:
phrase: host: https://api.us.app.phrase.com/v2
Control how the client pushes and pulls files by editing the .phrase.yml
configuration file.
-
Initialize a project.
Initialize project by running
phrase init
. This defines preferred locale file format, source files and more:$ phrase init
-
Upload locale files.
Use the
push
subcommand to upload locale files:$ phrase push
-
Download locale files.
Use the
pull
subcommand to download the most recent locale files back into a project:$ phrase pull
-
More subcommands.
To see a list of all available subcommands, run
phrase
without specifying a subcommand. To see all supported options for a specific subcommand, use the--help
flag:$ phrase locales list --help
Sample configuration file.
Escaping rules and quotes usage
When passing JSON objects on the command line, escaping rules and quotes usage may vary according to the shell used.
If using a Windows shell, enclose the whole JSON string in double quotes ""
, and escape double quotes within JSON using a backslash \
character. For example:
phrase locales create --project_id PROJECT123 --data "{\"name\":\"French\", \"code\":\"fr\"}" --access_token TOKEN123123
Accessing API endpoints
The client can be used to access all API endpoints. For example, to list all projects:
$ phrase projects list --access_token ACCESS_TOKEN
Authentication using Phrase credentials
Specify username with the --username
flag and the password will be requested:
$ phrase projects list --username user@example.com Password: ********
If two-factor authentication is activated for the user or organization, a valid multi factor token must be provided via the --tfa
flag:
$ phrase projects list --username user@example.com --tfa Password: ******** TFA: ********
Authentication using access token
Use the --access_token
flag to specify your access token:
$ phrase projects list --access_token ACCESS_TOKEN
or use the PHRASE_ACCESS_TOKEN
environment variable to store your token:
export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"
If two-factor authentication is activated, a valid multi factor token must be provided via the --x_phrase_app_otp
flag:
$ phrase projects list --access_token ACCESS_TOKEN --x_phrase_app_otp PASSWORD
Token can also be provided in interactive mode with the --tfa
flag:
$ phrase projects list --access_token ACCESS_TOKEN --tfa TFA: ********
The access token is read from the .phrase.yml
configuration file by default, but behavior can be overridden by using the mentioned flags or env variables and the token provided via the flag or environment variable is used instead. Tokens provided via flags override tokens provided via the environment variable.
When storing the .phrase.yml
file in a code repository, it is recommended to remove the token first and use alternative methods, such as passing the token through the environment or a command-line flag. Storing secret tokens directly in a repository can be a security issue.
Push and pull
Use the push and pull commands to upload and download locale files. Instead of command line arguments, push and pull rely on the configuration stored in the .phrase.yml
configuration file in the project root folder.
If the push has the
option set to true, the push overwrites the translations. Pull always overwrites translations in the local file.Example configuration for uploading and downloading locale files of a typical Rails application:
phrase: access_token: "ACCESS_TOKEN" project_id: "PROJECT_ID" file_format: "yml" push: sources: - file: "./config/locales/<locale_name>.yml" pull: targets: - file: "./config/locales/<locale_name>.yml"
Use the push command to upload locale files to the project identified by project_id
matching the de.yml
and en.yml
file in the config/locales folder. If there are new keys, these will be added to the localization file:
$ phrase push Uploading config/locales/de.yml Uploaded config/locales/de.yml successfully. Uploading config/locales/en.yml Uploaded config/locales/en.yml successfully.
Use the pull command to download locale files from the project identified by project_id
to their respective file paths. If there are new keys, these will be added to the project:
$ phrase pull Downloaded de to config/locales/de.yml Downloaded en to config/locales/en.yml
Rate limit support
The client supports the rate limit for locale downloads. When the rate limit is reached, the client waits until the rate limit has expired and continues downloading locales afterwards. The client displays rate limit exceeded, download will resume in x seconds.
Upload cleanup
The uploads cleanup command is provided to delete keys that are found in the project but are not contained in the uploaded file. After pushing locale files, deleting all keys that are not contained in a default locale or some other locale may be required:
$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>
Format options
Several formats, such as CSV, support additional format options during upload. Access these options by prefixing the options with --format_options
:
phrase uploads create \ --project_id PROJECT_ID \ --file ./en.csv \ --file_format csv \ --locale_mapping ‘{“en”:3, “de”:2}’ \ --format_options ‘{“key_index”:1}’ \ --access token YOUR_ACCESS_TOKEN
Translation key prefix
A translation key prefix prevents key collisions across different projects or files and improves traceability of translation keys. The CLI interface supports key prefix handling for both pull and push operations.
-
Push parameters:
-
translation_key_prefix
: The specified prefix is prepended to the translation keys being pushed.-
Use the
<file_path>
magic placeholder to automatically set thetranslation_key_prefix
to the current file path. The path has a maximum length of 255 characters.
-
-
-
Pull parameters:
-
translation_key_prefix
: This parameter allows the prefix to be subtracted from the translation key names during the pull operation.-
Use the
<file_path>
magic placeholder to automatically set thetranslation_key_prefix
to the current file path. The path has a maximum length of 255 characters.
-
-
filter_by_prefix
: A boolean option that filters translation keys based on the prefix before pulling them.
-
Example configuration of the phrase.yml
file:
phrase: access_token: access_token file_format: yml push: sources: - file: path/to/your/file.yml project_id: project_id params: locale_id: en translation_key_prefix: prefix_ pull: targets: - file: path/to/your/file.yml project_id: project_id params: translation_key_prefix: prefix_ filter_by_prefix: true
Curl commands example:
curl "https://api.phrase.com/v2/projects/:project_id/uploads?translation_key_prefix=prefix_" \ -u USERNAME_OR_ACCESS_TOKEN \ -X POST \ -F file=@/path/to/my/file.format \ -F file_format=format \ -F locale_id=locale_id
curl "https://api.phrase.com/v2/projects/:project_id/locales/:id/download?file_format=file_format&translation_key_prefix=prefix_&filter_by_prefix=true" \ -u USERNAME_OR_ACCESS_TOKEN
Proxy
If behind a proxy, specify proxy settings using the HTTPS_PROXY
environment variable:
export HTTPS_PROXY=https://user:password@host:port
Multiple localization files for one project
Use one file for each locale in a project. If tools or framework force the use of multiple files, see maintaining file structures for details on how to set up the project.
Multiple projects for one localization project
When working on a large localization project, distribute translations over multiple projects. Configure the CLI to work with multiple localization files for one localization project.
Format options
Some file formats allow specifying format options for greater control over file syntax. Specify format options in the .phrase.yml
configuration file::
phrase: pull: targets: - file: file.xml params: format_options: convert_placeholder: true push: sources: - file: file.csv params: format_options: column_separator: ";"
Configuration for Android projects
Android doesn’t use the standard ISO language codes as the file pattern. Specify the required pattern in .phrase.yml
.
Specify each locale explicitly in the .phrase.yml
file. This example shows a .phrase.yml
configuration with English as the default language, a German locale, and a German region locale for Austrian German:
phrase: access_token: ACCESS_TOKEN project_id: PROJECT_ID file_format: xml pull: targets: - file: ./app/src/main/res/values/strings.xml params: file_format: xml # Unique locale id for English locale_id: LOCALE_ID - file: ./app/src/main/res/values-de/strings.xml params: file_format: xml # Unique locale id for German locale_id: LOCALE_ID - file: ./app/src/main/res/values-de-rAU/strings.xml params: file_format: xml # Unique locale id for Austrian locale_id: LOCALE_ID push: sources: - file: ./app/src/main/res/values/strings.xml params: file_format: xml locale_id: LOCALE_ID - file: ./app/src/main/res/values-de/strings.xml params: file_format: xml locale_id: LOCALE_ID - file: ./app/src/main/res/values-de-rAU/strings.xml params: file_format: xml locale_id: LOCALE_ID