21 KiB
i18n — Internationalization Guide (日本語)
🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr
OmniRoute は、30 の言語をサポートしており、ダッシュボード UI の完全な翻訳、翻訳されたドキュメント、アラビア語とヘブライ語の RTL サポートを備えています。## Quick Reference
| タスク | コマンド | |
|---|---|---|
| 翻訳を生成する | node scripts/i18n/generate-multilang.mjs メッセージ |
|
| ドキュメントの翻訳 (LLM) | python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <モデル> |
|
| ロケールを検証する | python3 scripts/validate_translation.py クイック -l cs |
|
| コードキーを確認する | python3 スクリプト/check_translations.py |
|
| QAレポートを生成する | node scripts/i18n/generate-qa-checklist.mjs |
|
| ビジュアルQA（劇作家） | node scripts/i18n/run-visual-qa.mjs |
## アーキテクチャ |
Source of Truth
-UI 文字列: src/i18n/messages/en.json (英語ソース、~2800 キー) -ロケール ファイル: src/i18n/messages/{locale}.json (30 個の翻訳) -フレームワーク: Cookie ベースのロケール解決を備えた next-intl -Config: src/i18n/config.ts — 30 個すべてのロケール、言語名、フラグを定義します### Runtime Flow
- ユーザーが言語を選択 →
NEXT_LOCALEクッキーセット src/i18n/request.tsはロケールを解決します: cookie →Accept-Languageヘッダー → フォールバックen- 動的インポートにより
messages/{locale}.jsonがロードされます - コンポーネントは
useTranslations("namespace")とt("key")を使用します### Supported Locales
| コード | 言語 | RTL | Google 翻訳コード | |
|---|---|---|---|---|
ar |
और देखेंはい | ar |
||
bg |
Български | いいえ | bg |
|
cs |
チェシュティナ | いいえ | cs |
|
| だ | ダンスク | いいえ | だ | |
| で | ドイツ語 | いいえ | で | |
| エス | スペイン語 | いいえ | エス | |
フィ |
スオミ | いいえ | フィ |
|
fr |
フランセ | いいえ | fr |
|
| 「彼」 | ログイン | ログインはい | iw |
|
| こんにちは。 हिन्दी | いいえ | こんにちは。 | ||
| 「ふー」 | マジャール語 | いいえ | 「ふー」 | |
id |
インドネシア語 | いいえ | id |
|
| それ | イタリアーノ | いいえ | それ | |
じゃ |
日本語 | いいえ | じゃ |
|
こ |
한국어 | いいえ | こ |
|
ms |
バハサ・メラユ | いいえ | ms |
|
nl |
オランダ | いいえ | nl |
|
| いいえ | ノルスク | いいえ | いいえ | |
ファイ |
フィリピン人 | いいえ | tl |
|
pl |
ポルスキ | いいえ | pl |
|
pt |
Português (ポルトガル) | いいえ | pt |
|
pt-BR |
ポルトガル語 (ブラジル) | いいえ | pt |
|
| 「ろ」 | ロマナ | いいえ | 「ろ」 | |
| る | Русский | いいえ | る | |
sk |
スロベンチナ | いいえ | sk |
|
sv |
スヴェンスカ | いいえ | sv |
|
| `番目 | ไทย | いいえ | th |
|
tr |
テュルクチェ | いいえ | tr |
|
イギリス-UA |
Українська | いいえ | イギリス |
|
vi |
ティエン・ヴィエット | いいえ | vi |
|
zh-CN |
中文 (简体) | いいえ | zh-CN |
## Adding a New Language |
1. Register the Locale
src/i18n/config.ts を編集します。```ts
// Add to LOCALES array
"xx",
// Add to LANGUAGES array
{ code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },
### 2. Add to Generator
`scripts/i18n/generate-multilang.mjs` を編集します — エントリを `LOCALE_SPECS` に追加します。```js
{
code: "xx",
googleTl: "xx",
label: "XX",
flag: "🏳️",
languageName: "Language Name",
readmeName: "Language Name",
docsName: "Language Name",
},
3. Generate Initial Translation
node scripts/i18n/generate-multilang.mjs messages
これにより、Google 翻訳によって「en.json」から自動翻訳された「src/i18n/messages/xx.json」が作成されます。### 4. Review & Fix Auto-Translations
自動翻訳は出発点です。以下について手動で確認します。
- 技術的な精度
- 文脈に応じた用語
- プレースホルダー (
{count}、{value}など) の適切な処理### 5. Validate
python3 scripts/validate_translation.py quick -l xx
python3 scripts/validate_translation.py diff common -l xx
6. Generate Translated Documentation
node scripts/i18n/generate-multilang.mjs docs
Auto-Translation Pipeline
generate-multilang.mjs (Google Translate)
プライマリ自動翻訳エンジン— Google Translate 無料 API を使用して、UI 文字列、README、ドキュメントの翻訳を生成します。```bash node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]
|モード |何をするのか |
| ---------- | ---------------------------------------------------------------------------- |
| `メッセージ` | `src/i18n/messages/{locale}.json` 内の欠落しているキーを `en.json` から変換します。
| 「リードミー」 | `README.md` をプロジェクト ルートの `README.{code}.md` としてすべてのロケールに変換します。
| `ドキュメント` | `DOC_SOURCE_FILES` を `docs/i18n/{locale}/{docName}` に変換します。
| 「すべて」 | 3 つのモードすべてを実行します。
**特徴:**
-**テキスト保護**: コード ブロック (` ``` `)、インライン コード (` ` `)、マークダウン リンク/イメージ (`[text](url)`)、HTML タグ、テーブル、および ICU プレースホルダー (`{count}`、`{value}`、`{total}` など) を翻訳前にマスクし、復元します。
-**チャンクバッチ**: `__OMNIROUTE_I18N_SEPARATOR__` 区切り文字を使用して複数の文字列を結合し、API 呼び出しを最小限に抑えます (リクエストごとに最大 1800 文字)
-**メモリ内キャッシュ**: セッション内で繰り返される文字列に対する冗長な API 呼び出しを回避します。
-**再試行ロジック**: 429/5xx エラーの指数関数的バックオフ (300 ミリ秒 × 試行遅延で最大 5 回の試行)
-**タイムアウト**: リクエストごとに 20 秒
-**既存をスキップ**: ターゲット ファイルが既に存在する場合、上書きされません。
**重要な行動:**
- `docs/i18n/README.md` は実行のたびに**再生成**されます。これはすべてのドキュメントの自動生成されたインデックスです。
- ルート `README.{code}.md` ファイルは、存在しない場合にのみ作成されます (`EXISTING_README_CODES` のロケールをスキップします)。
- 言語バー (`🌐**Languages:**...`) は、すべての翻訳されたドキュメントに自動的に挿入/更新されます### i18n_autotranslate.py (LLM-based)
**セカンダリトランスレータ**— OpenAI 互換の LLM API (OmniRoute 自体を含む) を使用して、既存の `docs/i18n/` マークダウン ファイルを翻訳します。 Google 翻訳よりも高品質なドキュメントを磨き上げたり、再翻訳したりする場合に最適です。```bash
python3 scripts/i18n_autotranslate.py \
--api-url http://localhost:20128/v1 \
--api-key sk-your-key \
--model gpt-4o
特徴:
docs/i18n/マークダウン ファイルをスキャンして英語の段落を探します- コードブロック、テーブル、および翻訳済みのコンテンツをスキップします
- 技術翻訳システムのプロンプトを使用して段落を LLM に送信します
- 30 言語すべてをサポート## Validation & QA
validate_translation.py
翻訳バリデータ— ロケール JSON を「en.json」と比較し、問題を報告します。```bash
Quick check (counts only)
python3 scripts/validate_translation.py quick -l cs
Output:
Missing: 0
Untranslated: 0
Ignored (UNTRANSLATABLE_KEYS): 236
Detailed diff by category
python3 scripts/validate_translation.py diff common -l cs python3 scripts/validate_translation.py diff settings -l cs
Export to CSV
python3 scripts/validate_translation.py csv -l cs > report.csv
Export to Markdown
python3 scripts/validate_translation.py md -l cs > report.md
Full report (default)
python3 scripts/validate_translation.py -l cs
**検出:**
-**キーがありません**— `en.json` にはキーがありますが、ロケール ファイルにはありません
-**追加キー**— ロケール ファイルにはあるが、「en.json」には含まれていないキー
-**未翻訳キー**— ロケール値が英語ソースと等しいキー (ホワイトリストを除く)
-**プレースホルダーの不一致**— ソースと翻訳の間で一致しない ICU プレースホルダー
**終了コード:**
|コード |意味 |
|-----|----------|
| 0 | OK |
| 1 |一般的なエラー |
| 2 |文字列がありません (ハード エラー) |
| 3 |未翻訳警告 (ソフト) |
**環境:**`TRANSLATION_LANG=cs` を設定するか、`-l cs` フラグを使用します。### check_translations.py
**Code-to-JSON キー チェッカー**— `useTranslations()` 呼び出しの `src/**/*.tsx` と `src/**/*.ts` をスキャンし、参照されているすべてのキーが `en.json` に存在することを確認します。```bash
# Basic check
python3 scripts/check_translations.py
# Verbose output
python3 scripts/check_translations.py --verbose
# Auto-fix (adds missing keys to en.json)
python3 scripts/check_translations.py --fix
generate-qa-checklist.mjs
静的分析 QA— Next.js ページ ファイルをスキャンして i18n リスク メトリクスを取得し、Markdown レポートを生成します。```bash node scripts/i18n/generate-qa-checklist.mjs
**チェック:**
- 固定幅クラスの使用 (オーバーフローのリスク)
- 方向性のある左/右クラス (RTL リスク)
- クリッピングが発生しやすいパターン
- ロケールのパリティ (欠落/余分なキーと `en.json` の比較)
- 優先ロケールの README 言語セレクター バー (`es`、`fr`、`de`、`ja`、`ar`)
**出力:**`docs/reports/i18n-qa-checklist-{date}.md`### run-visual-qa.mjs
**Playwright によるビジュアル QA**— 複数のロケールおよびビューポートですべてのダッシュボード ルートのスクリーンショットを取得し、ページの健全性を評価します。```bash
# Default: es, fr, de, ja, ar on localhost:20128
node scripts/i18n/run-visual-qa.mjs
# Custom base URL and locales
QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs
# Custom routes
QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs
検出:
- テキストオーバーフロー
- 要素のクリッピング
- RTL レイアウトの不一致
出力:docs/reports/i18n-visual-qa-{date}.md + JSON レポート## Managing Untranslatable Keys
untranslatable-keys.json
ファイル:scripts/i18n/untranslatable-keys.json
英語のソースと同一のままにする必要があるキーのホワイトリスト。誤検知の「未翻訳」警告を回避するために「validate_translation.py」によって使用されます。```json { "description": "Keys that should remain untranslated...", "keys": [ "common.model", "common.oauth", "health.cpu", ... ] }
**ここに属するもの:**
- ブランド/製品名: `landing.brandName`、`common.social-github`
- 技術用語/頭字語: 「health.cpu」、「mcpDashboard.pid」、「settings.ai」
- ICU/フォーマット文字列: `apiManager.modelsCount`、`health.millisecondsShort`
- プレースホルダーの値: `providers.openaiBaseUrlPlaceholder`、`cliTools.baseUrlPlaceholder`
- プロトコル名: `common.http`、`common.oauth`、`providers.oauth2Label`
- ナビゲーション セクション: `sidebar.primarySection`、`sidebar.cliSection`
**キーを追加するには:**`scripts/i18n/untranslatable-keys.json` の `keys` 配列を編集し、検証を再実行します。## CI Integration
### GitHub Actions (`.github/workflows/ci.yml`)
CI パイプラインは、プッシュおよび PR ごとにすべてのロケールを検証します。
1.**`i18n-matrix` ジョブ**— すべてのロケール ファイル (`en.json` を除く) を動的に検出します
2.**`i18n` ジョブ**— ロケールごとに `validate_translation.py Quick -l '<lang>'` を並行して実行します
3.**`ci-summary` ジョブ**— 結果をダッシュボードの概要に集約します```yaml
# i18n-matrix: discovers languages
LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')
# i18n: validates each language
python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'
ダッシュボード出力:```
🌍 Translations
| Metric | Value |
|---|---|
| Languages checked | 30 |
| Total untranslated | 0 |
✅ All translations complete
## File Structure
src/i18n/ ├── config.ts # Locale definitions (30 locales, RTL config) ├── request.ts # Runtime locale resolution └── messages/ ├── en.json # Source of truth (~2800 keys) ├── cs.json # Czech translation ├── de.json # German translation └── ... # 30 locale files total
scripts/ ├── i18n/ │ ├── generate-multilang.mjs # Auto-translation engine (Google Translate, 888 lines) │ ├── generate-qa-checklist.mjs # Static analysis QA │ ├── run-visual-qa.mjs # Playwright visual QA │ └── untranslatable-keys.json # Allowlist for validation (236 keys) ├── validate_translation.py # Translation validator ├── check_translations.py # Code-to-JSON key checker └── i18n_autotranslate.py # LLM-based doc translator
.github/workflows/ └── ci.yml # i18n validation in CI matrix
docs/ ├── I18N.md # This file — i18n toolchain documentation ├── i18n/ │ ├── README.md # Auto-generated language index │ ├── cs/ # Czech docs │ │ └── docs/ │ │ ├── I18N.md # Czech translation of this file │ │ └── ... │ ├── de/ # German docs │ └── ... # 30 locale directories └── reports/ ├── i18n-qa-checklist-.md # Static analysis reports └── i18n-visual-qa-.md # Visual QA reports
## Best Practices
### When Editing Translations
1.**常に「en.json」を最初に編集してください**— これが信頼できる情報源です
2.**`generate-multilang.mjsmessages`**を実行して、新しいキーをすべてのロケールに伝達します
3.**自動翻訳を確認する**— Google 翻訳は出発点であり、最終的なものではありません
4.**コミット前に検証**— `python3 scripts/validate_translation.py Quick -l <lang>`
5.**キーを英語のままにする必要がある場合は、`untranslatable-keys.json`**を更新します### Placeholder Safety
- ICU プレースホルダー (`{count}`、`{value}`、`{total}`、`{seconds}`) は正確に保存する必要があります
- 複数の形式 (`{count, plural, one {# model} other {# models}}`) は構造を維持する必要があります
- バリデーターはプレースホルダーの不一致を自動的に検出します### Adding New Translation Keys in Code
```tsx
// Use namespaced keys
const t = useTranslations("settings");
t("cacheSettings"); // maps to settings.cacheSettings in JSON
// Run check_translations.py to verify keys exist
python3 scripts/check_translations.py --verbose
RTL Considerations
- アラビア語 (
ar) とヘブライ語 (he) は RTL ロケールです - ハードコーディングされた
left/rightCSS を避け、start/end論理プロパティを使用します - Visual QA は「run-visual-qa.mjs」を介して RTL レイアウトの不一致を検出します## Known Issues & History
in.json → hi.json Fix
ジェネレーターは当初、正しい ISO 639-1 hi の代わりに、ヒンディー語の code: "in" (非推奨の Google 翻訳コード) を使用していました。これにより、孤立した「hi.json」の複製「in.json」が作成されました。 generate-multilang.mjs の code: "in" を code: "hi" に変更し、孤立したファイルを削除することで修正しました。### docs/i18n/README.md Is Auto-Generated
docs/i18n/README.md ファイルは、generate-multilang.mjs docs によって完全に再生成されます。手動で編集した内容は失われます。永続化する必要がある手書きのドキュメントには、docs/I18N.md (このファイル) を使用します。### External Untranslatable Keys List
untranslatable-keys.json ホワイトリストは、メンテナンスを容易にするために、validate_translation.py に設定されたインライン Python から外部 JSON ファイルに移動されました。バリデーターは実行時にそれをロードします。### generate-multilang.mjs Hindi Code Fix
ジェネレーターは当初、正しい ISO 639-1 hi の代わりに、ヒンディー語の code: "in" (非推奨の Google 翻訳コード) を使用していました。これは、diegosouzapw によってアップストリーム コミット 952b0b22c で導入されました。 LOCALE_SPECS 配列の code: "in" を code: "hi" に変更し、孤立した in.json ファイルを削除することで修正しました。### validate_translation.py Ignored Count Output
「クイック」チェックでは、「untranslatable-keys.json」から無視されたキーの数が表示されるようになりました。``` Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236