Using the CLI (Strings)

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

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 Strings 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.

Authentication using Platform access token

Platform API tokens are not accepted directly by the Strings CLI. Users must first exchange them for a short-lived product access token (JWT) and then use the returned token through one of the following options:

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.

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.

Instead of defining a separate pull target for each locale, use the global locale_mapping setting combined with the <locale_name> placeholder. The CLI will use the custom name from the mapping for the corresponding locale and fall back to the default Phrase locale code for all other languages.

Example:

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: "xml"

  # Map Phrase locales to Android-specific directory names
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # Source file is the default language, mapped to 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # Must match the source locale in Phrase

  pull:
    targets:
      # Use <locale_name> placeholder which will be replaced by the mapping
      - file: ./app/src/main/res/<locale_name>/strings.xml