PhraseApp Client Configuration

Configuration file

You can use the .phraseapp.yml to store repeating command line arguments.

The following arguments are supported:

Name Description
access_token Your PhraseApp access token
project_id The ID of your PhraseApp project
file_format File default file format used (unless specified explicitly within sources and targets entries)
per_page Number of items returned in paginated responses
defaults Default parameters for specific API actions

This is the original long version of the command to list all keys for a project:

$ phraseapp keys list --access-token 3d7e6598d955bfcabaf1b9459df5692ac4c28a17793 --sort updated_at --order desc 5c05692a2a995c0c45c0c3cbfcab1

You can move some of the arguments to your .phraseapp.yml configuration file:

phraseapp:
  access_token: 3d7e6598d955bfcabaf1b9459df5692ac4c28a17793
  project_id: 5c05692a2a995c0c45c0c3cbfcab1
  file_format: yml
  ...

With this configuration in place, it is now sufficient to just type:

$ phraseapp keys list --sort updated_at --order desc
Default parameters for API actions

You can also provide default parameters for specific API actions:

phraseapp:
  ...
  defaults:
    keys/list:
      sort: "updated_at"
      order: "desc"

Now it is sufficient to just type:

$ phraseapp keys list

We recommend moving arguments to the configuration file to make using the command line easier and more consistent (e.g. across your team members).

Location

The .phraseapp.yml configuration file is expected to be in one of these locations:

  • the directory the CLI client was called in, or
  • the current user’s home directory (on unix $HOME and on windows $HomePath) or
  • the path specified in the PHRASEAPP_CONFIG environment variable

Init

Create your .phraseapp.yml configuration file by running

$ phraseapp init

You will need to specify the

  • access token (can be created inside the Translation Center in your Profile Settings)
  • PhraseApp project
  • locale file format
  • location of your locale files inside your project’s codebase

This will generate a basic configuration file in your current directory. Here are some examples of configurations for popular frameworks:

phraseapp:
  access_token: "3d7e6598d955bfcab104c45c037af1b9459df5692ac4c28a17793"
  project_id: "5c05692a2a995c0c45c0c3cbfcab1"
  file_format: "yml"
  push:
    sources:
    - file: "./config/locales/*.yml"
  pull:
    targets:
    - file: "./config/locales/<locale_name>.yml"
phraseapp:
  access_token: "3d7e6598d955bfcab09f232a99c37af1b9459df5692ac4c28a17793"
  project_id: "5c05692a2a995c0c45c0c3cbfcab1"
  file_format: "strings"
  push:
    sources:
    - file: "./<locale_code>.lproj/Localizable.strings"
      params:
        convert_emoji: true
  pull:
    targets:
    - file: "./<locale_code>.lproj/Localizable.strings"
      params:
        convert_emoji: true
    - file: "./<locale_code>.lproj/Localizable.stringsdict"
      params:
        # access_token or file_format can be overwritten
        file_format: "stringsdict"
phraseapp:
  access_token: "3d7e6598d955bfcab109f232a99c37af1b9459df5692ac4c28a17793"
  project_id: "5c05692a2a995c0c45c0c3cbfcab1"
  file_format: "xml"
  push:
    sources:
    - file: "./res/values-<locale_code>/strings.xml"
  pull:
    targets:
    - file: "./res/values-<locale_code>/strings.xml"

We recommend to modify the configuration file to suit your needs and then checking it into source control/version control.

Push

$ phraseapp push

The push command uploads the files found in your local project directories. Use the .phraseapp.yml configuration to specify the files that will be uploaded:

phraseapp:
  access_token: 3d7e6598d955bfcabaf1b9459df5692ac4c28a17793
  project_id: 5c05692a2a995c0c45c0c3cbfcab1
  file_format: nested_json

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

This example will upload the file en.json found at ./locales/ to PhraseApp with the given locale_id (this locale must already exist in PhraseApp).

This example for Ruby on Rails YAML files

phraseapp:
  push:
    sources:
    - file: ./config/locales/*.yml
      params:
        file_format: yml

will upload all files ending with .yml in ./config/locales/ to PhraseApp. Note that Ruby on Rails YAML contains the locale information in the actual file so there is no need to specify it.

The following example for iOS Localizable Strings matches all files named Localizable.strings in your .lproj folders:

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

The <locale_code> is everything that matches after / and before .lproj. It is used to create or identify locales in PhraseApp.

You can use the following placeholders in the paths within your file entries:

Placeholder Description
<locale_name> The locale name is the unique name of your locale in PhraseApp.
<locale_code> The locale code is the RFC 5646 compliant locale identifier. Note that the locale code does not have to be unique, so you might have multiple locales with different names, but the same code.
<tag> Use tags to group keys in PhraseApp. This is especially useful if you want to keep the original file structure.
Globbing

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

# 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 downloading via the pull command, you will have to provide the file pattern ./abc/defg/<locale_name>.yml instead of ./**/*.yml.

Parameters

The push command also supports all parameters that are available for the uploads#create API endpoint.

You can specify them like this:

phraseapp:
  push:
    sources:
    - file: "./locales/example.yml"
      params:
        update_translations: true
        file_format: strings
        convert_emoji: true
        ...

Pull

Use the pull command to download locale files from PhraseApp:

$ phraseapp pull

It works similar to the push command with the exception that you cannot use any globbing. When using placeholders we recommend using <locale_name> whenever possible.

Parameters

The pull command also supports all parameters that are available for the locales#download API endpoint.

You can specify them like this:

phraseapp:
  pull:
    targets:
    - file: "./locales/example.yml"
      params:
        file_format: strings
        convert_emoji: true
        ...