# Translate I18N

> Fill missing i18n translations in the viewer source JSON. Run this after adding or modifying English or Chinese UI strings in claude_tap/viewer_i18n.json — it auto-translates to ja, ko, fr, ar, de, ru via OpenRouter.

- Skill: `liaohch3/translate-i18n` (Agent Skill)
- Install (CLI): `npx skillmds@latest add liaohch3/translate-i18n`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liaohch3/translate-i18n/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: liaohch3 (https://skillmd.com/u/liaohch3)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/liaohch3/translate-i18n

---


# Translate i18n

Automatically fill missing translations for the viewer's `claude_tap/viewer_i18n.json` source file. The script uses English and Chinese as source languages and translates to Japanese, Korean, French, Arabic, German, and Russian.

## Prerequisites

- `OPENROUTER_API_KEY` must be set in the environment (it is in the user's `.zshrc`)
- Default model: `google/gemini-2.5-flash`

## Workflow

### 1. Check what's missing (dry run)

Always preview first to confirm which keys need translation:

```bash
uv run python scripts/translate_i18n.py --dry-run
```

This parses `claude_tap/viewer_i18n.json`, finds keys present in both `en` and `zh-CN` but missing in other languages, and lists them without modifying the file.

### 2. Run the translation

```bash
uv run python scripts/translate_i18n.py
```

The script calls OpenRouter once per target language, then writes the translations back into `viewer_i18n.json` in-place.

### 3. Verify the result

After translation, run the formatter and tests to make sure nothing broke:

```bash
uv run python -m json.tool claude_tap/viewer_i18n.json >/dev/null
uv run pytest tests/test_translate_i18n.py -v
```

## Options

| Flag | Purpose |
|------|---------|
| `--dry-run` | Show missing keys only, no file changes |
| `--model MODEL` | Override the OpenRouter model (default: `google/gemini-2.5-flash`) |
| `--target {viewer,cli}` | Translation target preset (default: `viewer`) |
| `--file PATH` | Override target file path |
| `--object-name NAME` | Override the legacy JS/Python i18n object name |

## How it works

The script:
1. Loads the viewer i18n JSON source file
2. Validates that every language block is a string-to-string map
3. Identifies keys present in `en` + `zh-CN` but missing in target languages
4. Sends a structured prompt to OpenRouter with existing translations for consistency
5. Normalizes fullwidth punctuation for CJK languages (matching zh-CN style)
6. Inserts new entries after the existing keys in each target language

## Common scenarios

**Added a new UI string**: Add the key to both `en` and `zh-CN` blocks in `claude_tap/viewer_i18n.json`, then run this skill. The other 6 languages will be filled automatically.

**Changed an existing string**: The script only fills *missing* keys. To re-translate an existing key, first delete it from the target language blocks, then run the script.