localize

あらゆる対応ロケールで、単に翻訳しただけでなく、自然に感じられるインターフェースを構築し、保守します。

ローカライズは、文字列を差し替えるだけではありません。あらゆる市場のユーザーが、製品を後付けではなく意図的に作られたものとして体験できるよう、レイアウト、書式、コンテンツ、操作パターンを適応させることです。

言語セレクター、国選択メニュー、通貨選択メニュー、地域設定コントロールを設計する際は、言語とロケールの選択のリファレンスを参照してください。 ロケールを問わず、キーボードで操作でき、スクリーンリーダーにも対応する必要があるカスタムコンポーネントをローカライズする際は、コンポーネントのアクセシビリティのリファレンスを参照してください。 検証メッセージ、エラー状態、復旧フローをローカライズする際は、エラーからの復旧のリファレンスを参照してください。 日付、時刻、カレンダーのパターンをロケールの慣習に合わせて調整する際は、日付入力のUXおよび日時ピッカーのUXのリファレンスを参照してください。

必須の事前準備

frontend-designを読み、コンテキスト収集プロトコルに従ってください。利用可能なコンテキストを再利用し、重大な不足点についてのみ質問してください。さらに、現在および次の対象市場と言語、製品がコンテンツ中心かUI中心か、翻訳を社内、代理店、TMSのいずれで行うかを確認してください。

ローカライズの範囲を評価する

変更が必要な対象と、適応の深さを把握します。

1. コンテンツの対象範囲：

   • 静的なUI文字列（ラベル、ボタン、見出し、空の状態）
   • 動的なユーザー生成コンテンツ（名前、説明、コメント）
   • マーケティングおよび法務関連の文言（規約、プライバシー、コンプライアンス）
   • エラーメッセージと検証フィードバック
   • 通知、メール、製品外のメッセージ

2. 書式と慣習：

   • 日付、時刻、カレンダーの書式（ISO形式とローカライズされた表示）
   • 数値の書式（小数点記号、桁区切り、通貨）
   • 計量単位（メートル法とヤード・ポンド法、通貨記号）
   • 住所と電話番号の書式
   • 名前の順序（名が先か、姓が先か）
   • 並べ替えと照合の規則

3. レイアウトと構造の調整：

   • テキストの拡張と縮小（ドイツ語は+30％、日本語は-10％）
   • 右から左（RTL）に書く文字体系への対応要件
   • 縦書きテキストや複数の文字体系が混在するレイアウト
   • 読み進める方向とスキャンパターン

4. コンテンツと法的な違い：

   • 地域固有の機能やカタログの提供状況
   • 法的要件（GDPR、CCPA、各地の税制、年齢確認）
   • 支払い方法と通貨への対応
   • 文化的なイメージ、色、象徴

ローカライズのアーキテクチャ

文字列管理の方針

キーによる抽出：

• 説明的で階層的なキーを使用します：checkout.shipping.title、errors.email.required
• キーに英語の文章を使わないでください。原文が変更されると問題になります
• 翻訳者向けのコンテキストコメントを追加します：// 配送フォームのボタンラベルとして使用
• ファイルを管理しやすくするため、機能またはルートごとに名前空間を分けます

メッセージ形式：

• 補間、複数形、性別にはICU MessageFormatを使用します
• コード内で文字列を連結しないでください。翻訳者には全文が必要です

// Good: complete sentence with interpolation
{count, plural, =0 {No items} one {# item} other {# items}} in your cart

// Bad: concatenated fragments
t('items_prefix') + count + t('items_suffix')

ソース言語の運用規律：

• ソース言語（通常は英語）を開発上の契約として扱います
• 翻訳を前提にソース文字列を作成します。完全な文章にし、代名詞の指す対象を明確にし、慣用句を避けてください
• 翻訳者に送る前に、翻訳しやすいソース文になっているか確認します

ロケールのネゴシエーションとルーティング

URL 戦略（いずれかを選び、統一してください）：

• サブディレクトリ：/en/products、/de/products — SEO に適しており、共有しやすく、明確です
• サブドメイン：en.example.com、de.example.com — 分離は明確ですが、保守が難しくなります
• クエリパラメーター：?lang=de — 実装は最も簡単ですが、SEO と共有には最も不向きです

ロケールの検出順序：

1. ユーザーが明示的に設定した優先言語（アカウントまたは Cookie に保存）
2. URL のパスまたはサブドメイン
3. ブラウザーの Accept-Language ヘッダー
4. ジオロケーション（補助的なデフォルトとしてのみ使用し、強制リダイレクトには使用しないでください）

ロケールの保持：

• 認証済みの場合、明示的に選択された設定をユーザープロフィールに保存します
• 匿名の訪問者には Cookie を使用し、再訪時もその設定を尊重します
• 自動検出によって明示的な選択を上書きしないでください

ライブラリとツールの選定

ニーズ	有力な選択肢	使用する場面
React フレームワーク	react-i18next、Lingui、FormatJS (react-intl)	フック／コンテキストを使ったコンポーネント単位の翻訳
Next.js	next-intl、next-international、Lingui、FormatJS	App Router に対応したロケールルーティングとサーバー／クライアントの境界
React アイランドを使用する Astro	Astro の i18n ルーティングと、アイランド内の React i18n	静的コンテンツは Astro ネイティブのままにし、インタラクティブなアイランドの文言は React と互換性を保つ
ビルド時の抽出	Lingui	バンドルサイズを抑え、実行時の解析を不要にする
実行時の抽出	i18next、react-i18next	動的な読み込みや CMS 主導のコンテンツ
翻訳管理	Phrase、Lokalise、Crowdin、Smartling	チームでの共同作業、TMS ワークフロー、コンテキスト内編集

実用的なルール：

• プロジェクトごとに i18n ライブラリは 1 つにすることを推奨します。複数のライブラリを使うと、キーの規約や読み込み動作が分断されます。
• プロジェクトが小規模で静的な場合は、JSON／PO ファイルを使ったビルド時の抽出で十分です。
• 翻訳が頻繁に変更される場合や、開発者以外が編集する場合は、早い段階で TMS を統合してください。

実装上の観点

テキストの拡張とレイアウトの柔軟性

スペースの確保：

• ドイツ語、フィンランド語など、テキストが長くなりやすい言語向けに、水平方向のスペースを 30～40% 多く確保します
• 最も短い言語（中国語、日本語）では、余白が過剰になったり、視覚的なリズムが崩れたりしないかテストします
• ボタン、ラベル、ナビゲーション項目には固定幅ではなく、最小幅／最大幅を使用します

コンテナーの挙動：

• コンテンツの長さに合わせて適応する Flexbox と Grid を優先します
• テキストの折り返しを許可し、ラベルを 1 行に固定しないでください
• テキストの拡張が利用可能なスペースを超えた場合の切り捨て動作をテストします

RTL と双方向テキスト

Tailwind の論理的なスペーシングとボーダーのユーティリティ：

• 使用可能な場合は、論理的なユーティリティと方向を考慮したバリアントを優先します
• プロジェクトでユーティリティではカバーされていない論理プロパティが必要な場合に限り、Tailwind の任意プロパティを使用します

方向を考慮した変換：

[dir="rtl"] .arrow { transform: scaleX(-1); }
[dir="rtl"] .timeline { flex-direction: row-reverse; }

反転に関する考慮事項：

• ナビゲーション、パンくずリスト、戻るボタンは反転します
• 物理的な物体を表すアイコン（時計、テキストカーソル）は反転しないでください
• 方向を示すアイコン（矢印、山形、進捗インジケーター）は反転します
• RTL を母語とする話者にテストしてもらいましょう。機械的な反転では、文化的なパターンを見落としがちです

表示形式とデータ表示

日付と時刻：

• Intl.DateTimeFormat またはライブラリの同等機能を使用し、書式文字列をハードコードしないでください
• ロケールごとの 12 時間制／24 時間制の慣習を尊重します
• 該当する場合は、暦法（グレゴリオ暦、仏暦、イスラム暦）も考慮します

数値と通貨：

• 桁区切り、小数、通貨記号には Intl.NumberFormat を使用します
• 通貨記号の位置はロケールによって前後します（$1,234.56 と 1.234,56 € など）
• 複数通貨を扱う場合は、明確さのため、記号と併せて通貨コード（USD、EUR）を表示します

複数形、序数、文法：

• ICU MessageFormat の複数形ルールを使用し、英語の one/other を前提にしないでください
• アラビア語には 6 つ、ポーランド語には 4 つ、ウェールズ語には 6 つの複数形があります
• 性による文法の変化や序数（1st、2nd、3rd）は、コードのロジックではなくメッセージ形式で処理します

文字列以外のコンテンツ

画像とメディア：

• 可能な限り、画像内のテキストを通常のテキストに置き換えます
• ビジュアルに文化固有のコンテンツが含まれる場合は、ロケールごとに画像セットを用意します
• アイコンや図には SVG を使用します。拡大縮小や反転をよりきれいに行えます

URL と SEO：

• 言語や地域ごとのバリエーションを示すには、hreflang アノテーションを使用します
• 正規 URL にロケールを含めます
• ページコンテンツだけでなく、メタタイトルと説明もローカライズします
• URL スラッグには、そのロケールに適さないキーワードを使用しないでください

法務およびコンプライアンス関連のコンテンツ：

• 地域ごとの法務文言（利用規約、プライバシー、Cookie に関する通知）を維持します
• 法務文書を自動翻訳しないでください。認定を受けた法務翻訳者を利用してください
• コンプライアンス関連のコンテンツは、法域ごとにバージョン管理します

翻訳ワークフロー

開発者からの引き継ぎ：

1. コードから文字列を抽出し、翻訳ファイル（JSON、PO、YAML）に格納します
2. 曖昧な文字列には、コンテキストのコメントとスクリーンショットの参照を追加します
3. 翻訳中に変更が発生しないよう、翻訳に出す前に原文の文字列を確定します
4. コードのリリースに合わせて翻訳ファイルをバージョン管理します

品質保証：

• 翻訳の切り詰め、はみ出し、レイアウト崩れを確認します
• プレースホルダーと HTML タグが保持されていることを検証します
• 性別による表現が意図されたコンテキストに合っていることを確認します
• 実際の翻訳の前に疑似ローカライズ（アクセント記号を使った文字列の拡張）を実施し、レイアウトの不具合を早期に発見します

継続的なローカライズ：

• TMS をバージョン管理（GitHub/GitLab の Webhook）と連携します
• プルリクエスト時に抽出を自動化します
• 翻訳メモリを設定して、コストを削減し、一貫性を高めます
• 新規または変更されたキーを翻訳者に速やかに通知します

ローカライズされた UI のテスト

レイアウトテスト：

• サポート対象言語のうち、文字列が最も長くなる言語と最も短くなる言語でテストします
• ブラウザーの方向切り替え機能を使って、RTL レイアウトを検証します
• ビューポート幅が最小および最大の場合に、切り詰め、折り返し、はみ出しを確認します

機能テスト：

• すべてのロケールで補間変数が正しく反映されることを検証します
• 複数形のルールが正しく表示されることを確認します（0、1、2、5、11、21 件）
• 該当する場合は、ページ全体を再読み込みせずにロケールを切り替えられることをテストします
• ログアウト後に再ログインしても、保存されたロケール設定が保持されることを検証します

コンテンツテスト：

• 翻訳の正確さと文体の一貫性を抜き取り確認します
• 法務およびコンプライアンス関連の文言が認定済みのバージョンと一致することを検証します
• ローカライズされた URL と SEO メタデータが用意されていることを確認します

アンチパターン

• 翻訳済みの断片を連結する：翻訳者には完全な文が必要です。t('you_have') + count + t('messages') のような連結は、ほとんどの言語で問題を引き起こします。
• ロケールに関する前提をハードコードする：左から右への表記、12 時間制、MM/DD/YYYY、英語の複数形ルールを前提にしないでください。
• レビューせずに UI を自動翻訳する：UI 文字列の機械翻訳は、用語の不統一や文法の崩れにつながります。
• テキストの拡張を無視する：幅が固定されたボタンやラベルは、ドイツ語など文字列が長くなりやすい言語で崩れます。
• 言語を国旗で表す：国旗が表すのは国であり、言語ではありません。スペイン語を話す国は 20 か国以上、英語を話す国は数十か国あります。言語名または中立的なアイコンを使用してください。
• IP アドレスだけでリダイレクトする：旅行者、VPN ユーザー、海外在住者が誤ったロケールに固定されることがあります。強制せず、提案してください。
• 疑似ローカライズを省略する：実際の翻訳の前に疑似ロケールでテストすれば、修正コストが低いうちにレイアウトや切り詰めの不具合を発見できます。
• バージョン管理せずに翻訳をバージョン管理に保存する：ロールバックできるよう、コードと合わせて翻訳ファイルにもタグを付け、リリースする必要があります。
• エラーメッセージのローカライズを忘れる：未翻訳の検証エラーは、ユーザーの混乱や離脱を招く一般的な原因です。
• ローカライズを一度限りのプロジェクトとして扱う：言語は変化し、製品には機能が追加され、市場も変わります。ローカライズは継続的なメンテナンスです。

ローカライズ対応状況の確認

ローカライズした製品をリリースする前に、以下を確認してください。

• ユーザーに表示されるすべての文字列を抽出してキーを設定し、ハードコードしない
• 原文を翻訳しやすい内容にするため、完全な文になっているか、慣用表現が含まれていないかを確認する
• 対象言語のうち、最も長い言語と最も短い言語でレイアウトをテストする
• 論理プロパティと方向を考慮したテストにより、RTL スクリプトに対応する
• 日付、数値、通貨の書式設定には、ロケールに対応した API を使用する
• 複数形の処理が、対象言語のすべての複数形に正しく対応している
• ロケールを切り替えても、ユーザーのコンテキストと状態が維持される
• URL にロケールを含め、hreflang アノテーションを使用する
• 法務およびコンプライアンスに関する文言が地域ごとに適切で、認証を受けている
• 翻訳ワークフローが文書化され、リリースのサイクルに組み込まれている
• 実際の翻訳を始める前に、疑似ローカライズでレイアウトとテキスト切り捨てのチェックに合格している