Core Translator CLI

Command-line interface for the Core Translator service. Translate iOS strings, PO files, browser extensions, and more.

Installation

npm install -g core-translator-cli

Or use directly with npx:

npx core-translator-cli --help

Configuration

Set your authentication token and backend endpoint:

# Using environment variables
export CORE_TRANSLATOR_TOKEN="your-token-here"
export CORE_TRANSLATOR_BACKEND_ENDPOINT="https://api.example.com"

# Or using the config command
core-translator config --token YOUR_TOKEN --endpoint https://api.example.com

Usage

Translate Single Text

core-translator text --text "Hello World" -t zh-Hans

Translate iOS xcstrings

core-translator xcstrings ./Localizable.xcstrings -t ja

Translate PO Files

# Single PO file
core-translator po ./messages.po -t fr

# Multiple PO files using glob pattern (automatically detects language from filename)
core-translator po "src/locales/*.po"

# With custom concurrency
core-translator po "src/locales/*.po" --concurrency 8

# Disable automatic language extraction from filename
core-translator po "src/locales/*.po" --no-extract-language -t fr

Translate Browser Extension

core-translator browser-ext ./_locales/en/messages.json -t es -o ./_locales/es/messages.json

Translate FormatJS Files

core-translator formatjs "./locales/*.json" --target_language fr

Translate Rails YAML

core-translator rails-yaml --source config/locales/en.yml --target config/locales/ja.yml

Translate Xcode .strings Files

core-translator xcode-strings ./en.lproj/Localizable.strings -t es

Translate Single File

core-translator single-file ./README.md --target_language zh-Hans -o ./README.zh.md

Commands

• text - Translate a single text string
• xcstrings - Translate iOS .xcstrings localization files
• po - Translate GNU gettext .po files (supports glob patterns for multiple files)
• browser-ext - Translate browser extension _locales JSON files
• formatjs - Translate FormatJS JSON files
• rails-yaml - Translate Rails i18n YAML files
• xcode-strings - Translate Xcode .strings files
• single-file - Translate a single text file
• config - Configure API credentials

Options

All commands support these common options:

• -t, --target-language <lang> - Target language code (required)
• -s, --source-language <lang> - Source language code (default: en)
• -a, --app-name <name> - Application name for context
• --endpoint <url> - Override backend endpoint
• --token <token> - Override authentication token
• -v, --verbose - Enable verbose logging

Translation Manifest (xcstrings)

The xcstrings command auto-discovers a core-translator.json next to the source file (or load explicitly with --manifest <path>). The manifest gives the LLM domain context so terms like "recording" translate correctly for a screen recorder (录制 / 録画) instead of an audio recorder (录音 / 録音).

{
  "appName": "ScreenKite",
  "appDescription": "macOS screen recording app",
  "glossary": {
    "Recording": {
      "description": "Screen/video recording, not audio recording.",
      "translations": { "ja": "録画", "zh-Hans": "录制" },
      "forbidden":    { "ja": ["録音"], "zh-Hans": ["录音"] },
      "unlessKeyContains": ["voiceover", "microphone", "audio recording"]
    }
  },
  "doNotTranslate": ["ScreenKite", "macOS"],
  "styleNotes": { "ja": "Use です/ます polite form." },
  "perKeyContext": {
    "Stop Recording?": "Confirmation dialog before ending a screen recording session."
  }
}

Flags: --manifest <path>, --no-manifest-auto-discover, --app-description <text>, --extra-context <text>.

Backend requirement: the manifest sends a structured-context envelope that only the Next.js (Cloudflare Workers) backend understands. The legacy Python backend will silently misinterpret it. Point the CLI at a Next.js deployment (or omit the manifest) when targeting the Python backend.

Supported Languages

• ja, ja-JP - Japanese
• ko, ko-KR - Korean
• zh-Hans, zh-CN - Chinese (Simplified)
• zh-Hant, zh-TW - Chinese (Traditional)
• zh-HK - Chinese (Hong Kong)
• de, de-DE - German
• fr, fr-FR - French
• it - Italian
• es, es-ES, es-MX - Spanish
• pt, pt-BR, pt-PT - Portuguese
• en, en-US, en-GB - English
• And many more...

License

MIT