PhraseApp Client Configuration
You can use the
.phraseapp.yml to store repeating command line arguments.
The following arguments are supported:
||Your PhraseApp access token|
||The ID of your PhraseApp project|
||File default file format used (unless specified explicitly within
||Number of items returned in paginated responses|
||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).
.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
$HOMEand on windows
- the path specified in the
.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.
$ phraseapp push
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: update_translations: false 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).
update_translations parameter. If set to true, the client will import your local changes to existing translations
into PhraseApp, overwriting content already present.
update_translations had been set to
false, like in the example, only new keys and translations would be imported into PhraseApp.
This example for Ruby on Rails YAML files
phraseapp: push: sources: - file: ./config/locales/*.yml params: update_translations: true file_format: yml
will upload all files ending with
./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.
In this example, we have also set
true, meaning all changes to translations will be imported into PhraseApp,
and any changed translations will overwrite the data present in PhraseApp!
The following example for iOS Localizable Strings matches all files named
Localizable.strings in your
phraseapp: push: sources: - file: "./<locale_code>.lproj/Localizable.strings" params: convert_emoji: true file_format: strings
<locale_code> is everything that matches after
/ and before
.lproj. It is used to create or identify locales in PhraseApp.
Here, we have omitted the
update_translations flag, which has the same behavior as setting it to
You can use the following placeholders in the paths within your
||The locale name is the unique name of your locale in PhraseApp.|
||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.|
||Use tags to group keys in PhraseApp. This is especially useful if you want to keep the original file structure.|
** are globbing operators. A single star
* skips any folder in a
path. The double star works like the standard globbing operator and matches any
** 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
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 ...
Wait for uploads
All uploads are processed asynchronously. To wait on uploads you can use the
--wait flag. This tells the push command to wait for each file upload and returns whether it
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.
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 ...