---
name: po-translate
description: Orchestrate English→Japanese translation of po/ja.po — classify, delegate translation/review to subagents, iterate until clean
---

# PO Translation Orchestrator

Translate `po/ja.po` from English to Japanese for this literate Nix configuration
repository. This skill orchestrates the process: you classify entries yourself, then
delegate translation and review to subagents, iterating until the review passes.

## Phase 1: Classify (do this yourself)

Scan `po/ja.po` and classify every entry into three buckets.

### Skip (leave msgstr empty)

| PO type comment (`#. type:`)    | Reason                   |
| ------------------------------- | ------------------------ |
| `paragraph in src`              | Code block content       |
| `keyword NAME` / `keyword name` | Source block identifiers |
| `keyword SETUPFILE`             | Org directive            |
| `keyword PROPERTY`              | Property drawer value    |
| `keyword OPTIONS`               | Export option string     |
| `keyword STARTUP`               | Startup keyword          |
| `keyword INCLUDE`               | po4a handles path swap   |
| `property (*)`                  | Property values          |

Also skip: bare URLs as msgid, table cells with hardware models/hostnames/platforms.

### Already Translated

Non-empty msgstr — leave unchanged unless review flags them.

### Translate

Everything else: `paragraph`, `heading *`–`*****`, `plain list`, `paragraph in QUOTE/quote/example`,
`cell column N` with prose, `keyword title`.

### Grouping

Group translatable entries by primary source file into sequential batches:

1. `configuration.org`
2. `applications/emacs/init.org`
3. `overlays/configuration.org` + `applications/emacs/early-init.org` + `.github/README.org`
4. `modules/configuration.org`

Output a batch summary (entry counts, line ranges) before proceeding to Phase 2.

## Phase 2: Translate (delegate to subagents)

Spawn one Agent per batch, **sequentially** (wait for each to finish before starting
the next — they all edit the same file).

### Subagent prompt template

Include ALL of the following in each subagent's prompt:

1. The batch assignment: line range, list of msgid start lines to translate
2. The full content of these reference files (read them yourself first, then paste
   the content into the prompt — subagents cannot read skill reference files by path):
   - `.claude/skills/po-translate/references/glossary.md`
   - `.claude/skills/po-translate/references/style-guide.md`
   - `.claude/skills/po-translate/references/po-format.md`
3. These rules:

```
## Translation Rules

### What to translate
- paragraph, heading, plain list, paragraph in QUOTE/quote/example, cell with prose, keyword title

### What to leave empty (msgstr "")
- paragraph in src, keyword NAME/name, SETUPFILE/PROPERTY/OPTIONS/STARTUP/INCLUDE, property (*), bare URLs, proper nouns (hardware models, hostnames, platforms)

### PO format
- #, no-wrap entries: msgstr on single line
- Multi-line msgid: msgstr starts with "" then continuation lines
- Match approximate line structure of msgid
- Preserve \" escaping

### Org markup preservation
- [[url][desc]]: translate only desc, keep URL intact
- [[*heading][desc]]: translate *heading to match the translated heading name in po/ja.po, translate desc independently
- =code= and ~verbatim~: do NOT translate content inside markers
- *bold* / /italic/: translate text, keep markers
- \\\\: preserve in same position

### Terminology
- Follow the glossary strictly
- Nix terms (flake, derivation, overlay, home-manager) → keep English
- General technical terms with Japanese equivalents → use Japanese

### Register
- です/ます (desu/masu) polite form consistently
- Technical but accessible
- Faithfully translate "why" reasoning — core value of literate config

### Important
- Never modify msgid or comment lines (#., #:, #,)
- If entry already has correct translation, leave unchanged
- Preserve blank lines between entries
- Use the Edit tool for each translation
- After completing, read back modified sections to verify
```

## Phase 3: Review (delegate to subagent)

After all translation batches complete, spawn a review subagent.

### Review subagent prompt

Include these checks in the prompt:

1. **PO Syntax**: Run `msgfmt --check po/ja.po`
2. **Code blocks empty**: Verify `paragraph in src`, `keyword NAME/name`, directive
   keywords, `property (*)` all have empty msgstr
3. **Prose translated**: Verify `paragraph`, `heading`, `plain list` etc. have non-empty msgstr
4. **No-wrap compliance**: `#, no-wrap` entries have single-line msgstr
5. **Terminology**: No "フレーク"/"デリベーション"/"オーバーレイ" (should stay English);
   "configuration"→"設定", "declarative"→"宣言的" consistently
6. **Markup**: `[[`/`]]` count matches, URLs unchanged, `=code=`/`~verbatim~` preserved
7. **Internal links**: `[[*heading][desc]]` — verify `*heading` matches the translated heading name in the corresponding heading entry's msgstr
8. **Register**: Sample entries for consistent です/ます form
9. **Japanese prose norms**: No em dash or 中黒-enumeration introduced in msgstr;
   no LLM-ish filler (「重要なのは」「掘り下げる」etc. — see style-guide.md);
   hedging level matches the English msgid

The review subagent should:

- Fix minor issues (structural/terminology) directly
- Report translation quality issues with line numbers
- Re-run `msgfmt --check po/ja.po` after fixes

## Phase 4: Iterate (do this yourself)

Evaluate the review subagent's report:

- If **PASS** on all checks → done
- If issues remain → spawn targeted translation subagents to fix only the
  flagged entries, then re-run review (Phase 3)
- Repeat until clean

## Final Validation

After review passes:

```sh
msgfmt --check po/ja.po
po4a po4a.cfg
```