CLI Tool - Quick Start Guide

Table of Contents

• Prerequisites
• Step 1: Install the CLI
• Step 2: Configure Your API Key
• Step 3: Run Your First Sync
• Understand the Modes
• Common Options
• Platform-Specific Behavior
• First Sync Workflow
• Integrate into CI/CD
• Command Reference
• Common Issues & Solutions
• Version History

Prerequisites

• Python 3.6+
• A GetTranslated account and Server API Key
• Your project already set up for localization (Android, iOS, React Native, or Flutter)

Step 1: Install the CLI

Install the GetTranslated CLI using pip:

pip install gettranslated-cli

This installs the translate command globally, so you can use it from any directory.

Step 2: Configure Your API Key

Get your API key from your project settings page. Each project has two API keys, one for the client and one for the server.

The CLI needs your Server API Key to authenticate.

You can provide your API key in three ways (in order of precedence):

Option 1: Use Init Command (Recommended)

The easiest way to create the .gettranslated file is using the init command:

cd /path/to/your/project
translate init

The init command will prompt you for your API key (masked input) and optionally save it to .gettranslated. See the Init Command section for details.

Option 2: Environment Variable (Recommended for CI/CD)

Set the GETTRANSLATED_KEY environment variable. This method is ideal for CI/CD pipelines, Docker containers, and automated workflows:

# Linux/macOS
export GETTRANSLATED_KEY="your-sk-api-key"

# Windows (Command Prompt)
set GETTRANSLATED_KEY=your-sk-api-key

# Windows (PowerShell)
$env:GETTRANSLATED_KEY="your-sk-api-key"

Use cases:

• CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.)
• Docker containers
• Automated scripts and workflows
• When you want to keep keys out of files

Option 3: Command Line Flag (Useful for Overrides)

Use the -k or --key flag to specify the API key directly. This is useful for one-off commands or overriding other configured keys:

translate sync -k your-sk-api-key

Use cases:

• Testing with different API keys
• One-off commands without configuring a key
• Overriding other configured keys temporarily

Priority Order: The CLI checks in this order: command line → .gettranslated file → environment variable

Using the Init Command (Recommended for First-Time Setup)

The easiest way to set up your project is using the init command. It guides you through the setup process and validates your API key.

cd /path/to/your/project
translate init

The init command will:

1. Prompt you for your Server API Key (input is masked for security)
2. Validate your API key by connecting to your GetTranslated project
3. Display your project information:
   • Project name
   • Platform (Android, iOS, React Native, or Flutter)
   • Base language
   • Configured target languages
4. Optionally save your API key to .gettranslated for future use

Example output:

Please enter your Server API Key:
(You can find this in your project settings)

API Key: [masked input]
Validating API key...

Connected to project "My Awesome App"
Platform: iOS
Base language: en
Configured target languages: es, fr, de

Save this API key to .gettranslated so you don't have to enter it next time? (y/n): y
✅ API key saved to .gettranslated

✅ Initialization complete!

You can now run commands like:
  translate sync
  translate upload

Benefits of using init:

• Validates your API key before you start using the CLI
• Shows your project configuration at a glance
• Securely prompts for your API key (masked input)
• Helps you save your API key to .gettranslated for convenience

Note: The init command follows the same API key resolution order as other commands. If you've already configured your API key using one of the methods above, init will use that key and won't prompt you.

Step 3: Run Your First Sync

Navigate to your project directory and run a sync:

cd /path/to/your/project
translate sync

Note: The working directory is optional - if you're already in your project directory, you can just run translate sync without specifying a path.

The CLI will:

1. Connect to your GetTranslated project
2. Find and upload your base language files (e.g., strings.xml for Android, en.json for React Native, app_en.arb for Flutter)
3. Automatically translate any new or untranslated strings
4. Download all translated files to your project

Example output:

Connected to project My App
Beginning upload...
Syncing src/i18n/locales/en.json...
Beginning translation...
Translating Spanish... 100.0%
Translating French... 100.0%
Beginning download...
Syncing src/i18n/locales/en.json...
Syncing src/i18n/locales/es.json...
Syncing src/i18n/locales/fr.json...
✅ Done!

Understand the Modes

The CLI supports five different modes:

1. Sync Mode (Recommended)

Runs upload → translate → download in sequence. This is the most common workflow:

translate sync

2. Upload Mode

Uploads your base language files to the server:

translate upload

3. Download Mode

Downloads translated files from the server to your project:

translate download

4. Translate Mode

Triggers translation of untranslated strings on the server:

translate translate

Common Options

Specify Working Directory

By default, the CLI uses the current directory. You can specify a different directory:

translate sync /path/to/project

Verbose Output

Get detailed debug information:

translate sync -v

Force Re-upload

Force upload even if files haven't changed:

translate sync -f

Custom Server URL

Use a different server URL (default: https://www.gettranslated.ai):

translate sync -s https://custom-server.com

Bypass Validation

Continue processing despite validation errors. When enabled, validation errors and warnings are still displayed, but the CLI will not exit with an error code:

translate sync --bypass-validation

Show Version

Display the CLI version number and exit:

translate --version

Combining Options

translate sync -v -f /path/to/project

Platform-Specific Behavior

Android Projects

The script looks for strings.xml files in:

• values/strings.xml (base language, typically English)
• values-XX/strings.xml (translated languages, e.g., values-es/strings.xml for Spanish)

iOS Projects

The CLI supports both the modern String Catalog and the traditional formats:

• *.xcstrings (String Catalog — Xcode 15's default, found anywhere in your project). A String Catalog is a single file holding all languages; the CLI uploads and writes back the whole catalog, so there's no per-language .lproj layout to manage.
• XX.lproj/Localizable.strings (traditional format, e.g., en.lproj/Localizable.strings for English)
• XX.lproj/Localizable.stringsdict (plurals format)

React Native Projects

The script searches for JSON files in common locations (searches all directories recursively):

• locales/XX.json (also finds src/locales/XX.json recursively)
• assets/locales/XX.json
• translations/XX.json
• i18n/XX.json (also finds src/i18n/XX.json recursively)
• Root directory: XX.json

The script searches all locations recursively and returns all matching files. Nested paths like src/locales and src/i18n are automatically found by the recursive search.

Flutter Projects

The CLI looks for App Resource Bundle (.arb) files — one file per locale (app_en.arb → app_es.arb). Both the conventional app_XX.arb prefix and a bare XX.arb are matched, in these common locations:

• lib/l10n/app_XX.arb (the usual arb-dir in l10n.yaml)
• l10n/app_XX.arb
• lib/src/l10n/app_XX.arb
• assets/l10n/app_XX.arb
• Root directory: app_XX.arb or XX.arb

A String Catalog holds every language in one file; ARB does not — each locale is its own file, and the CLI writes each target locale back with its @@locale set. Your template's @-metadata (descriptions, placeholder types) and ICU plural/select syntax are preserved so flutter gen-l10n still passes.

Custom Localization Directories (React Native & Flutter)

If your React Native or Flutter files live somewhere other than the locations above, run translate init and enter your directory(ies) when prompted (comma-separated, relative to the project root). They are saved to .gettranslated and searched in addition to the defaults — so nothing that was found before stops being found. Enter none at the prompt to clear them.

First Sync Workflow

On your first sync, the script will:

1. Detect existing language files - It scans your project and lists all detected language files
2. Warn about base language mismatches - If your configured base language doesn't match detected files
3. Offer to upload existing translations - If you already have translation files, it will ask if you want to upload them

This helps you migrate existing translations into GetTranslated.

Integrate into CI/CD

You can integrate the CLI into your build pipeline. For CI/CD workflows, always use environment variables to securely store your API key as secrets in your CI/CD platform.

Example GitHub Actions workflow:

name: Sync Translations

on:
  workflow_dispatch:  # Manual trigger
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

jobs:
  sync-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      
      - name: Install GetTranslated CLI
        run: pip install gettranslated-cli
      
      - name: Run translation sync
        env:
          GETTRANSLATED_KEY: $
        run: translate sync .

Command Reference

translate <mode> [working_directory] [options]

Modes:
  init        Link current directory to a GetTranslated project (first-time setup)
  upload      Upload base language files to server
  download    Download translated files from server
  translate   Trigger translation of untranslated strings
  sync        Run upload → translate → download (recommended)
  validate    Re-validate base strings and existing translations

Options:
  -k, --key KEY              Server API key
  -v, --verbose              Verbose output mode
  -f, --force                Force processing even if unchanged; also overwrites an empty/corrupt download
  -s, --server URL           Server URL (default: https://www.gettranslated.ai)
  --ref BRANCH               Git branch to sync (default: auto-detected; or GETTRANSLATED_REF)
  --bypass-validation         Bypass validation checks and continue despite errors
  --version                   Show version number and exit
  -h, --help                 Show help message

Common Issues & Solutions

translate sync --bypass-validation