@intlayer/docs 9.4.1 → 9.4.3

package/blog/ja/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "壊れやすいテストを作らずに翻訳をテストする方法"
+description: i18n対応アプリにおいてテストする価値があるものとないもの。Providerベースのレンダリングテスト、疑似多言語化、RTLと複数形のカバレッジ、そしてスナップショットの罠。
+keywords:
+  - 翻訳テスト
+  - i18n テスト
+  - testing library i18n
+  - 疑似ローカライゼーション
+  - locale provider test
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# 壊れやすいテストを作らずに翻訳をテストする方法
+
+多くのi18nテストスイートは、2つのパターンのいずれかで破綻します。1つは文言そのものをアサートしてしまうパターンで、文言を少し修正するたびに50個のテストが壊れ、チームは最終的にテストを削除してしまいます。もう1つはすべてをデフォルトロケールでのみ描画するパターンで、残りの17言語については何も検証できません。どちらも行き着く先は同じで、誰も信頼しないテストスイートになります。
+
+## 目次
+
+<TOC/>
+
+## パターンはライブラリに依存しません
+
+以下で紹介するパターンは、あらゆるi18nスタックで動作します。プロバイダーを `I18nextProvider`、`NextIntlClientProvider`、または `IntlProvider` に置き換えても、ライブラリの内部APIではなくレンダリングされた結果をアサートするため、テストコードは同一のままです。
+
+カバレッジ検証ツールも同様に移行可能です。[Sync JSONプラグイン](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/plugins/sync-json.md) を既存カタログに向けたり、[互換アダプター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/compat/index.md) を使って現在のインポートにエイリアスを張ることで、既存のJSONに対してそのままカバレッジ検証を実行できます。
+
+## 実際に何をテストしているのかを整理する
+
+翻訳品質はコードテストで検証するものではありません。ドイツ語が自然であるかどうかを判定できるアサーションは存在せず、それを試みるとテスト内にハードコードされた文字列が散乱するだけです。
+
+機械的にテストする価値があるのは以下の項目です。
+
+| テストする価値があるもの                        | テストする価値がないもの   |
+| :---------------------------------------------- | :------------------------- |
+| 必須ロケールすべてに値が存在する                | 言い回しが洗練されているか |
+| 適切なロケールがコンポーネントに届いている      | 各ラベルの厳密なテキスト   |
+| 各カテゴリの複数形が解決される                  | 翻訳者が正しく作業したか   |
+| RTLロケールで文字方向やミラーリングが適用される | 全ロケールの全文字列       |
+| フォーマットされた日付や数値がロケールに従う    | `Intl` 内部実装の正確性    |
+
+カバレッジの担保はコンポーネントテストではなく、単一のデータ駆動型テストで行うべきです。これについては [翻訳漏れを検出する方法](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/detecting_missing_translations.md) で詳しく解説しています。本記事ではそれ以外の部分を扱います。
+
+## Provider下で描画し、ロールでアサートする
+
+中核となるパターンは、コンポーネントをロケールプロバイダーでラップしてマウントし、テキストではなくロール（role）やテストIDでクエリすることです。
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renders the summary heading in French", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+`getByRole("heading")` によるクエリは文言の変更に耐えられますが、`getByText("Récapitulatif")` は文言変更で壊れます。文字列自体がテスト対象である稀なケースを除き、リテラル文字列によるクエリは避けましょう。
+
+`aria-label` のような属性にはレンダリングノードではなく未加工の文字列が必要です。Reactの場合、`useIntlayer` のエントリは `.value` フィールドを提供しています。
+
+## ロケールをまたいでテストをパラメータ化する
+
+言語ごとにテストを個別に書くよりも、1つのテストロジックをすべてのロケールに対して回すほうが価値があります。
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("キー名へフォールバックせずに描画される", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // キー名が表示されている場合はルックアップに失敗している
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("正しいテキスト方向が設定されている", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+1つ目のアサーションは手軽で効果的です。キーの取得に失敗してライブラリがキー名をそのまま描画すると、DOM内に `cart.summary.title` のような文字列が現れます。これにより、個別の文字列を検証することなく多くのバグを検知できます。
+
+## 疑似ローカライゼーションでカタログの盲点を突く
+
+すべての文字列を変換するテスト用ロケールを追加します（例: `Checkout` を `[!!! Çĥéçķöũţ !!!]` に変換）。そしてそのロケールでページを描画します。
+
+英語のまま残っている部分はソースコードに直書きされています。ツール側から見ればその文字列は存在しないため、カタログベースの監査では検出できません。また、前後のブラケットはテキストを約30%長くするため、ドイツ語を導入する前にレイアウト崩れを発見できる利点もあります。
+
+これは視覚的な破綻を見つける作業なので、ユニットテストではなくビジュアルリグレッションテストやE2Eテストとして実施するのが適しています。
+
+## 複数形テストは言語ごとではなくカテゴリごとに実施する
+
+複数形のバグは見落とされがちです。英語には2つの形式しかなく、多くの開発者はそれらしか検証しないためです。しかしポーランド語には4つ、アラビア語には6つの形式が存在します。
+
+```ts fileName="plural.test.ts"
+// アラビア語は zero, one, two, few, many, other を網羅します。
+describe.each([0, 1, 2, 3, 11, 100])("count %i", (count) => {
+  it("アラビア語で空文字にならない文字列を生成する", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+すべての言語で単に1と2をテストするのではなく、最も複雑な言語のCLDRカテゴリを網羅する数値を選びます。`Intl.PluralRules` を使えば数値がどのカテゴリに分類されるかが分かるため、推測に頼らずサンプルを決定できます。詳細は [ICUメッセージフォーマットの記事](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/icu_message_format.md) を参照してください。
+
+## スナップショットテストの罠
+
+スナップショットとi18nの相性は最悪です。ローカライズされたコンポーネントのスナップショットにはすべての文字列が含まれます。そのため、翻訳者がポルトガル語のタイポを修正しただけでテストが失敗し、レビュー担当者には判断できないdiffが生まれます。何度か繰り返すうちに、開発者はdiffを読まずに `-u` を実行するようになり、スナップショットは形骸化します。
+
+スナップショットを利用する場合は単一のロケールでのみ取得し、内容ではなく構造チェックとして扱いましょう。ロケール固有の検証はすべて明示的なアサーションで行うべきです。
+
+## 表示だけでなくロケール解決ロジックをテストする
+
+本番環境で最も頻発するi18nバグは、文字列の欠落ではありません。間違ったロケールが選択されることです。URLが `/fr/` であるにもかかわらず、クライアントが `navigator.language` を読み取って不整合が起きるケースです。
+
+コンポーネントから切り離し、解決順序を純粋関数としてテストします。
+
+```ts fileName="locale-resolution.test.ts"
+it("保存された設定よりもURLを優先する", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("URLにプレフィックスがない場合はヘッダーにフォールバックする", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+これは多くのプロジェクトで見過ごされている最も価値の高いi18nテストであり、DOMも不要です。
+
+## テストの配置基準
+
+- **Unit**: ロケールネゴシエーション、フォーマッター、複数形カテゴリ。DOM不要で高速。
+- **Component**: ロケールごとにProvider経由で描画し、ロールと未解決キーの有無を検証。
+- **Coverage**: 必須ロケールに未翻訳がないことを確認するデータ駆動テスト。
+- **Visual / E2E**: 疑似ローカライゼーションとRTLページの描画テスト（表示崩れを検出）。
+
+最初の3つはコミットごとにCIで実行します。最後の項目は夜間ビルドで定期実行するのが効率的です。
+
+## よくある失敗
+
+- **すべての箇所でリテラルテキストをアサートする。** 数ヶ月以内にテストスイートが破棄される原因になります。
+- **ローカライズされたコンポーネントをスナップショット化する。** 翻訳更新でビルドが止まり、レビューが形骸化します。
+- **デフォルトロケールしかテストしない。** 欠落するはずのない言語だけを検証しても意味がありません。
+- **複数形を1と2だけでテストする。** 英語に存在しないカテゴリを見落とします。
+- **i18nライブラリをモックで消してしまう。** 単にモックが文字列を返すことしかテストできません。
+- **ロケール解決ロジックをテストしない。** 本番環境で最も起きやすく、最も簡単に防げる問題です。
+
+## さらに学ぶ
+
+- [コンテンツのテスト: CLI監査、プログラムAPI、UIアサーション](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/testing.md)
+- [ESLintプラグイン: ハードコードされた文字列と未使用コンテンツの検出](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/eslint.md)
+- [フォーマッターとロケールユーティリティ（`getHTMLTextDir` を含む）](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/formatters.md)
+- [主要フレームワーク間のベンチマークレポート](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/benchmark/index.md)
+- [react-i18next互換アダプター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/compat/react-i18next.md)
+- [翻訳漏れを検出する方法](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/detecting_missing_translations.md)
+- [ICUメッセージフォーマット: 複数形、select、スケルトン](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/icu_message_format.md)

package/blog/ja/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/intlayer_with_next-intl.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` フラグはオプションです。AI エージェントの場合は `intlayer-cli init` を使用してください。

package/blog/ja/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: 2026年においてi18nextは時代遅れなのか？
+description: i18nextは数百万のWebサイトで利用されていますが、2011年設計のランタイムアーキテクチャには限界も見え始めています。バンドルサイズ、Tree-shakingの制約、進化の停滞を分析します。
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - 国際化
+  - i18n
+  - バンドルサイズ
+  - ブログ
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# 2026年においてi18nextは時代遅れなのか？
+
+`i18next`は2011年、ReactコンポーネントやWebpackによるバンドル、TypeScriptが普及するより遥か前に登場しました。その柔軟性と汎用性の高さから広く普及し、あらゆる技術スタックに対応するプラグインと、StackOverflowの豊富な知見を蓄積してきました。
+
+このプロジェクトは決して放棄されておらず、定期的に修正パッチが提供されています。しかし、既存の古いエンジンを保守することと、近年のフロントエンドアーキテクチャに合わせて進化し続けることの間には大きな隔たりがあります。
+
+ここ数年でフロントエンドは、ビルド時コンパイル、React Server Components（RSC）、徹底したTree-shaking、AIワークフローの統合へと舵を切りました。対照的にi18nextのコアは10年前と変わらず、クライアント側で文字列キーを検索するランタイムシングルトン構造のままです。
+
+<TOC/>
+
+## 主なポイント
+
+**メンテナンス中心の運用:**
+
+過去1年間で、`next-i18next`のコミット数は約63回（週に約1回）、`react-i18next`は約157回にとどまり、その大半は依存関係の更新や小規模なバグ修正です。
+
+**無視できないランタイムオーバーヘッド:**
+
+`react-i18next`と`next-i18next`は、翻訳テキストを1文字描画する前から約17〜18 KB（gzip圧縮後、Minifiedで約60 KB）のスクリプトをクライアントに注入します。これは`next-intlayer`（約4.7 KB）の約4倍です。
+
+**深刻なコンテンツ漏洩:**
+
+標準的な静的設定では、ページに配信される翻訳データの最大**89.8%**が、他のルートや現在表示されていない言語のデータで占められています。
+
+**Tree-shakingの困難さ:**
+
+`t("home.hero.title")`のような動的文字列呼び出しはバンドラー側で静的解析できず、JSONファイル全体がクライアントバンドルに含まれてしまいます。
+
+**ビジネス上のインセンティブ構造:**
+
+メンテナーは翻訳プラットフォームLocizeを運営しています。CLIに無料で利用可能なローカルAI翻訳パイプラインを統合することは、彼ら自身の収益モデルと競合することになります。
+
+## 保守と革新の比較
+
+GitHubのスター数は過去の実績を示す指標であり、現在の技術的な進化スピードを表すものではありません。
+
+| リポジトリ              | スター数                                                                                                                                                   | 総コミット数                                                                                                                                                            | 年間コミット数                                                                                                                                                         | 最終コミット                                                                                                                                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+過去12か月間の開発状況:
+
+| プロジェクト    | 累計コミット数 | 過去12か月 | 主な注力分野                              |
+| --------------- | -------------- | ---------- | ----------------------------------------- |
+| `next-i18next`  | 1,311          | **63**     | Next.js互換性の維持と不具合修正           |
+| `react-i18next` | 1,988          | **157**    | 型定義とメンテナンス                      |
+| `i18next` core  | 2,626          | **259**    | マイナー修正                              |
+| Intlayer        | 7,156          | **4,343**  | コンパイラ、IDEツール、AIエンジン等の開発 |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+成熟したライブラリは安定性という価値を提供します。しかし、i18nツールの基準は進化しています。ビルド時に不要なコンテンツを排除し、CIでLLMによる自動翻訳を行い、開発環境ではLanguage Server（LSP）やAIエージェントと統合される時代です。ランタイムに特化した従来の設計では、こうした技術的進展を取り入れるのが困難です。
+
+## バンドルへの影響検証
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 本番ビルド環境において10ルート、10言語、gzip圧縮の条件で測定。詳細は[i18nベンチマークレポート](https://intlayer.org/ja/doc/benchmark)に記載されています。
+
+### ライブラリ自体の基礎オーバーヘッド
+
+翻訳データを含まない、ライブラリ導入のみによるサイズ:
+
+| ライブラリ             | Gzip圧縮後 | Minified    |
+| ---------------------- | ---------- | ----------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB     |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB     |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB** |
+
+### ページサイズと不要コンテンツの混入率
+
+React / TanStack Start（静的戦略）での検証:
+
+| ライブラリ            | 平均ページJS (gz) | 他言語混入率 | 他ページ混入率 | 平均コンポーネント (gz) | ハイドレーション |
+| --------------------- | ----------------- | ------------ | -------------- | ----------------------- | ---------------- |
+| `react-i18next`       | 180.3 KB          | **50.0%**    | **89.8%**      | 24.3 KB                 | 85.1 ms          |
+| Intlayer              | **127.8 KB**      | 50.0%        | **0.8%**       | **7.1 KB**              | **24.1 ms**      |
+| Intlayer (scoped dyn) | **118.1 KB**      | **0.0%**     | **0.8%**       | **4.6 KB**              | 23.7 ms          |
+
+Next.jsでの測定結果:
+
+| ライブラリ         | 平均ページJS (gz) | 他ページ混入率 | 平均コンポーネント (gz) |
+| ------------------ | ----------------- | -------------- | ----------------------- |
+| ベース（i18nなし） | 150.8 KB          | 0.0%           | 0.7 KB                  |
+| `next-i18next`     | **227.5 KB**      | **89.8%**      | 24.5 KB                 |
+| `next-intlayer`    | **152.1 KB**      | **0.0%**       | **7.2 KB**              |
+
+### 測定結果のポイント
+
+**ページ全体の肥大化:**
+
+Next.js環境において、`next-i18next`は素の状態と比較して**76.7 KB（gzip圧縮後）**増加します（約50%増）。一方、`next-intlayer`の増加幅はわずか1.3 KBです。
+
+**翻訳データの無駄な配信:**
+
+デフォルト設定では、対象ルートに配信されるテキストの約**90%**が他ページ用のデータです。名前空間の手動分割は維持コストが高く、人為的ミスの原因になりやすいのが実情です。
+
+**ハイドレーション速度の差:**
+
+`react-i18next`コンポーネントのハイドレーションに**85 ms**を要したのに対し、Intlayerは**24 ms**でした。巨大なJSON構造をクライアントコンポーネントへ渡す処理が、初期描画の応答性を低下させます。
+
+## なぜi18nextは重くなるのか？
+
+### ランタイム機能の積み重ね
+
+ブラウザ上ですべてを完結させようとするため、文字列の埋め込み処理、複数形判定ロジック、コンテキスト管理、フォーマッター、イベントバスなど、あらゆる機能を事前に読み込む必要があります。単純な文字列を1つ表示するだけでも、システム全体の負荷が発生します。
+
+### 動的キー参照によるTree-shakingの阻害
+
+`"hero.title"`のようなキーは実行時に評価されるため、バンドラー側でどのキーが実際に使用されているかを判別できません。その結果、未使用の翻訳文字列もそのままクライアントバンドルに残ります。
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+[Intlayerコンパイラ](https://intlayer.org/ja/doc/compiler)は`Hero.tsx`で参照されているフィールドを正確に特定し、未使用のデータをクライアントバンドルの生成前に除去します。詳細は[バンドル最適化](https://intlayer.org/ja/doc/concept/bundle-optimization)をご覧ください。
+
+## 開発体験（DX）の比較
+
+### 隔離されたJSONとコンポーネントの共配置
+
+i18nextでは、翻訳テキストがコードから離れたJSONディレクトリにまとめられます。Intlayerでは、コンテンツ定義をコンポーネントのすぐ隣に配置できます。
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/ja/hero.json"
+{
+  "title": "あらゆる言語でリリースしよう"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      ja: "あらゆる言語でリリースしよう",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+コンポーネント`Hero.tsx`を移動または削除すると、対応するコンテンツ定義も連動して移動または削除されます。
+
+### エディタ補完と厳格な型安全性の違い
+
+`CustomTypeOptions`を設定すればエディタ上で補完が効きますが、翻訳が全言語で揃っているかまでは保証されません。例えば`ja/hero.json`からキーを削除してもビルドエラーにはならず、実行時にフォールバックテキストが表示されるだけです。
+
+Intlayerは宣言されたコンテンツから型を自動生成し、[`strictMode`](https://intlayer.org/ja/doc/concept/configuration)を有効にすれば翻訳の欠落をビルドエラーとして即座に検出します。
+
+### 提供ツールの比較
+
+| 機能                      | i18nextエコシステム | Intlayer                                                                |
+| ------------------------- | ------------------- | ----------------------------------------------------------------------- |
+| **VS Code拡張機能**       | サードパーティのみ  | ✅ [公式拡張機能](https://intlayer.org/ja/doc/vs-code-extension)        |
+| **Language Server (LSP)** | ❌ なし             | ✅ [専用LSP搭載](https://intlayer.org/ja/doc/lsp)                       |
+| **AI向けMCPサーバー**     | ❌ なし             | ✅ [組み込みMCPサーバー](https://intlayer.org/ja/doc/mcp-server)        |
+| **AIエージェントスキル**  | ❌ なし             | ✅ [標準スキルセット](https://intlayer.org/ja/doc/agent_skills)         |
+| **ビジュアルCMS機能**     | Locize（有料SaaS）  | ✅ [無料かつオープンソース](https://intlayer.org/ja/doc/concept/editor) |
+
+## 翻訳ワークフローとLocizeの関係
+
+Locizeはi18nextの開発元が運営する有償サービスです。オープンソースを支援する資金源として機能している一方、有料の翻訳SaaS事業を展開している以上、CLI上で完結する無料のローカルAI翻訳ツールを積極的に提供する動機は生まれにくい構造にあります。
+
+Intlayerはオープンなエコシステムを重視しています。
+
+- [`intlayer fill`](https://intlayer.org/ja/doc/concept/auto-fill)を使用し、手持ちのOpenAI、Anthropic、Mistral、GeminiのAPIキーを使ってターミナルやCI上で不足している翻訳を自動補完できます。
+- [Intlayer CMS](https://intlayer.org/ja/doc/concept/cms)はオープンソースであり、Docker Compose等を用いてセルフホスト可能です。
+- コンパイラ、CLI、エディタ、CMSはすべてApache 2.0ライセンスで提供されています。
+
+## 現在もi18nextの採用が妥当なケース
+
+<AccordionGroup>
+<Accordion header="稼働中の安定したレガシー環境">
+
+既存システムが問題なく稼働しており、バンドルサイズが深刻な課題となっていない場合、あわてて移行する必要はありません。
+
+</Accordion>
+<Accordion header="特殊なプラットフォーム環境">
+
+豊富なプラグイン群により、Electronや旧世代のjQueryスタック、独自のネイティブブリッジなど、最新コンパイラが標準で対応していない環境にも適用できます。
+
+</Accordion>
+<Accordion header="蓄積されたノウハウ">
+
+StackOverflowやGitHub上に長年のトラブルシューティング事例が豊富に存在するため、特殊な問題の解決が容易です。
+
+</Accordion>
+</AccordionGroup>
+
+## 既存のi18next環境を改善するには？
+
+Intlayerは、i18next関連ライブラリ（`i18next`、`react-i18next`、`next-i18next`）の関数シグネチャをそのまま再現する互換パッケージを提供しています。コンポーネントを全面的に書き直すことなく、コンパイラ主導の最新アーキテクチャの恩恵を受けることができます。
+
+セットアップはコマンド1行で完了します。
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+この対話型CLIツールは以下の処理を自動で行います。
+
+1. `@intlayer/i18next`互換パッケージをインストールします。
+2. バンドラーのエイリアスを設定し、既存のインポート（`useTranslation`、`Trans`、`t`）をIntlayerに自動転送します。これにより、旧ライブラリを`package.json`から安全に削除できます。
+3. エディタ上での言語サーバー（LSP）診断、ビルド時のツリーシェイキング（バンドル最適化）、ローカルAI翻訳ワークフローを即座に有効化します。
+
+ステップごとの詳しい手順は専用のガイドをご確認ください。
+
+- **互換レイヤーの活用:** [i18next](https://intlayer.org/ja/doc/compatibility/i18next)、[react-i18next](https://intlayer.org/ja/doc/compatibility/react-i18next)、[next-i18next](https://intlayer.org/ja/doc/compatibility/next-i18next)の互換レイヤーを利用し、既存の記法を保ったままビルドプロセスを最新化します。
+- **カタログ移行ガイド:** JSON資産を型付き辞書へ移行するためのドキュメントを用意しています。[i18nextからの移行](https://intlayer.org/ja/doc/migration/i18next)、[react-i18nextからの移行](https://intlayer.org/ja/doc/migration/react-i18next)、[next-i18nextからの移行](https://intlayer.org/ja/doc/migration/next-i18next)。
+- **ハイブリッド構成:** ランタイムとしてi18nextを維持しながら、[Intlayerとi18nextを連携](https://intlayer.org/ja/blog/intlayer-with-i18next)させて型の強化やローカルAI翻訳を活用します。
+
+無料の[i18n SEOスキャナー](https://intlayer.org/i18n-seo-scanner)で、自社サイトのサイズと翻訳漏れをチェックできます。
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## 関連記事
+
+- [Next.js i18nベンチマーク: パフォーマンス徹底比較](https://intlayer.org/ja/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ja/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [2026年においてnext-intlは時代遅れなのか？](https://intlayer.org/ja/blog/is-next-intl-outdated)
+- [コンパイラ主導型i18nと宣言型アプローチの比較](https://intlayer.org/ja/blog/compiler-vs-declarative-i18n)