GetTranslated CLI

Command-line tool for syncing translation files with GetTranslated.ai.

Installation

pip install gettranslated-cli

Quick Start

Option 1: Using init (Recommended for First-Time Setup)

The easiest way to get started is using the init command:

# Navigate to your project directory
cd /path/to/your/project

# Run init to link your project
translate init

The init command will:

• Prompt you for your Server API Key (input is masked for security)
• Validate your API key by connecting to your project
• Display your project information (name, platform, base language, target languages)
• Optionally save your API key to .gettranslated for future use

After initialization, you can run commands like translate sync or translate upload without entering your API key again.

Option 2: Manual Setup

1. Get your Server API Key from your project settings

   • ⚠️ Important: Use the Server API Key, not the Client API Key
   • The Server API Key is required for CLI operations

2. Configure your API key (choose one method):

   # Option 1: Use init command (recommended for local development)
   translate init
   
   # Option 2: Environment variable (recommended for CI/CD)
   export GETTRANSLATED_KEY="your-server-api-key-here"
   
   # Option 3: Command line flag (useful for one-off commands or overrides)
   translate sync -k your-server-api-key-here
   

   When to use each method:

   • init command: Best for local development setup. Guides you through the process and saves your key to .gettranslated.
   • Environment variable: Ideal for CI/CD pipelines, Docker containers, and automated workflows. Keeps keys out of files.
   • Command line flag (-k): Useful for one-off commands, testing, or overriding other configured keys.

3. Run a sync from your project directory:

   cd /path/to/your/project
   translate sync
   

That's it! The CLI will:

• Upload your base language files
• Translate any new or untranslated strings
• Download all translated files to your project

First Sync Workflow

On your first sync, the CLI will:

• Detect existing language files in your project
• Warn about base language mismatches if detected
• Offer to upload existing translations if you already have translation files
• Guide you through the setup process

Usage

Basic Commands

# Initialize project (links directory to GetTranslated project)
translate init

# Full sync (upload → translate → download)
translate sync

# Upload only
translate upload

# Download only
translate download

# Translate only
translate translate

Options

# Specify working directory (default: current directory)
translate sync /path/to/project

# Verbose output (shows detailed debug information)
translate sync -v

# Force re-upload even if files haven't changed
translate sync -f

# Bypass validation errors and continue processing
translate sync --bypass-validation

# Custom server URL
translate sync -s https://custom-server.com

# Sync a specific git branch (auto-detected by default; also via GETTRANSLATED_REF)
translate sync --ref feature/new-onboarding

# Show version number
translate --version

Validation

The CLI validates your translation files during upload. If validation errors are found:

• The process will stop with detailed error messages
• Each error includes the error code, message, and location (line/column)
• Use --bypass-validation to continue despite validation errors
• See the Validation Errors documentation for details

Example validation output:

VALIDATION SUMMARY
======================================================================

📄 src/i18n/locales/en.json
  ❌ Validation Errors (2):
  • INVALID_KEY: Key contains invalid characters (line 5, column 12) [key: my-key]
  • MISSING_VALUE: Translation value is empty (line 10) [key: empty_key]
======================================================================

Supported Platforms

• Android: Automatically finds strings.xml files in values/ and values-XX/ directories
• iOS: Automatically finds *.xcstrings String Catalogs (Xcode 15's default; a single multi-language file) as well as Localizable.strings and Localizable.stringsdict files in XX.lproj/ directories
• React Native: Searches for JSON files in common locations:
  • locales/
  • src/locales/
  • assets/locales/
  • translations/
  • i18n/
  • Root directory
• Flutter: Automatically finds App Resource Bundle (.arb) files — one file per locale (app_en.arb → app_es.arb). Both the conventional app_<lang>.arb prefix and a bare <lang>.arb are matched, in common locations:
  • lib/l10n/
  • l10n/
  • lib/src/l10n/
  • assets/l10n/
  • Root directory

Custom localization directories

If your React Native or Flutter localization 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 again.

When custom directories are set, .gettranslated is written as a small JSON object ({"key": "...", "dirs": ["..."]}) instead of a bare key string. Both forms are read transparently. (Android and iOS don't need this — they already discover files across the whole project by their values-XX/ and XX.lproj/ conventions.)

API Key Configuration

The CLI looks for your API key in the following order (first match wins):

1. Command line argument (-k or --key) - highest priority, useful for overrides
2. Project config file (.gettranslated in project directory) - convenient for local development
3. Environment variable (GETTRANSLATED_KEY) - recommended for CI/CD and automated workflows

Note: If no API key is found and you're using translate init, you'll be prompted to enter it (input is masked for security).

Choosing the Right Method

• Local Development: Use translate init to set up your project. It creates a .gettranslated file automatically.
• CI/CD Pipelines: Use environment variables (e.g., GETTRANSLATED_KEY) stored as secrets in your CI/CD platform. This keeps keys secure and out of your repository.
• One-off Commands: Use the -k or --key flag to override other configured keys for a single command.
• Docker Containers: Use environment variables passed at container runtime.

Security Note

⚠️ Important: Add .gettranslated to your .gitignore to avoid committing your API key:

echo ".gettranslated" >> .gitignore

API Key Requirements:

• Use the Server API Key (not the Client API Key)
• The Server API Key is required for all CLI operations
• Keep your API key secure and never commit it to version control
• API keys can be rotated in your project settings if needed

Examples

First-time Setup

Using init (Recommended):

# 1. Install the CLI
pip install gettranslated-cli

# 2. Navigate to your project
cd ~/projects/my-app

# 3. Run init to link your project
translate init

# 4. Run your first sync
translate sync

Manual Setup:

# 1. Install the CLI
pip install gettranslated-cli

# 2. Set your API key
export GETTRANSLATED_KEY="your-key-here"

# 3. Navigate to your project
cd ~/projects/my-app

# 4. Run your first sync
translate sync

CI/CD Integration

For CI/CD pipelines, always use environment variables to securely store your API key as secrets in your CI/CD platform. This keeps keys out of your repository and follows security best practices.

Branch-aware sync: the CLI auto-detects your current git branch and syncs that branch's version of your files, so parallel branches don't overwrite each other on the server. CI often checks out a detached HEAD where auto-detection fails — set GETTRANSLATED_REF (or pass --ref) to the branch name; common CI branch variables are used as a fallback. Omit it to sync the project's default branch.

# GitHub Actions example
# Store GETTRANSLATED_KEY as a secret in GitHub Settings > Secrets
name: Sync Translations

on:
  workflow_dispatch:
  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: ${{ secrets.GETTRANSLATED_KEY }}
          # Sync this branch's files (checkout is a detached HEAD in CI, so set it explicitly)
          GETTRANSLATED_REF: ${{ github.head_ref || github.ref_name }}
        run: translate sync .

Troubleshooting

Authentication Errors

"No API key found"

• Make sure you've configured your API key using one of the methods above
• Check that environment variables are set correctly
• Verify config files exist and contain the key
• Ensure you're running the command from the correct directory

"Authentication failed" (403 error)

• Verify you're using the Server API Key (not the Client API Key)
• Check that your API key hasn't expired or been revoked
• Ensure the API key matches an active project
• See: API Key Configuration Guide

"Project not found" (404 error)

• Verify you're using the correct Server API Key for your project
• Check that the project is active and not deleted
• Ensure the API key matches the project you want to access
• See: API Key Configuration Guide

File Not Found Errors

"No [Platform] files found to upload"

• Ensure your project structure matches the expected format:
  • Android: app/src/main/res/values/strings.xml
  • iOS:
    • *.xcstrings (String Catalog — single multi-language file, found anywhere)
    • XX.lproj/Localizable.strings (traditional format)
    • XX.lproj/Localizable.stringsdict (plurals format)
  • React Native: JSON files in one of the common locations
  • Flutter: .arb files (e.g. lib/l10n/app_en.arb, or a bare en.arb)
• Check that you're running the command from the correct directory
• If your files live elsewhere (React Native / Flutter), run translate init to add a custom localization directory
• Use -v (verbose) flag to see what directories are being searched

"Translation file not found" (404 on download)

• The translation may not have been created yet
• Run translate sync to upload, translate, and download in sequence
• Ensure languages are configured in your project settings
• Check that the file path matches your project configuration

Connection Errors

Network errors or timeouts

• Verify your internet connection
• Check that the server URL is correct (default: https://www.gettranslated.ai)
• Large files may take longer - the CLI uses appropriate timeouts (30-120 seconds)
• Try again if the server is experiencing high load

Request timeouts

• File uploads/downloads: 120 seconds timeout
• Translation/validation: 120 seconds timeout
• Metadata requests: 10 seconds timeout
• If timeouts persist, check your network connection or try again later

Validation Errors

Validation errors during upload

• Review the validation error messages for specific issues
• Each error includes the error code, message, and file location
• See the Validation Errors documentation for detailed information
• Use --bypass-validation to continue despite errors (errors are still shown)

"No languages are configured"

• Configure languages in your project settings
• Visit your project settings page to add target languages
• At least one target language must be configured before translating or downloading

Other Issues

"Unknown platform" error

• Ensure your project type is set correctly in project settings
• Supported platforms: Android, iOS, React Native, Flutter
• Contact support if your platform type is incorrect

For more help, see the CLI Quick Start Guide

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 (shows debug information)
  -f, --force                Force processing even if file hash matches
  --bypass-validation        Continue processing despite validation errors
  -s, --server URL           Server URL (default: https://www.gettranslated.ai)
  --ref BRANCH               Git branch to sync (default: auto-detected; or GETTRANSLATED_REF)
  --version                  Show version number and exit
  -h, --help                 Show help message

Error Handling

The CLI provides comprehensive error handling with helpful messages:

• Authentication errors (403): Clear messages with links to API key setup guide
• Project not found (404): Guidance on verifying your Server API Key
• Translation not found (404): Explains why and how to resolve
• Network errors: Helpful troubleshooting steps
• Validation errors: Detailed error information with file locations

All errors include links to relevant documentation for quick resolution.

License

MIT License

Changelog

See CHANGELOG.md for a detailed list of changes in each version.

Support

• Documentation: https://www.gettranslated.ai/developers/cli-quickstart/
• Email: support@gettranslated.ai