gettranslated-cli 1.1.1

Command-line tool for syncing translations with GetTranslated.ai

GetTranslated CLI

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

Installation

pip install gettranslated-cli

Quick Start

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: Project config file (recommended)
   echo "your-server-api-key-here" > .gettranslated
   
   # Option 2: Environment variable
   export GETTRANSLATED_KEY="your-server-api-key-here"
   
   # Option 3: Command line (not recommended for production)
   translate sync -k your-server-api-key-here
   

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

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

# Upload only
translate upload

# Download only
translate download

# Translate only
translate translate

# Grammar check
translate grammar

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

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

API Key Configuration

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

1. Command line argument (-k or --key)
2. Environment variable (GETTRANSLATED_KEY)
3. Project config file (.gettranslated in project directory)

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

# 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

# GitHub Actions example
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 }}
        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:
    • XX.lproj/Localizable.strings (traditional format)
    • XX.lproj/Localizable.stringsdict (plurals format)
  • React Native: JSON files in one of the common locations
• Check that you're running the command from the correct 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/grammar check: 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
• Contact support if your platform type is incorrect

Grammar check not available

• Grammar check is available on Professional and Enterprise plans
• Upgrade your plan or contact support for more information

For more help, see the CLI Quick Start Guide

Command Reference

translate <mode> [working_directory] [options]

Modes:
  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)
  grammar     Run grammar check on project strings

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

Support

• Documentation: https://www.gettranslated.ai/developers/cli-quickstart/
• Email: [e-mail]