@autoglot/cli

Translate i18n files from the command line. Supports JSON, YAML, PO/POT, and Xcode String Catalogs.

Quick start

npx @autoglot/cli en.json --lang es,fr,de

Pass multiple files or a shell glob to translate them together in one job:

npx @autoglot/cli ios/Layers/**/*.xcstrings --lang es,fr,de

Setup

1. Sign up at autoglot.app
2. Go to dashboard / API keys and create a key
3. Export it:

export AUTOGLOT_API_KEY=your_key_here

CLI usage

autoglot <files...> --lang <codes> [options]

Arguments

| Argument | Description | |----------|-------------| | files | Source files to translate in one job (e.g. en.json, en.po, messages.yaml) |

Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --lang | -l | (required) | Comma-separated target languages | | --source | -s | Auto-detect from filename, fallback en | Source language code | | --output | -o | Input root | Output directory for translated files; relative input paths are preserved | | --input-root | | Current directory when possible | Root used for stable source paths in translation context, analytics, and activity | | --project | -p | | Project for glossary/style guide (owner/repo format) | | --branch | | | Source branch recorded with activity; requires --deployment-type and --project | | --deployment-type | | | preview or release; requires --branch | | --api-key | -k | AUTOGLOT_API_KEY env var | API key | | --api-url | | https://api.autoglot.app | API base URL | | --timeout | | | Maximum wait in seconds, then return the latest compatible cached artifact. Requires --project | | --no-cache | | false | Skip translation cache | | --help | -h | | Show help | | --version | -v | | Show version |

Examples

Translate a JSON file into Spanish, French, and German:

npx @autoglot/cli src/locales/en.json --lang es,fr,de

Translate a PO file with explicit source language and output directory:

npx @autoglot/cli messages.po --lang ja,ko --source en --output ./translations

Use a project's glossary and style guide:

npx @autoglot/cli en.json --lang es,fr --project acme/my-app

Keep a build moving with cached translations if fresh translation takes more than two minutes:

npx @autoglot/cli en.json --lang es,fr --project acme/my-app --timeout 120

Skip cache to force re-translation:

npx @autoglot/cli en.yaml --lang pt-BR --no-cache

Translate multiple Xcode String Catalogs in one job with one timeout:

npx @autoglot/cli ios/Layers/**/*.xcstrings --lang de,fr --project acme/ios --input-root . --branch main --deployment-type release --timeout 120

Library usage

@autoglot/cli also exports a translate() function for use in Node.js scripts and other tools (like @autoglot/next).

import { translate } from '@autoglot/cli';
import { readFileSync } from 'fs';

const files = await translate({
  files: [{
    filename: 'frontend/apps/web/locales/en.json',
    content: readFileSync('en.json', 'utf-8'),
  }],
  targetLanguages: ['es', 'fr', 'de'],
  sourceLanguage: 'en',
  apiKey: process.env.AUTOGLOT_API_KEY!,
  project: 'myorg/my-app',
  branch: 'main',
  deploymentType: 'release',
  timeoutSeconds: 120,
  onProgress: (status) => {
    console.log(`${status.completed_strings}/${status.total_strings}`);
  },
});

for (const file of files) {
  console.log(file.filename, file.content.length);
}

translate(options)

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | files | { filename: string; content: string }[] | Yes | | Files to translate. Use stable project-relative filenames for analytics and activity. | | targetLanguages | string[] | Yes | | Target language codes | | sourceLanguage | string | Yes | | Source language code | | apiKey | string | Yes | | API key | | apiUrl | string | No | https://api.autoglot.app | API base URL | | project | string | No | | Project for glossary/style guide (owner/repo) | | branch | string | No | | Source branch recorded with activity; requires deploymentType and project | | deploymentType | 'preview' \| 'release' | No | | Build type recorded with activity; requires branch | | timeoutSeconds | number | No | | Maximum wait before returning the latest compatible cached artifact. Requires project | | skipCache | boolean | No | false | Skip translation cache | | onProgress | (status: JobStatus) => void | No | | Progress callback |

Returns Promise<{ filename: string; content: string }[]> — the translated files.

JobStatus

The object passed to onProgress:

| Field | Type | Description | |-------|------|-------------| | job_id | string | Job identifier | | status | string | processing, completed, or failed | | progress | number | Percentage (0–100) | | total_strings | number | Total strings to translate | | completed_strings | number | Strings translated so far | | error_message | string? | Error details if failed |

Supported file formats

| Format | Extension | |--------|-----------| | JSON | .json | | YAML | .yml, .yaml | | PO/POT | .po, .pot | | Xcode String Catalog | .xcstrings |

Supported languages

| Code | Language | Code | Language | |------|----------|------|----------| | de | German | ja | Japanese | | fr | French | ko | Korean | | es | Spanish | zh-Hans | Simplified Chinese | | it | Italian | zh-Hant | Traditional Chinese | | pt | Portuguese | ar | Arabic | | pt-BR | Brazilian Portuguese | he | Hebrew | | nl | Dutch | hi | Hindi | | pl | Polish | th | Thai | | ru | Russian | vi | Vietnamese | | uk | Ukrainian | id | Indonesian | | tr | Turkish | ms | Malay | | sv | Swedish | cs | Czech | | da | Danish | hu | Hungarian | | fi | Finnish | ro | Romanian | | nb | Norwegian | sk | Slovak | | el | Greek | bg | Bulgarian |

Links

• autoglot dashboard
• Get API key
• Report issues