Localize CLI

The Localize CLI makes it easy to translate content from mobile and web apps and backend services when a file-based approach is required. With a simple push/pull paradigm, you can easily push content to Localize and then pull the translations.

Watch this short video to see how to use the Localize CLI in your development workflow.

Installation

There are a number of different ways to install the Localize CLI on your machine, depending on what operating system and environment you are using. Here we describe how to install the Localize CLI using Pip.

Pip is a Python-based tool that offers convenient ways to install, upgrade, and remove Python packages and their dependencies. Pip is the recommended method of installing the CLI on Mac and Linux.

Prerequisites

• Windows, Linux, OS X, or Unix
• Python 2 version 2.6.5+ or Python 3 version 3.3+
• Pip

Install Python

First, check to see if you already have Python installed:

python --version

If you don't have Python installed, follow the procedure at Install Python to set it up.

• OS X / MacOS (Python 2)
• OS X / MacOS (Python 3)
• Linux
• Windows

Install Pip

Next, check pip:

pip --version

If you don't have pip installed. follow the procedure at Install pip.

To install pip on Linux

Download the installation script from pypa.io:

curl -O https://bootstrap.pypa.io/get-pip.py

The script downloads and installs the latest version of pip and another required package named setuptools.

Run the script with Python:

sudo python get-pip.py

Output:

Collecting pip
  Downloading pip-6.1.1-py2.py3-none-any.whl (1.1MB)
Collecting setuptools
  Downloading setuptools-15.0-py2.py3-none-any.whl (501kB)

Installing collected packages: pip, setuptools
Successfully installed pip-6.1.1 setuptools-15.0

📘

Python Executable Name May Vary

The name of the python executable may vary depending on your package manager (for example, python, python27, python3, etc.).

Install the Localize CLI

With Python and pip installed, use pip to install the Localize CLI:

Windows

pip install localize

To upgrade an existing Localize CLI installation, use the --upgrade option:

pip install --upgrade localize

Linux, OS X, or Unix

sudo pip install --ignore-installed localize

NOTE: The --ignore-installed option is not required for pip versions 9 and below, since these versions support the upgrading of dependencies.

📘

Pip Executable Name May Vary

The name of the pip executable may vary depending on what you are using (for example, pip, pip3, etc.).

Configure the CLI

Before you can start using the Localize Command Line Interface, you must sign up for a Localize account (if you don't already have one) and set up your CLI environment.

Provide Project and API Keys

1. Log into your Localize account and go to the API Keys section of your Organization Settings.

2. Create a new API key. It can be scoped to a specific project but do not scope it to a specific method.

3. Open terminal and run the following:

localize config

It will then ask you for your Project Key which you can find at the bottom of the API Keys page.

It will then ask for your API token, which you can find by clicking view next to the API key you made in step 1.

Add Path/Filenames

Find and open the Localize config.yml file, which should be at the root of your user folder.
On OS X/MacOS it is here: $HOME/.localize/config.yml.

Edit the following in theconfig.yml file:

1. YOUR_PROJECT_ID and YOUR_API_TOKEN should already be filled in for you.
   a. If they aren't, you can get them from your Localize dashboard.

api:
  project: YOUR_PROJECT_ID
  token: YOUR_API_TOKEN
format: DEFAULT_FILE_FORMAT
type: phrase | glossary
pull:
  targets:
  - LANGUAGE_CODE: /FULL_PATH_TO_FILE1/LANGUAGE_CODE.EXTENSION
  - LANGUAGE_CODE: /FULL_PATH_TO_FILE2/LANGUAGE_CODE.EXTENSION
    format: SPECIFIC_FILE_FORMAT
push:
  sources:
  - file: /FULL_PATH_TO_FILE3/LANGUAGE_CODE.EXTENSION
    format: SPECIFIC_FILE_FORMAT
  - file: /FULL_PATH_TO_FILE4/LANGUAGE_CODE.EXTENSION

2. Enter the desired DEFAULT_FILE_FORMAT in the format token.
   a. Unless otherwise specified, this file format will be used for all files in your push sources and pull targets.
3. Enter phrase or glossary in the type token
   a. type defaults to phrase if not specified.
4. Add your pull targets file(s).
   a. Replace the - file: path under pull: with the absolute path to a local file for your newly translated file. You can have many source files by adding a new - file field.
   b. If you want to specify a file format that's different from the DEFAULT_FILE_FORMAT , add a format token with the SPECIFIC_FILE_FORMAT below the file token.
5. Add your push source file(s).
   a. Replace the - file: value under push: with the absolute path to your local source language file. You can have many source files by adding a new - file field.
   b. If you want to specify a file format that's different from the DEFAULT_FILE_FORMAT , add a format token with the SPECIFIC_FILE_FORMAT below the file token.

📘

Notes

• For the pull file, the name can only be an active language code in that project. You do not need to create this file before doing a pull.
• The file name MUST be in the format LANGUAGE_CODE.EXTENSION, no other file name will work. e.g.:
  • es.csv, fr.yaml, etc.
• You must use an absolute path.
  • e.g. on a Mac, you cannot use environment variables like $HOME in the config.yml file.

Usage

This section introduces the common features and calling patterns used throughout the Localize Command Line Interface.

Pull

To pull translations from your Localize account and replace the files in your pull directive, run the pull command.

localize pull

Push

To push phrases and translations into your Localize account, run the push command. This command will look at each file in your push directive to get the content.

localize push