Localization & i18n スキル

概要

このスキルは、ドキュメントの国際化（i18n）と 地域化（l10n）のベストプラクティスを提供します。 翻訳しやすい原文作成から、多言語ワークフロー構築まで対応。

基本概念

i18n vs l10n

ローカライゼーションの 5 層

1. テキスト翻訳      ← 文字列の翻訳
2. フォーマット適応   ← 日付・数値・通貨
3. 文化的適応       ← 例・比喩・画像
4. 機能的適応       ← 入力方式・レイアウト
5. 法的適応        ← プライバシー・規制

翻訳しやすい原文設計

文章構造の原則

シンプルな文構造:

❌ 避ける:
「設定ファイルを編集後、変更を保存してからアプリを再起動すると、
新しい設定が反映されます。」

✅ 推奨:
「1. 設定ファイルを編集します。 2. 変更を保存します。 3. アプリを再起動します。
これで新しい設定が反映されます。」

能動態を使用:

❌ 受動態: 「設定はシステムによって読み込まれます」
✅ 能動態: 「システムが設定を読み込みます」

避けるべき表現

具体例

❌ 「これをクリックすると、あれが開きます」
✅ 「[保存]ボタンをクリックすると、確認ダイアログが開きます」

❌ 「一石二鳥のソリューション」
✅ 「2 つの問題を同時に解決するソリューション」

❌ 「アプリの起動」（名詞化）
✅ 「アプリを起動する」（動詞）

変数と文字列結合

問題のあるパターン

// ❌ 語順依存の文字列結合
message = "You have " + count + " new messages";
// 日本語: "新しいメッセージが" + count + "件あります"
// 語順が異なり、単純な置換では対応不可

// ✅ プレースホルダー使用
message = t("new_messages", { count: count });
// en: "You have {count} new messages"
// ja: "新しいメッセージが{count}件あります"

複数形の処理

# ❌ 単純な条件分岐
message_one: "{count} file selected"
message_other: "{count} files selected"

# ✅ ICU MessageFormat
message: "{count, plural,
  =0 {No files selected}
  =1 {1 file selected}
  other {{count} files selected}
}"

# 日本語版（複数形なし）
message: "{count}個のファイルを選択しました"

コンテンツ構造

ディレクトリ構造

docs/
├── ja/                     ← 日本語（ソース言語）
│   ├── getting-started/
│   │   ├── quickstart.md
│   │   └── installation.md
│   └── guides/
│       └── configuration.md
│
├── en/                     ← 英語
│   └── [同じ構造]
│
├── zh-Hans/                ← 簡体字中国語
│   └── [同じ構造]
│
└── _shared/                ← 言語共通リソース
    ├── images/
    ├── diagrams/
    └── code-samples/

言語コード規約

日付・数値・通貨

フォーマット比較

実装パターン

// ❌ ハードコーディング
const date = year + "/" + month + "/" + day;

// ✅ Intl API使用
const date = new Intl.DateTimeFormat(locale).format(dateObj);

// ❌ 通貨記号のハードコーディング
const price = "¥" + amount;

// ✅ Intl API使用
const price = new Intl.NumberFormat(locale, {
  style: "currency",
  currency: currencyCode,
}).format(amount);

翻訳メモリとスタイルガイド

用語集（Glossary）

# terms.yaml
terms:
  - source: "設定"
    translations:
      en: "Settings"
      zh-Hans: "设置"
    context: "UI要素として使用する場合"
    notes: "Configurationとは区別する"

  - source: "保存"
    translations:
      en: "Save"
      zh-Hans: "保存"
    context: "データの永続化"
    notes: "ファイル出力はExportを使用"

スタイルガイド項目

## 翻訳スタイルガイド

### 敬語レベル

- UI: です・ます調
- エラーメッセージ: 丁寧語
- 技術文書: である調も可

### 用語の一貫性

- 同一概念には同一訳語を使用
- 用語集を必ず参照

### 文体

- 簡潔で明確な表現
- 1 文は 40 文字以内を目安

UI テキストの i18n

レイアウト考慮

英語: "Save"     (4文字)
日本語: "保存"    (2文字)
ドイツ語: "Speichern" (9文字)
アラビア語: "حفظ"     (3文字、RTL)

対策:

• ボタン幅を可変に設計
• テキストが長くなることを想定（英語の 1.5 倍）
• RTL 言語を考慮したレイアウト

エスケープと特殊文字

# 特殊文字の処理
messages:
  # ❌ HTMLタグ埋め込み
  highlight: "Click <strong>here</strong>"

  # ✅ プレースホルダー使用
  highlight: "Click {start_bold}here{end_bold}"

  # ❌ 改行のハードコーディング
  multiline: "Line 1\nLine 2"

  # ✅ 配列または専用フォーマット
  multiline:
    - "Line 1"
    - "Line 2"

翻訳ワークフロー

標準プロセス

1. 原文作成
   ├── i18n対応チェック
   └── 翻訳準備確認
       ↓
2. 翻訳依頼
   ├── コンテキスト提供
   ├── 用語集共有
   └── スタイルガイド共有
       ↓
3. 翻訳実施
   ├── CAT（翻訳支援）ツール使用
   └── 翻訳メモリ活用
       ↓
4. レビュー
   ├── 技術レビュー
   ├── 言語レビュー
   └── 文化的適切性確認
       ↓
5. 統合
   ├── ファイル統合
   ├── ビルド確認
   └── 表示テスト

翻訳優先度

品質チェックリスト

原文チェック

• 文が短く、シンプルか？
• 能動態を使用しているか？
• 慣用句・比喩を避けているか？
• 代名詞の参照が明確か？
• 文化依存の例を避けているか？
• 変数はプレースホルダーを使用しているか？
• 複数形は適切に処理されているか？

翻訳品質チェック

• 用語の一貫性が保たれているか？
• 文脈に適した訳になっているか？
• 敬語レベルは適切か？
• 技術用語は正確か？
• 文化的に適切な表現か？
• UI 要素は正しく表示されるか？

リソース参照

関連スキル

• .claude/skills/user-centric-writing/SKILL.md: ユーザー中心ライティング
• .claude/skills/information-architecture/SKILL.md: 情報アーキテクチャ