i18n

i18n スキル

国際化のための標準とワークフローです。ユーザーに表示されるすべてのテキストは i18n を使用する必要があります。

開始時に宣言: "I'm using i18n skill to ensure proper internationalization."

重要: まず設定を読み込む

i18n 作業を行う前に、必ず src/common/config/i18n-config.json を読み込んで、現在サポートされている言語とモジュールの一覧を取得してください。このスキルの作成後に言語やモジュールが追加または削除されている可能性があるため、数を固定で想定しないでください。

cat src/common/config/i18n-config.json

このファイルが 唯一の信頼できる情報源（single source of truth） です。すべてのスクリプト、ランタイムコード、そしてこのワークフローは、このファイルに依存しています。

ファイル構成

src/common/config/i18n-config.json              # Single source of truth: languages, modules
src/renderer/i18n/
├── index.ts                             # i18next configuration
├── i18n-keys.d.ts                       # AUTO-GENERATED — do not edit manually
└── locales/
    ├── <lang>/                          # One directory per language in i18n-config.json
    │   ├── index.ts                     # Barrel import for all modules
    │   ├── common.json                  # One JSON per module in i18n-config.json
    │   ├── conversation.json
    │   └── ...
    └── ...

重要なポイント

• 基準言語: i18n-config.json の referenceLanguage で定義されています（現在は en-US）
• サポート言語: supportedLanguages 配列で定義されています。現在の一覧はファイルを読んで確認してください
• モジュール: modules 配列で定義されています。現在の一覧はファイルを読んで確認してください

キーの構造

コードでは、キーは 名前空間付きのドット記法 を使用します: t('module.key') または t('module.nested.key')。

各モジュールの JSON ファイル内では、キーをフラットにも、ネストさせることもできます:

// common.json — flat keys
{
  "send": "Send",
  "cancel": "Cancel",
  "copySuccess": "Copied"
}

// cron.json — nested keys
{
  "scheduledTasks": "Scheduled Tasks",
  "status": {
    "active": "Active",
    "paused": "Paused"
  }
}

コード内での使用例:

t('common.send'); // flat key in common.json
t('cron.status.active'); // nested key in cron.json

キー命名規則

• キー名には camelCase を使用します: copySuccess, scheduledTasks
• 関連するキーはネストでグループ化します: status.active, actions.pause
• 再利用可能なテキストは common.json に配置します: save, cancel, delete, confirm など
• 機能固有のテキストは対応するモジュールに配置します

一般的なサフィックス

サフィックス	用途
title	セクション/ページのタイトル
placeholder	入力欄のプレースホルダー
label	フォームのラベル
success / error	ステータスメッセージ
confirm	確認ダイアログ
empty	空の状態のメッセージ
tooltip	ツールチップのテキスト

新しいテキストの追加 — ワークフロー

ステップ 1: src/common/config/i18n-config.json を読み込む

現在の言語一覧とモジュール一覧を取得します。このステップを飛ばさないでください。

ステップ 2: 既存のキーを確認する

新しいキーを追加する前に、類似の既存キーを検索してください:

grep -r "keyword" src/renderer/i18n/locales/en-US/

可能な場合は common.* キーを再利用してください。

ステップ 3: 適切なモジュールを選ぶ

機能領域に合ったモジュールを選択します。適合するモジュールがない場合は、新しいモジュールが必要かどうかを検討してください（後述の「新しいモジュールの追加」を参照）。

ステップ 4: すべてのロケールディレクトリに追加する

重要: 新しいキーはすべて、supportedLanguages に含まれる すべて のロケールに追加する必要があります。各キーについて次のチェックリストを使用してください:

• en-US/<module>.json — 基準言語（ステップ 3 で追加）
• zh-CN/<module>.json — 追加済み
• zh-TW/<module>.json — 追加済み
• src/common/config/i18n-config.json → supportedLanguages に記載されているその他の言語 — 追加済み

1 つのロケールでもキーが欠けていると、CI で node scripts/check-i18n.js が失敗します。

ステップ 5: コンポーネントで使用する

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();
  return <button>{t('common.save')}</button>;
}

ステップ 6: 型を再生成して検証する

以下の 2 つのコマンドを この順序で 実行してください。コミット前に両方とも成功している必要があります:

bun run i18n:types          # Step A: regenerate i18n-keys.d.ts from reference locale
node scripts/check-i18n.js  # Step B: validate structure, keys, and type sync

• check-i18n.js より前に i18n:types を実行する必要があります。このチェックは生成されたファイルを検証するためです
• check-i18n.js がエラー（❌）で終了した場合は、先に修正してから進んでください
• check-i18n.js が警告のみ（⚠️）で終了した場合は、確認したうえで進めて構いません
• 古い i18n-keys.d.ts のままコミットしないでください

新しいモジュールの追加

1. src/common/config/i18n-config.json → modules 配列にモジュール名を追加します
2. すべての ロケールディレクトリに <module>.json を作成します（どの言語かは supportedLanguages を読んで確認してください）
3. 各ロケールの index.ts に import と export を追加します
4. bun run i18n:types を実行して型定義を再生成します
5. node scripts/check-i18n.js を実行して検証します

ハードコードされた文字列の検出

禁止パターン

JSX 内でハードコードされた中国語・英語のテキストを使用しないでください:

// Bad
<span>重命名</span>
<span>Delete</span>
{name || '新对话'}

// Good
<span>{t('common.rename')}</span>
<span>{t('common.delete')}</span>
{name || t('conversation.newConversation')}

例外

• コードコメント（任意の言語で可）
• console.log() / デバッグ出力
• ユーザーに表示されない内部の文字列定数

補間

変数

{
  "taskCount": "{{count}} task(s)",
  "greeting": "Hello, {{name}}!"
}

t('cron.taskCount', { count: 5 });

翻訳における HTML

複雑なマークアップには Trans コンポーネントを使用します:

import { Trans } from 'react-i18next';

<Trans i18nKey='cron.countdown'>
  Task <strong>{{ taskName }}</strong> in <span>{{ countdown }}</span>
</Trans>;

zh-TW のメンテナンス

ほとんどの用語は zh-CN から自動変換できますが、一部は手動でレビューが必要です:

zh-CN	zh-TW	Notes
视频	影片	Different term
软件	軟體	Different term
信息	訊息	Different term
默认	預設	Different term

クイックチェックリスト

新しいテキストを含むコードを送信する前に:

• src/common/config/i18n-config.json を読み、現在の言語とモジュールを確認する
• ユーザーに表示されるすべてのテキストで t() 関数を使用している
• supportedLanguages 内のすべての locale ディレクトリに新しいキーを追加した
• JSX に中国語・英語をハードコーディングしていない
• zh-TW で用語の違いを確認した
• 先に bun run i18n:types を実行した（i18n-keys.d.ts が再生成される）
• 型の再生成後に node scripts/check-i18n.js がエラーなしで通過した

よくある間違い

間違い	正しい方法
言語数が固定だと仮定する	必ず先に i18n-config.json を読む
一部の locale にだけキーを追加する	supportedLanguages 内のすべての locale に追加する
i18n-keys.d.ts を手動で編集する	bun run i18n:types を実行して生成する
t("New Chat") を使用する	キーを定義する: t("conversation.newChat")
新しいモジュールのために設定を更新しない	先に設定を更新してから、ファイルを作成する
モジュールの JSON を追加したが index.ts を更新しない	各 locale の index.ts に import と export を追加する必要がある