i18n & ローカリゼーション
選択的読み取りルール
まず以下を参照してください:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
その後、ユーザーの実際のタスクに一致する継承されたドキュメント、スクリプト、アセット、または例のみを読み込んでください。
国際化(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> |