CLI

Modify the CLI Configuration File (Strings)

The .phrase.yml file is used to store reused command line arguments.

Supported arguments:

  • project_id

    The ID of a project.

  • file_format

    The file format used when one is not explicitly specified within source and target entries.

  • per_page

    The number of items returned in paginated responses.

Sample configuration file.

Push and Pull

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

Parameters

The push and pull commands can be configured within the .phrase.yml file. Push options are the same as for the uploads API endpoint and pull options are the same as the locales download API endpoint.

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

Format Options

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: ";"

Placeholders and Globbing

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

  • <locale_name>

    The unique locale name.

  • <locale_code>

    The RFC 5646-compliant locale identifier. The locale code does not have to be unique, so multiple locales with different names can exist with the same code.

  • <tag>

    Use tags to group keys. Tags can be used to maintain the original file structure.

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.

Waiting for Uploads

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.

Use Cases

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

Configuration Examples for Frameworks

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.

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

  push:
    sources:
    - file: "./res/values-<locale_code>/strings.xml"

  pull:
    targets:
    - file: "./res/values-<locale_code>/strings.xml"

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