| name | japanese-doc-localization |
| description | Improve Japanese technical documentation readability by translating general English terms into natural Japanese prose while preserving identifiers, config keys, protocol names, and normative keywords. Use when editing *.ja.md files, Japanese versions of English specs, localized developer docs, or reviews that complain Japanese docs are hard to read because they are just line-broken English. |
Japanese Doc Localization
Purpose
Make Japanese technical documents read like Japanese, not like English text with Japanese particles.
Use this skill when editing Japanese documentation, especially *.ja.md files that mirror English source documents.
Core Rule
Translate general terminology into natural Japanese prose.
Preserve only names that readers must match exactly in code, configuration, protocols, commands, APIs, states, domain terminology, or external products.
Preserve As-Is
Keep these in English or code style:
- Configuration keys:
tracker.kind, workspace.root, codex.command
- Domain terms that the project treats as names: Issue Tracker
- Enum values and state names:
Todo, Done, Human Review
- Protocol and product names: Codex app-server, Linear GraphQL, RFC 2119
- Command names and flags:
codex app-server, --port
- Field names when they are part of the contract:
thread_id, issue_id, turn_id
- Normative keywords:
MUST, SHOULD, MAY, OPTIONAL, REQUIRED
Translate General Terms
Translate English words used as ordinary explanation:
| Avoid | Prefer |
|---|
| issue | 課題 |
| workspace | ワークスペース |
| workflow | ワークフロー |
| runtime | 実行時 |
| dispatch | 割り当てる / 割り当て |
| retry | 再試行 |
| cleanup | クリーンアップ |
| state | 状態 |
| terminal state | 終端状態 |
| active state | アクティブ状態 |
| agent | エージェント |
| coding agent | コーディングエージェント |
| prompt | プロンプト |
| observability | 可観測性 |
| dashboard | ダッシュボード |
| log | ログ |
| validation | 検証 |
| configuration | 設定 |
| default | 既定値 |
| failure | 失敗 |
| success | 成功 |
Prefer verbs that make the sentence Japanese:
dispatch issue -> 課題を割り当てるfetch candidate issues -> 候補課題を取得するvalidate config -> 設定を検証するemit log -> ログを出力するpreserve workspace -> ワークスペースを保持する
Editing Workflow
- Read the nearby English source when the Japanese file mirrors one.
- Identify contract terms that must stay exact.
- Translate ordinary explanatory terms into Japanese.
- Rewrite fragments into complete Japanese sentences.
- Keep headings and bullets scannable, but do not leave bullet items as English noun piles.
- Verify that the meaning, requirements, and normative strength did not change.
Style Guidance
Use Japanese sentence order instead of direct English calques.
Bad:
workflow config value に対する typed getter を提供する。
Good:
ワークフロー設定値に対する型付き getter を提供する。
Bad:
candidate issue を fetch し dispatch する。
Good:
Bad:
operator-visible observability を提供する。
Good:
Review Checklist
- General terms are Japanese unless they are exact identifiers.
- Sentences are not just English clauses with Japanese endings.
- Code identifiers remain searchable and exact.
- Japanese and English versions still describe the same contract.
- No requirement strength changed:
MUST is still MUST, SHOULD is still SHOULD.
