i18n-localization

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. ベストプラクティス

DO ✅

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

DON'T ❌

• コンポーネント内に文字列をハードコードする
• 翻訳済み文字列を連結する
• テキストの長さを決めつける（ドイツ語は 30% 長くなります）
• RTL レイアウトを忘れる
• 同じファイル内で複数の言語を混在させる

---

6. よくある問題

問題	解決策
翻訳の欠落	デフォルトの言語にフォールバックする
文字列のハードコード	リンター／チェッカースクリプトを使用する
日付形式	Intl.DateTimeFormat を使用する
数値形式	Intl.NumberFormat を使用する
複数形	ICU メッセージ形式を使用する

---

7. RTL サポート

/* CSS Logical Properties */
.container {
  margin-inline-start: 1rem;  /* Not margin-left */
  padding-inline-end: 1rem;   /* Not padding-right */
}

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

---

8. チェックリスト

リリース前に確認してください。

• ユーザーに表示されるすべての文字列で翻訳キーを使用している
• サポート対象のすべての言語について、ロケールファイルが存在する
• 日付／数値の書式設定に Intl API を使用している
• RTL レイアウトをテストしている（該当する場合）
• フォールバック言語を設定している
• コンポーネント内にハードコードされた文字列がない

---

スクリプト

同梱のチェッカーはヒューリスティック方式で、対象はソートされたソースファイルの先頭 50 個までです。英語に偏った正規表現とディレクトリベースの JSON ロケールのグループ化を使用しており、gettext カタログと messages/en.json のレイアウトではキーの一致を完全には確認できません。実際にサンプル抽出／検出した件数と解析エラーを報告してください。サンプルに問題がなくても、完全性、翻訳品質、アクセシビリティが保証されるわけではありません。RTL では、方向を示すアイコン（ナビゲーション矢印など）のみを反転し、すべてのロゴ、画像、メディアコントロールを反転しないでください。

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

使用する場面

このスキルは、概要で説明されているワークフローまたはアクションを実行する際に適用できます。

制限事項

• このスキルは、タスクが上記の適用範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。