i18n-completer

name	i18n-completer
description	Use when checking, completing, fixing, or adding translations in .xcstrings files, especially when localizations are missing or glossary terminology must be enforced.

i18n Completer

Core Principle

LLM does not read or write .xcstrings directly. All file operations go through scripts. The LLM's role is only to generate translation pairs.

Workflow

1. Scan for gaps

python3 .agents/skills/i18n-completer/scripts/scan_i18n.py <xcstrings_path>

Options: --glossary <path>, --source-lang <lang>, --json

2. Read source strings

Get the English values for missing keys without loading the full file:

python3 -c "
import json
with open('<xcstrings_path>') as f:
    data = json.load(f)
keys = <list of missing keys from scan output>
for k in keys:
    en = data['strings'][k].get('localizations',{}).get('en',{}).get('stringUnit',{}).get('value','')
    print(f'{k} = {en}')
"

3. Load glossary (if exists)

Read references/LOCALIZATION_TERMS.md to follow project terminology.

4. Generate translations

Produce a JSON object mapping keys to language-code/value pairs:

{
  "key.name": {
    "de": "German translation",
    "es": "Spanish translation"
  }
}

Translation rules:

• Follow glossary terms strictly
• Keep parameterized placeholders (%@, %lld, %1$@) exactly as in source
• Follow target language punctuation (… not ... for ja/zh-Hans)
• Match existing tone and style in the target language

5. Write via script

Pipe the JSON to the apply script:

cat <<'EOF' | python3 .agents/skills/i18n-completer/scripts/apply_i18n.py <xcstrings_path> --from -
{
  "key.name": {
    "de": "...",
    "es": "..."
  }
}
EOF

Or save to a temp file first:

python3 .agents/skills/i18n-completer/scripts/apply_i18n.py <xcstrings_path> --from /tmp/translations.json

Single key shortcut:

python3 .agents/skills/i18n-completer/scripts/apply_i18n.py <xcstrings_path> --set KEY --lang ja --value "翻訳"

Options: --dry-run to preview, --source-lang <lang>

6. Verify

Re-run scan to confirm no gaps remain.

Glossary Format

Markdown table with at least two columns. See references/LOCALIZATION_TERMS.md.

English	Target Language Term
channel	信道
scan	扫描