CLI

Using the CLI (Strings)

Content is machine translated from English by Phrase Language AI.

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

Basic Usage

Control how the client pushes and pulls files by editing the .phrase.yml configuration file.

  1. Initialize a project.

    Initialize project by running phrase init. This defines preferred locale file format, source files and more:

    $ phrase init
  2. Upload locale files.

    Use the push subcommand to upload locale files:

    $ phrase push
  3. Download locale files.

    Use the pull subcommand to download the most recent locale files back into a project:

    $ phrase pull
  4. 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
 

Access and Authentication

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 update_translations 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 the translation_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 the translation_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
 

Complex Usage

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
 
 
Was this article helpful?

Sorry about that! In what way was it not helpful?

The article didn’t address my problem.
I couldn’t understand the article.
The feature doesn’t do what I need.
Other reason.

Note that feedback is provided anonymously so we aren't able to reply to questions.
If you'd like to ask a question, submit a request to our Support team.
Thank you for your feedback.