i18n & ローカライゼーション

国際化 (i18n) とローカライゼーション (L10n) のベストプラクティス。

---

1. コアコンセプト

用語	意味
i18n	国際化 - アプリを翻訳可能にすること
L10n	ローカライゼーション - 実際の翻訳
ロケール	言語 + 地域 (en-US, tr-TR)
RTL	右から左の言語 (アラビア語、ヘブライ語)

---

2. i18n を使用する場合

プロジェクトタイプ	i18n が必要？
公開ウェブアプリ	✅ はい
SaaS プロダクト	✅ はい
内部ツール	⚠️ おそらく
単一地域アプリ	⚠️ 将来を考慮
個人プロジェクト	❌ オプション

---

3. 実装パターン

React (react-i18next)

import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome.title')}</h1>;
}

Next.js (next-intl)

import { useTranslations } from 'next-intl';

export default function Page() {
  const t = useTranslations('Home');
  return <h1>{t('title')}</h1>;
}

Python (gettext)

from gettext import gettext as _

print(_("Welcome to our app"))

---

4. ファイル構造

locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
└── ar/          # RTL
    └── ...

---

5. ベストプラクティス

すべき こと ✅

• 生のテキストではなく翻訳キーを使用する
• 機能ごとに翻訳を名前空間で分ける
• 複数形に対応する
• ロケールごとに日付/数値フォーマットを処理する
• 最初から RTL を考慮する
• 複雑な文字列には ICU メッセージ形式を使用する

してはいけない こと ❌

• コンポーネント内に文字列をハードコードする
• 翻訳された文字列を連結する
• テキスト長を想定する (ドイツ語は30% 長くなる)
• RTL レイアウトを忘れる
• 同じファイルに言語を混在させる

---

6. よくある問題

問題	解決策
翻訳が見つからない	デフォルト言語にフォールバック
ハードコードされた文字列	リンター/チェッカースクリプトを使用
日付フォーマット	Intl.DateTimeFormat を使用
数値フォーマット	Intl.NumberFormat を使用
複数形対応	ICU メッセージ形式を使用

---

7. RTL サポート

/* CSS 論理プロパティ */
.container {
  margin-inline-start: 1rem;  /* margin-left ではなく */
  padding-inline-end: 1rem;   /* padding-right ではなく */
}

[dir="rtl"] .icon {
  transform: scaleX(-1);
}

---

8. チェックリスト

リリース前に確認:

• ユーザー向けのすべての文字列が翻訳キーを使用している
• サポートされているすべての言語のロケールファイルが存在する
• 日付/数値フォーマットが Intl API を使用している
• RTL レイアウトがテストされている (該当する場合)
• フォールバック言語が設定されている
• コンポーネント内にハードコードされた文字列がない

---

スクリプト

スクリプト	目的	コマンド
scripts/i18n_checker.py	ハードコードされた文字列と欠落している翻訳を検出	python scripts/i18n_checker.py <project_path>

使用する場合

このスキルは、概要に記載されているワークフローまたはアクションを実行する場合に適用されます。

制限事項

• このスキルは、タスクがうえで説明されたスコープに明確に一致する場合のみ使用してください。
• 出力を環境固有の検証、テスト、またはエキスパートレビューの代替としては扱わないでください。
• 必要な入力、権限、セキュリティ境界、または成功基準が不明な場合は中止し、明確化を求めてください。