Modify the CLI Configuration File (Strings)

Push

$ phrase push 

The push command uploads files found in local project directories. Use the .phrase.yml file to specify files for upload and set any additional parameters. The <tag> placeholder can also be used to download keys into separate files based on their tags.

Pull

$ phrase pull 

Similar to the push command with the exception globbing cannot be used. When using placeholders, use <locale_name> whenever possible. To pull a file with keys that have a specific tag, use the tags parameter:

phrase:
  pull:
    targets:
    - file: path/to/file/<locale_name>.yml
      params:
        tags:tag_name

To use the <tag> placeholder, the desired tags must be listed in the params section.

Parameters

The push and pull commands can be configured within the .phrase.yml file.

Push example:

push:
  sources:
  - file: ./locales/en.json
    params:
      update_translations: true 

Pull example:

pull:
  targets:
  - file: "./locales/example.yml"
    params:
      include_unverified_translations: true

Depending on file format, format options can be applied to the parameter section. Format options can be applied to uploads, downloads or both.

Format examples:

params:
  format_options:
    convert_placeholder: true

Some file formats allow greater control over the file syntax:

phrase:
  pull:
    targets:
    - file: file.xml
      params:
        format_options:
          convert_placeholder: true

  push:
    sources:
    - file: file.csv
      params:
        format_options:
          column_separator: ";"

The following placeholders and globbing operators can be placed in the paths within your file entries:

Globbing

* and ** are globbing operators. A single asterisk * skips any folder in a path. The double asterisk ** is like the standard globbing operator and matches any character for recursive, non-exhaustive matching.

Examples:

# a file pattern

./abc/**/*.yml

# with a few files on your system

./abc/defg/en.yml

./abc/es.yml

./fr.yml

# selects

./abc/defg/en.yml

./abc/es.yml

When using the pull command to download files, provide an explicit file pattern such as ./abc/defg/<locale_name>.yml instead of ./**/*.yml.

All uploads are processed asynchronously. To wait for uploads, apply the --wait  flag. The push will wait for each file upload and returns whether it failed or succeeded.

Upload a file to specified locale

Upload the en.json file to the ./locales/ directory with the given locale_id (locale must already exist).

Update_translations is set to false, so only new keys and translations are imported. If set to true, the client would also import local changes to existing translations, overwriting any already present content.

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: nested_json

  push:
    sources:
    - file: ./locales/en.json
      params:
        update_translations: false
        locale_id: YOUR_LOCALE_ID # the locale must exist remotely

Ruby on Rails: upload specified file type

Upload all files ending with .yml located in ./config/locales/. Ruby on Rails YAML files contain locale information, so there is no need to specify the locale explicitly. Update_translations is set to true, so all changes to translations will be imported with any existing data being overwritten.

phrase:
  push:
    sources:
    - file: ./config/locales/*.yml
      params:
        update_translations: true
        file_format: yml

Match iOS strings

To match all iOS strings files with files named Localizable.strings in .lproj folders.

The <locale_code> is everything that matches after / and before .lproj to create and identify locales.

The update_translations parameter is omitted and has the same effect as setting it to false.

phrase:
  push:
    sources:
    - file: "./<locale_code>.lproj/Localizable.strings"
      params:
        file_format: strings

Maintain multiple Strings projects for one localization project

Edit the configuration file to limit the scope of projects by splitting the translations into smaller categories.

Modify the configuration file to suit requirements, then check it into the source control or version control system.

Rails

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

  push:
    sources:
    - file: "./config/locales/*.yml"

  pull:
    targets:
    - file: "./config/locales/<locale_name>.yml"

iOS strings

phrase:

  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: "strings"

  push:
    sources:
    - file: "./<locale_code>.lproj/Localizable.strings"

  pull:
    targets:
    - file: "./<locale_code>.lproj/Localizable.strings"
    - file: "./<locale_code>.lproj/Localizable.stringsdict"
      params:
        #file_format can be overwritten
        file_format: "stringsdict"

Android XML

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

Explicitly set locales example

Example 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

Multi-platform example

Automatically push and pull translations for multiple targets in one configuration. 

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: nested_json

  push:
    sources:
      # Web JSON
      - file: "apps/web/src/assets/i18n/.json"
        params:
          file_format: nested_json
          locale_id: LOCALE_ID
      # Android XML
      - file: "apps/android/app/src/main/res/values-/strings.xml"
        params:
          file_format: android
          locale_id: LOCALE_ID
      # iOS Strings
      - file: "apps/ios/.lproj/Localizable.strings"
        params:
          file_format: strings
          locale_id: LOCALE_ID

  pull:
    targets:
      - file: "apps/web/src/assets/i18n/.json"
        params:
          file_format: nested_json
          locale_id: LOCALE_ID
      - file: "apps/android/app/src/main/res/values-/strings.xml"
        params:
          file_format: android
          locale_id: LOCALE_ID
      - file: "apps/ios/.lproj/Localizable.strings"
        params:
          file_format: strings
          locale_id: LOCALE_ID