How to import and export translation files using the Localize CLI

This guide will walk you through the process of translating your project using the Localize CLI.

What you'll learn

How to configure the Localize CLI
How to push new phrases into your Localize project
How to pull phrases from your Localize project

Prerequisites

You have installed the Localize CLI by following the instructions on the Localize CLI Installation page
You have basic experience with the command line, package managers, and text editors
You have an active Localize account

How to configure the CLI

If you haven’t installed the CLI, follow the instructions on the Localize CLI Installation page before continuing. Installation will take approximately 5 minutes.

Before you can begin using the CLI you must configure it to be aware of a Project key and an associated API key.

Provide Project and API Keys

Log into your Localize account and go to the API Keys section of your Organization Settings.
{{SCREENSHOT}}
Create a new API key.
Open your terminal or command prompt and run the following:
localize config
You will be asked for and must input your Project key and the API key you created in step 2

Define Source and Target File Paths

The CLI ingests phrases by importing a source file from a file path you have defined on your computer. Similarly, the CLI exports phrases from Localize and saves them in a target file at a file path you have defined. In order to get the CLI working properly you will need to specify both source and target file paths.

The source and target file paths are commonly files within a Git or SVN repository where the phrases and translations in your target files are used within your application.

Find and open the Localize config.yml file using a text editor of your choice. The config.yml file is located at the root of your user folder. On OS X/MacOS that is: $HOME/.localize/config.yml. The example below uses VIM to open the config file:
vim ~/.localize/config.yml
The contents of your config.yml file should look like this:
{{USE SAME CODE SNIPPET AS IN INSTALLATION DOCS}}
Replace the - file: value under push: with the absolute path to your source file. You can add more source files by adding a new - file: field. For example on Mac OS you could reference a file in your Documents folder:
/Users/yourusername/Documents/localize-push/fr.json
Replace the - file: value under pull: with the absolute path to your soon-to-be-created file. You do not have to create this file; the CLI will create it for you when you run the pull command. You can add more target files by adding a new - file: field. For example on a Mac OS you could reference a file in your Documents folder:
/Users/yoursystemname/Documents/localize-pull/fr.json
Note: The file name MUST be in the format LANGAUGE_CODE.EXTENSION, no other file name will work. The language code must be an active language code in use in your project. For example:
fr.json, es.csv, pt.yml

How to push new phrases into your Localize project

With the CLI now properly configured you can begin pushing phrases into your Localize project.

Make sure that the file you want to push is a file type supported by Localize and is formatted in the way Localize needs to process it. Please see File Types and Formatting in the docs for more details on file formats.
Run localize push to push the files on your computer that you specified in your config.yml file into your Localize project
If successful you will see a green message that says “Successfully pushed x file(s) to Localize!”
If unsuccessful you will see a red error message
After successfully pushing phrases, login to your Localize account, go to the project you specified earlier, and you will see the phrases from your source file.

How to pull phrases from your Localize project

Run localize pull to pull the files from your Localize project and store them on your computer at the file path you specified in your config.yml file
If successful you will see a green message that says “Successfully pulled x file(s) to Localize!”
If unsuccessful you will see an red error message

Additional tips, recommendations, and resources

If you use a task runner such as Grunt or Gulp in your deployment pipeline for a web or mobile application, consider using plugins such as grunt-shell or gulp-exec to automate pulling of translations with our CLI. With this technique integrated into your workflow you can be certain that any deployment of your application will have the most up-to-date translations pulled from your Localize project.