Using the CLI (Strings)

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

Sample configuration file.

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

Setting environment variables works differently on different platforms. Storing the access token in the .phrase.yml configuration file is recommended.

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.

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.

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:

$ 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:

$ 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

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 structuring localization files 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 configuratoin 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