Skip to content

About

Skill for AI Agents to efficiently add translations to Apple Platform apps based on Xcode Strings Catalog.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

xcstrings-translation-review

A Claude Code skill + standalone Python toolkit for managing translations in Xcode String Catalog (.xcstrings) files.

Analyze coverage gaps, detect the best pivot language, extract strings for batch translation, and merge results back — all without leaving the terminal.

The problem

Xcode's String Catalog editor works fine for a handful of strings, but becomes painful when you have hundreds of keys across multiple languages. You end up with:

  • No clear picture of which languages are incomplete
  • Format specifier mismatches (%@, %lld) silently breaking at runtime
  • No efficient way to batch-translate missing strings with an LLM
  • No way to detect which existing language would make the best translation source

This toolkit solves all of that.

What's included

xcstrings-translation-review/
├── SKILL.md                           # Claude Code skill (workflow + guidelines)
├── LICENSE
├── scripts/
│   ├── analyze_xcstrings.py           # Translation coverage & format validation
│   ├── detect_pivot_language.py       # Best source language recommendation
│   ├── extract_for_translation.py     # Batch extraction for LLM translation
│   └── merge_translations.py          # Merge translations back into .xcstrings
└── README.md

Quick start

1. Analyze your catalog

python3 scripts/analyze_xcstrings.py Localizable.xcstrings
============================================================
XCSTRINGS ANALYSIS REPORT
============================================================
Source language: en
All languages: de, en, es, fr, ja, ko
Total keys: 342
  Translatable: 338
  Skipped (shouldTranslate=false): 4
  Keys with comments: 47

--- Per-Language Coverage ---
  [de] 72.5% — translated:245  missing:93  new:0  needs_review:0
  [es] 100.0% — translated:338  missing:0  new:0  needs_review:0
  [fr] 85.2% — translated:288  missing:50  new:0  needs_review:0
  [ja] 41.4% — translated:140  missing:198  new:0  needs_review:0
  [ko] 0.0% — translated:0  missing:338  new:0  needs_review:0

Add --format-check to catch format specifier mismatches, --lang ja to focus on one language, or --json for machine-readable output.

2. Find the best pivot language

python3 scripts/detect_pivot_language.py Localizable.xcstrings
=================================================================
PIVOT LANGUAGE ANALYSIS
=================================================================
Source language: en
Translatable keys: 338

--- Language Ranking (by pivot score) ---
Lang        Coverage   Translated  LLM Bonus    Score Notes
-----------------------------------------------------------------
en            100.0%      338/338      1.15x    115.0  SOURCE, RECOMMENDED
es            100.0%      338/338      1.05x    105.0
fr             85.2%      288/338      1.05x     89.5
de             72.5%      245/338      1.03x     74.7
ja             41.4%      140/338      1.00x     41.4
ko              0.0%        0/338      1.00x      0.0

Source language 'en' is already the best pivot (100.0% coverage).

The pivot score combines translation coverage with LLM quality — English gets a 15% bonus because LLMs produce better translations from English.

3. Extract strings for batch translation

# Extract only missing translations for Japanese
python3 scripts/extract_for_translation.py Localizable.xcstrings ja

# Extract everything for quality review
python3 scripts/extract_for_translation.py Localizable.xcstrings ja --mode all

# Include existing translations for comparison
python3 scripts/extract_for_translation.py Localizable.xcstrings ja --mode review --with-existing

Creates batch files in ./translation_batches/:

{
  "meta": { "lang": "ja", "batch": 1, "total_batches": 8, "count": 25 },
  "strings": {
    "Save": { "source": "Save" },
    "Delete entry": { "source": "Delete entry", "comment": "Confirmation dialog button" },
    "%lld entries": { "source": "%lld entries" }
  }
}

Modes: missing (default), all, review, stale, outdated.

4. Merge translations back

After translating (manually or via LLM), merge the results:

# Merge as confirmed
python3 scripts/merge_translations.py Localizable.xcstrings ja translations_ja.json

# Merge as needs_review (recommended for AI-generated translations)
python3 scripts/merge_translations.py Localizable.xcstrings ja translations_ja.json --state needs_review

The translations file is a flat JSON object:

{
  "Save": "保存",
  "Delete entry": "エントリーを削除",
  "%lld entries": "%lldエントリー"
}

5. Validate

Run the analysis again with format checking:

python3 scripts/analyze_xcstrings.py Localizable.xcstrings --format-check

Using as a Claude Code skill

Copy the folder into your skills directory and Claude Code will use it automatically when working with .xcstrings files:

# Global (all projects)
cp -r xcstrings-translation-review ~/.claude/skills/

# Project-specific
cp -r xcstrings-translation-review .claude/skills/

The skill guides Claude through the full workflow: analysis, glossary building, batch translation with domain-specific terminology, merging, and validation. See SKILL.md for the complete reference.

Requirements

  • Python 3.6+
  • No external dependencies (standard library only)

License

MIT

About

Skill for AI Agents to efficiently add translations to Apple Platform apps based on Xcode Strings Catalog.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages