localize

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

ローカライズとは、文字列を置き換えるだけではありません。レイアウト、書式、コンテンツ、操作パターンを調整し、あらゆる市場のユーザーに、後付けではなく意図をもって作られた製品だと感じてもらうことです。

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

必須の準備

ユーザーは /localize を使ってこのワークフローを開始します。このスキルが有効になったら、$frontend-design を読み込んでください。デザイン原則、アンチパターン、コンテキスト収集プロトコルが含まれています。作業を進める前に、そのプロトコルに従ってください。デザインコンテキストがまだ存在しない場合は、必ず最初に $setup を読み込んでください。さらに、現在および今後対象とする市場と言語、製品がコンテンツ中心か 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 戦略（1 つ選び、統一してください）：

• サブディレクトリ：/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)	フック／コンテキストを使ったコンポーネント単位の翻訳
Vue	vue-i18n	Composition API または Options API を使う Vue 2/3
Svelte	svelte-i18n、typesafe-i18n	軽量で、ストアベースのリアクティビティが必要な場合
Vanilla JS／フレームワークに依存しない構成	i18next、FormatJS IntlMessageFormat	複数のスタックで共有する場合や、プラグインエコシステムが充実している場合
ビルド時の抽出	Lingui、typesafe-i18n	バンドルを小さくし、実行時の解析を避けたい場合
実行時の抽出	i18next、react-i18next	動的な読み込みや CMS 主導のコンテンツが必要な場合
翻訳管理	Phrase、Lokalise、Crowdin、Smartling	チームでの共同作業、TMS ワークフロー、コンテキスト内編集が必要な場合

実践的なルール：

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

実装に関する考慮事項

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

余白の確保：

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

コンテナーの挙動：

• コンテンツの長さに適応する flexbox と grid を優先します
• テキストの折り返しを許可し、ラベルを 1 行に固定しないでください
• テキストの拡張によって利用可能なスペースを超えた場合の切り詰めの挙動をテストします

RTL と双方向テキスト

CSS の論理プロパティ：

/* Use logical properties for margins, padding, borders */
margin-inline-start: 1rem;
padding-inline: 1rem;
border-inline-end: 1px solid;

方向を考慮した変換：

[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 アノテーションを使用する
• 法務およびコンプライアンスに関する文言が地域ごとに適切で、認証を受けている
• 翻訳ワークフローが文書化され、リリースのサイクルに組み込まれている
• 実際の翻訳を始める前に、疑似ローカライズでレイアウトとテキスト切り捨てのチェックに合格している