XCStrings Translator

Translate Apple's Localizable.xcstrings files using AI. Supports Claude, GPT, and Gemini.

xcstrings translate Localizable.xcstrings -l fr,es,it,ja,ko

Features

• Multi-provider - Choose Claude, GPT, or Gemini based on cost/quality needs
• Context-aware - Uses existing translations to understand meaning and tone
• Format-safe - Preserves %@, %lld, %1$@ and other specifiers
• 35+ languages - All major App Store locales
• Recursive - Point at a directory to translate every nested .xcstrings file
• Cost estimation - Preview costs before translating
• Validation - Detect missing translations and format mismatches

Quick Start

# Install
pip install xcstrings-translator

# Set API key (pick one)
export ANTHROPIC_API_KEY=sk-...   # Claude
export OPENAI_API_KEY=sk-...      # GPT
export GOOGLE_API_KEY=...         # Gemini
export OPENROUTER_API_KEY=sk-or-... # OpenRouter (any vendor)

# Translate
xcstrings translate Localizable.xcstrings -l fr,de,ja

Models

Older aliases still work: gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini, gemini-2.5-pro/flash, gemini-2.0-flash.

xcstrings translate input.xcstrings -l fr -m haiku        # fast/cheap
xcstrings translate input.xcstrings -l fr -m sonnet       # balanced (default)
xcstrings translate input.xcstrings -l fr -m gpt-5.4-nano # cheapest

OpenRouter

Route through OpenRouter to reach any vendor with one key. Set OPENROUTER_API_KEY, then pass an openrouter:vendor/model string or a shorthand alias:

xcstrings translate input.xcstrings -l fr -m openrouter:anthropic/claude-sonnet-4.6
xcstrings translate input.xcstrings -l fr -m or-gpt-5.4-nano

Cost estimates for openrouter:* models are fetched live from OpenRouter's public model catalog (cached ~24h under ~/.cache/xcstrings-translator/), so any model — even brand-new ones — gets accurate pricing in estimate/--dry-run. Pass --no-fetch to skip the network and use cached/static prices only.

Commands

Usage Examples

# Translate to multiple languages
xcstrings translate Localizable.xcstrings -l fr,es,it,de,ja

# Translate every .xcstrings under a project directory (recursive; asks first)
xcstrings translate ./MyApp -l fr,es,it
xcstrings translate ./MyApp --fill-missing -y   # skip the confirmation prompt

# Estimate cost first
xcstrings translate Localizable.xcstrings -l fr,es,it --dry-run

# Use faster model
xcstrings translate Localizable.xcstrings -l fr -m haiku

# Parallel requests (faster for large files)
xcstrings translate Localizable.xcstrings -l fr,es -c 32

# Save to different file
xcstrings translate input.xcstrings -l fr -o translated.xcstrings

# Fill missing translations only
xcstrings translate Localizable.xcstrings --fill-missing

# Check translation coverage
xcstrings info Localizable.xcstrings

# Validate format specifiers
xcstrings validate Localizable.xcstrings

App Context

Provide context for better translations. Create context.md next to your xcstrings file:

# My Fitness App

A workout tracking app for athletes.

Tone: Motivational, energetic.
Use informal "you" (du/tu).

Or pass directly:

xcstrings translate input.xcstrings -l fr --context "A fitness app with motivational tone"

Python API

from xcstrings_translator import XCStringsFile, XCStringsTranslator

# Load
xcstrings = XCStringsFile.from_file("Localizable.xcstrings")

# Translate
translator = XCStringsTranslator(model="sonnet")
xcstrings = translator.translate_file(xcstrings, ["fr", "es", "it"])

# Save
xcstrings.to_file("Localizable.xcstrings")

# Stats
print(f"Translated: {translator.stats.translated}")
# Rates below are sonnet's ($3 in / $15 out per 1M tokens); adjust for your model.
print(f"Cost: ${translator.stats.input_tokens * 3 / 1e6 + translator.stats.output_tokens * 15 / 1e6:.2f}")

Supported Languages

European: en, de, fr, es, it, pt, pt-BR, pt-PT, nl, pl, sv, da, nb, fi, cs, sk, hu, ro, bg, el, sq, uk, ru, tr

Asian: ja, ko, zh-Hans, zh-Hant, th, vi, id, ms, hi

Middle Eastern: ar, he

Other: ca, eu

Options

Troubleshooting

"Unsupported language" - Use Apple codes: zh-Hans not zh-CN, pt-BR not pt_BR

Format mismatch - Run xcstrings validate to find issues

API errors - Check correct key is set for your model

Contributing

Contributions are welcome! See CONTRIBUTING.md for dev setup, tests, and the release process. Please also review our Code of Conduct. To report a security issue, see SECURITY.md.

License

MIT

Made with ❤️ by Justin Lanfermann