Create a configuration file

To create your configuration file you will have to install the PhraseApp Client. You can then 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 ID
  • Locale file format
  • Location of your locale files inside your project’s codebase

This will generate a basic configuration file in your current directory.

If you decide to create a configuration file from scratch it 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

Modify your configuration file

You can use the .phraseapp.yml  to store repeating command line arguments.
The following arguments are supported:

project_id                        
The ID of your PhraseApp project

file_format                        
File default file format used (unless specified explicitly within sources and targets entries). See our format guide for available file formats and their API extension.

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

Push & Pull

Use the push command to import locale files to PhraseApp:

$ 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 and to set additional parameters for the upload if required.

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 (see below). When using placeholders we recommend using <locale_name> whenever possible. Alternatively, you can use the <tag>  placeholder to download keys into separate files based on their tag.

Parameters

The push command can be configured within the .phraseapp.yml  configuration file where you can use the same options that are available for the uploads#create endpoint.

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

You can specify them like this:

Push

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

Pull

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

Format Options

Depending on the file format you can add a variety of format options in the parameter section as well. Please use our list of supported platforms and formats to find your file format and the list of format options that are supported for each one. Format options can be available for upload, download or both,

You can specify them in the parameter section like this:

params:
 format_options:
   convert_placeholder: true

Placeholders & Globbing     

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

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

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 failed or succeeded.

Common use-cases

Common use-cases

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). Notice the update_translations  parameter. If set to true, the client will import your local changes to existing translations into PhraseApp, overwriting content already present. If 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 .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. In this example, we have also set update_translations to 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 .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.

Here, we have omitted the update_translations flag, which has the same behavior as setting it to false.


Configuration examples for popular frameworks

Rails

phraseapp:
  access_token: "3d7e6598d955bfcab104c45c037af1b9459df5692ac4c28a17793"
  project_id: "5c05692a2a995c0c45c0c3cbfcab1"
  file_format: "yml"
  push:
    sources:
    - file: "./config/locales/*.yml"
  pull:
    targets:
    - file: "./config/locales/<locale_name>.yml"

 iOS Strings

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"

 Android XML

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.

Did this answer your question?