このガイドでは、AI生成アプリを国際化(i18n)し、ローカライズする方法を解説します。扱う内容は、キー設計、ロケールファイル、文字列の抽出、用語集、そしてUIが頻繁に変わっても壊れない自動化です。globalize.nowはAIを活用したローカライズ基盤で、プッシュのたびにGitと連携して翻訳カタログを最新の状態に保ちます。一度セットアップすれば、あとはプッシュごとに自動同期され、ファイルを手動でやり取りする手間もなくなります。AIファーストのコードベースでi18n層が後回しにされがちな理由については、AI Code Broke Localization and Nobody Fixed Itをご覧ください。ツールの世代ごとの業界動向は、3 Stages of Localization Development (And Why AI Changes Everything)で紹介しています。リポジトリがまだ整理されていない段階でのベンダー選定の順序については、globalize.now vs Lokalise vs Crowdinと、実際に手を動かして進めるHow to Globalize Your App with globalize.nowが参考になります。
「AI生成アプリをローカライズする」とは実際どういうことですか?
**ローカライズ(l10n)**はユーザーに見える部分です:そのロケールに合った正しい言語、複数形、日付、通貨、レイアウトのことです。
**国際化(i18n)**はエンジニアが最初に行う作業です:ユーザーに表示されるテキストをアドレス可能にし、繰り返し利用できるようにし、大規模に翻訳しても安全な状態にすることです。
「まだローカライズできない」というブロッカーの多くは、実はi18nのブロッカーです。アーキテクチャを一度整えれば、ローカライズは発掘作業ではなく運用上の課題になります。
ツールを選ぶ前に、i18nアーキテクチャのチェックリストに含めるべき項目は何ですか?
翻訳管理ツールや翻訳ベンダーを選ぶ前に、次の基本要素がそろっているかを確認してください。まだない場合は、この順番で導入していくのがおすすめです:
- あなたのスタック(React、Next.js、Railsなど)に適したランタイムi18nライブラリで、UI文字列に対して単一の統一されたパターンをサポートしていること。
- IDとして英語の文をそのまま使うのではなく、安定した翻訳キー(名前空間分けされた階層構造)を使うこと。
- リポジトリにチェックインされる、またはCIで生成されるロケールリソースファイル(JSON、PO、YAMLなど)。
"{count} items"のような動的な表現に対するICU形式の複数形と変数により、翻訳者が安全に文法の語順を入れ替えられるようにすること。- 文字列抽出パイプラインにより、新しいUIがカタログを知らずに素通りしてしまうことを防ぐこと。
| 層 | 担当 | 典型的な失敗パターン |
|---|---|---|
| UIコード | t("…")のみを呼び出す | コンポーネント内にハードコードされた英語 |
| カタログ | キー、説明、最大文字数 | キーの重複、コンテキストの欠落 |
| ロケール | 言語ごとのメッセージ | 手動編集されたJSONがソースからずれる |
| コーディネーション/機械翻訳 | 人によるワークフロー、機械翻訳エンジン | 不正なキーや欠落文字列が渡される |
開発スピードを落とさずに文字列を抽出するには?
AI生成のリポジトリでは、「保存」「キャンセル」「詳しく見る」のような同じラベルが何十ものファイルで繰り返し使われがちです。抽出処理では次のことを行うべきです:
- コンポーネント、ルート、共通UIプリミティブに含まれるユーザーに表示されるリテラルを検出します。ただし、技術的な文字列(CSSクラス、アナリティクスID、ユーザーに表示されないURLなど)は対象外とします。
- 重複を1つのキーに正規化して参照させることで、翻訳者が単一の意味単位として認識できるようにすること。
- 新しいキーごとの正規値としてソースロケール(通常は英語)を出力すること。
- チームで合意したi18n APIを使うよう、呼び出し箇所を機械的に書き換えます。これにより、差分をレビューしやすい状態を保てます。
Reactスタイルのコードでの最小限のビフォーアフターはこのようになります:
<button>Submit order</button>
抽出とキー付けを行った後:
<button>{t("checkout.submit_order")}</button>
// locales/en.json
{
"checkout.submit_order": "Submit order"
}
言語を増やす前に、用語集とスタイルガイドが重要な理由は?
機械翻訳は速いです。しかし制約を定義しないと、画面ごとにまるで別のプロダクトのように見えてしまうのも簡単に起こります。多言語に展開する前に、以下を書き出しておきましょう:
- 翻訳してはならないブランド用語(プロダクト名、機能名)。
- リスクの高い単語(「お問い合わせ」「トライアル」「請求」「ワークスペース」など)の推奨訳語。
- トーン:フォーマルか会話調か、二人称か中立的な表現か。
その用語集をコーディネーションツールや機械翻訳のプロファイルに反映させ、自動生成された翻訳がチームで既に決めた方針と一致し続けるようにしましょう。
翻訳QAループを自動チェックでどう支えるべきですか?
キーがロケールファイルに流れ込んだら、現代的なループはこうなります:機械翻訳の下書き → リンターチェック(文字数、プレースホルダー、禁止用語)→ 影響度の高い箇所での自動リグレッションチェック → リリース → 効果測定。自動化は時間を節約し、リンターは壊れたプレースホルダーをリリースしてしまう事態から守ってくれます。
CLIスタイルのツールを使えば、リポジトリ内にどれだけ作業が残っているかを素早く確認できます。例えば:
✔ Scanned 312 files
✔ Found 1,284 user-visible literals
✔ Proposed 920 translation keys (364 duplicates merged)
✔ Wrote locales/en.json
Next: sync translation-ready keys to your coordination tool or run an MT batch with glossary v1
ローカライズのリファクタリングをレビュー可能な状態に保つエージェントプロンプトとは?
これらのプロンプトは、テストとコードレビューが整っているリポジトリでの利用を想定しています。信頼できる差分を生み出すことが目的で、気づかないうちに広範囲へ及ぶリファクタリングを行うものではありません。
リファクタリングの前に、UI文字列の一覧をどう作成しますか?
You are analyzing a TypeScript React codebase for localization readiness.
Task: List every pattern where user-visible English might appear (JSX text, string props that render to the DOM, template literals interpolated into UI, aria-label/title/placeholder, toasts, empty states). Exclude className values, internal IDs, and URLs that are not shown to users.
Output: a table with columns: file path, line range, example string, recommended next step (extract key / ignore / needs product decision).
最小限の型付きt() APIを安全に導入するにはどうすればいいですか?
Add a minimal i18n helper used across the app: a typed t(key, vars?) function backed by JSON locale files in /locales. Do not translate yet; only wire English as the source locale.
Constraints:
- Keys use dot namespaces: "section.component.purpose"
- Support ICU-style pluralization for keys that need counts
- Add a dev-only warning when t() is called with a missing key
Show the file tree you created and example usage in two existing components.
リテラル文字列を名前空間付きキーに機械的に抽出するにはどうすればいいですか?
Refactor the following files to replace user-visible string literals with t("…") keys.
Rules:
- Prefer stable semantic keys, not English sentences as keys
- Deduplicate identical UI strings to one key
- Keep string interpolation correct using ICU message patterns
- Do not change layout/styling except where required by the refactor
After edits, print a JSON object mapping each new key to its English source string for translators.
翻訳者が信頼できる用語集CSVをどのように作成すればいいですか?
From locales/en.json and the product marketing pages in this repo, propose a glossary CSV with columns: term_en, part_of_speech, definition_for_translators, do_not_translate (true/false), allowed_synonyms, notes_for_de.
Flag terms that are legally sensitive (pricing, trials, refunds) and terms that are ambiguous in software ("session", "organization", "member").
新たなハードコード英語の混入を防ぐCIのガードレールとは?
Add a CI script that fails if new user-visible English literals appear in JSX outside of tests/fixtures.
Implementation guidance:
- Use the repo's existing package manager and test runner
- Provide a small allowlist file for exceptions (brand strings, intentional English)
- Print actionable file/line references on failure
Include README notes for how engineers should add exceptions responsibly.
これらのプロンプトは今でも手動でコピペする必要がありますか?
今はほとんど不要です。このガイドが最初に書かれた当時は、プロンプトをエージェントにコピー&ペーストするのが実践的なループの回し方でした。それ以降、ツール自体がエージェント側に組み込まれるようになりました:コーディングエージェントは今、MCPサーバーを通じてローカライズを直接呼び出せるため、抽出、キー付け、翻訳同期は、あなたが貼り付けるプロンプトではなく、エージェントが実行するツール呼び出しになります。セットアップについてはglobalize.now MCPのご紹介を、この変化がアーキテクチャ上なぜ重要なのかについてはローカライズはSDKではなくエージェントスキルになりつつあるをご覧ください。
上記のプロンプトは、レビュー用のチェックリストとしても有用です。人が貼り付けて使う場合でも、エージェントのスキルに組み込む場合でも、エージェント主導のi18nリファクタリングが満たすべき条件を示しています。自動化されたリファクタリングは、どれも同じ基準で評価してください。その基準とは、レビューしやすい差分、安定したキー、ICUに対応した安全な補間、そしてリグレッションを防ぐCIのガードレールです。
AI構築のプロダクトをローカライズする際、長期的に忘れてはならない制約は何ですか?
ローカライズは一度のスプリントで終わるものではなく、未来の自分との約束です。キー、カタログ、自動化に最初に投資しておけば、AIが生成する新しい画面も、世界へ届けるコストをぐっと抑えられます。
globalize.nowは、ハードコードされたアプリ内テキストを翻訳可能なロケールファイルに変換し、リリースのたびに自動で最新の状態を保ちます。
globalize.nowを無料で試す