@intlayer/docs 9.5.6 → 9.5.7

package/blog/ja/vue-i18n_vs_intlayer_benchmark.md

@@ -0,0 +1,361 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: "vue-i18n vs Intlayer：2026年ベンチマーク"
+description: 同じ Vite + Vue 3 アプリで vue-i18n と Intlayer を計測。ライブラリサイズ、ページあたりの JavaScript、コンテンツの漏れ、コンポーネントサイズ、ロケール切り替えのリアクティビティを、数値の解説付きで紹介します。
+keywords:
+  - vue-i18n
+  - Intlayer
+  - Internationalization
+  - i18n
+  - Benchmark
+  - Bundle size
+  - Blog
+  - Vue
+  - Nuxt
+  - Vite
+  - JavaScript
+slugs:
+  - blog
+  - vue-i18n-vs-intlayer-benchmark
+author: aymericzip
+---
+
+# vue-i18n VS Intlayer | Vue 国際化 (i18n) ベンチマーク
+
+`vue-i18n` は Vue における i18n ライブラリの定番です。Intlayer はコンパイラベースでコンポーネント単位にスコープされた代替手段で、Vue 統合（`vue-intlayer`）を提供します。両者の[機能と開発者体験](https://intlayer.org/blog/vue-i18n-vs-intlayer)についてはすでに比較済みです。本記事では、アプリをビルドした後にそれぞれがどれだけのコストになるかを見ていきます。
+
+データは [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) から取得しています。これは各ライブラリで同じアプリケーションをビルドし、ブラウザが実際にダウンロードして実行する内容を記録するオープンソースのスイートです。
+
+<TOC/>
+
+> **tl;dr**：同じ Vite + Vue 3 アプリで、`vue-i18n` はページあたり **134.9 KB** の gzip 圧縮 JavaScript を配信するのに対し、i18n なしのアプリは **41.3 KB** です。Intlayer は **57.1 KB** を配信します。`vue-i18n` のランタイムだけで **24.3 KB gzip**（Intlayer の 3.9 KB の 6 倍）あり、すべてのページが**他ページの文字列の 90%** を抱え、単体でコンパイルしたコンポーネントはグローバルなメッセージツリーに束縛されているため **196 KB** を引き込みます。`@intlayer/vue-i18n` アダプターは `vue-i18n` の API を維持しつつ、ページあたり **47.0 KB** を計測しました。
+
+## 要約
+
+- **vue-i18n** - Vue 2 / Vue 3 における事実上の標準 i18n ライブラリで、`@nuxtjs/i18n` の中核。ICU スタイルのメッセージ、SFC の `<i18n>` ブロック、`v-t` ディレクティブ、`d()` / `n()` フォーマッター、大規模なエコシステム。メッセージは `createI18n()` でグローバルインスタンスに登録され、ロケールごとの遅延読み込みは手動の `setLocaleMessage()` パターンで、ルートごとの分割は自分で構築する必要があります。
+- **Intlayer** - コンポーネント中心のコンテンツモデル。`.content.ts` 辞書はそれを使うコンポーネントの隣に置かれ、ビルド時コンパイラ（`vite-intlayer`）がコンポーネント単位・ロケール単位でツリーシェイクと遅延読み込みを行い、コンテンツから厳密な TypeScript 型が生成され、翻訳の欠落はビルド時に失敗します。ルーター / SEO ヘルパー、ビジュアルエディター / CMS、AI 支援翻訳を同梱しています。
+
+| ライブラリ            | GitHub スター                                                                                                                                                                  | 総コミット数                                                                                                                                                                       | 最終コミット                                                                                                                                        | 初版       | NPM バージョン                                                                                              | NPM ダウンロード                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `aymericzip/intlayer` | [![GitHub Repo stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/aymericzip/intlayer/stargazers) | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits) | [![Last Commit](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits) | 2024年4月  | [![npm](https://img.shields.io/npm/v/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer) | [![npm downloads](https://img.shields.io/npm/dm/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer) |
+| `intlify/vue-i18n`    | [![GitHub Repo stars](https://img.shields.io/github/stars/intlify/vue-i18n?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/intlify/vue-i18n/stargazers)       | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/intlify/vue-i18n?style=for-the-badge&label=commits)](https://github.com/intlify/vue-i18n/commits)       | [![Last Commit](https://img.shields.io/github/last-commit/intlify/vue-i18n?style=for-the-badge)](https://github.com/intlify/vue-i18n/commits)       | 2016年12月 | [![npm](https://img.shields.io/npm/v/vue-i18n?style=for-the-badge)](https://www.npmjs.com/package/vue-i18n) | [![npm downloads](https://img.shields.io/npm/dm/vue-i18n?style=for-the-badge)](https://www.npmjs.com/package/vue-i18n) |
+
+> バッジは自動的に更新されます。スナップショットは時間とともに変化します。
+
+## 機能の比較一覧
+
+| 機能                                                 | `vue-intlayer` (Intlayer)                                 | `vue-i18n`                                                                |
+| ---------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
+| **コンポーネントの近くに翻訳を配置**                 | ✅ はい、`.content.ts` を各コンポーネントと同じ場所に配置 | ✅ SFC の `<i18n>` ブロック経由（任意）。グローバルカタログが一般的な構成 |
+| **TypeScript 統合**                                  | ✅ コンテンツから厳密な型を自動生成                       | ✅ 良好な型定義。厳密なキー安全性にはスキーマの型付けと規律が必要         |
+| **翻訳欠落の検出**                                   | ✅ TypeScript エラー + ビルド時のエラー/警告              | ⚠️ ランタイムのフォールバック + コンソール警告                            |
+| **リッチコンテンツ（コンポーネント / Markdown）**    | ✅ 直接サポート                                           | ⚠️ `<i18n-t>` コンポーネント補間。Markdown は外部プラグイン経由           |
+| **ICU サポート**                                     | ⚠️ 開発中                                                 | ✅ はい                                                                   |
+| **フォーマット（日付、数値、通貨）**                 | ✅ Intl ベースのフォーマッター                            | ✅ `datetimeFormats` / `numberFormats` を使った `d()` / `n()`             |
+| **ローカライズされたルーティング**                   | ✅ Vue Router / Nuxt 向けヘルパー、`getMultilingualUrls`  | ⚠️ コアではない（`@nuxtjs/i18n` またはカスタムルーター設定）              |
+| **SEO ヘルパー（hreflang、sitemap、robots）**        | ✅ 組み込みヘルパー                                       | ❌ コアではない                                                           |
+| **ツリーシェイキング（使用するコンテンツのみ配信）** | ✅ コンポーネント単位・ロケール単位で、コンパイラが自動化 | ⚠️ 手動：カタログを分割し、ルートごとに `setLocaleMessage()`              |
+| **遅延読み込み**                                     | ✅ `importMode: 'dynamic'`（設定 1 行）                   | ✅ 手動の `import()` + `setLocaleMessage()`                               |
+| **未使用コンテンツのパージ**                         | ✅ 未使用の辞書はビルド時に削除                           | ❌ 組み込みなし                                                           |
+| **翻訳欠落のテスト（CLI / CI）**                     | ✅ `npx intlayer content test`                            | ⚠️ サードパーティ（`vue-i18n-extract`）                                   |
+| **AI による翻訳**                                    | ✅ 組み込み、自身のプロバイダーキーを使用                 | ❌ なし                                                                   |
+| **ビジュアルエディター / CMS**                       | ✅ 無料のビジュアルエディター + オプションの CMS          | ❌ なし（外部のローカライゼーションプラットフォーム）                     |
+| **MCP サーバーと Agent Skills**                      | ✅ はい                                                   | ❌ なし                                                                   |
+| **エコシステム / コミュニティ**                      | ⚠️ 小規模だが急成長中                                     | ✅ Vue エコシステムで大規模かつ成熟                                       |
+
+## ベンチマーク
+
+### 計測内容
+
+[Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) スイートは、各ライブラリで**同じ Vite + Vue 3 アプリケーション**をビルドします：**10 ページ**（home、about、blog、careers、contact、FAQ、pricing、products、settings、team）、**10 ロケール**（`en`、`fr`、`es`、`de`、`it`、`pt`、`zh`、`ja`、`ko`、`ru`）、同一のコンポーネントと同一のコンテンツ。ページは `en` と `fr` で計測されます。
+
+両ライブラリとも、ほとんどの Vue プロジェクトが出荷している **static** 構成でテストされました：`vue-i18n` では各ロケールの JSON をインポートして `createI18n({ messages })` に渡し、Intlayer ではデフォルトの `importMode: 'static'` を使用。このモードでは Intlayer もすべてのロケールをバンドルしますが、コンパイラは依然としてコンテンツを**コンポーネント単位**でスコープするため、ページはレンダリングするコンポーネントの辞書だけを抱えます。
+
+各ビルドについて、スイートは以下を記録します：
+
+- **Lib size**：i18n ライブラリのみをインポートする空のコンポーネントの gzip サイズ。ランタイムの固定コスト。
+- **Page JS**：ページあたりにダウンロードされる gzip JavaScript。全ページ・全ロケールの平均。
+- **Locale leak %**：ダウンロードされた JS に含まれる翻訳文字列のうち、ユーザーが閲覧して**いない**ロケールに属するものの割合（`en` と `fr` でフィンガープリントするため、50% は「もう一方の計測ロケールが完全に含まれている」ことを意味し、10 ロケールをバンドルした場合の実際の無駄はそれより大きい）。
+- **Page leak %**：ダウンロードされた JS に含まれる翻訳文字列のうち、ユーザーが**いない**ページに属するものの割合。
+- **Component avg**：各コンポーネントを単体でコンパイルしたときの平均 gzip サイズ。1 つのコンポーネントがどれだけの i18n ランタイムとカタログを引き込むかを示します。
+- **E2E reactivity**：新しいロケールを選択してから DOM の `html[lang]` が更新されるまでの実時間（Playwright、5 回反復）。
+- **Page load**：`PerformanceNavigationTiming.duration`。
+
+> 以下の数値は、`vue-i18n` 11.4.0 と `intlayer` 9.5.0 / 9.5.1 を使用した **2026-09-12** の実行結果です。テストアプリケーションは意図的に小さく作られている（ロケールあたり数十の文字列）ため、漏れの割合は**パターン**を示すものです：コンテンツが増えるほど割合は大きくなり、一方でランタイムコストは固定のままです。
+
+### Vite + Vue 3 での結果
+
+| ライブラリ                    | 戦略   | Lib size (gz) | Lib size (min) | Page JS 平均 (gz) | Locale leak | Page leak | Component 平均 (gz) | E2E リアクティビティ | Page load |
+| ----------------------------- | ------ | ------------: | -------------: | ----------------: | ----------: | --------: | ------------------: | -------------------: | --------: |
+| **base**（i18n なし）         | -      |        0.0 KB |         0.0 KB |           41.3 KB |        0.0% |         - |              1.1 KB |               1.8 ms |   10.8 ms |
+| `vue-i18n`                    | static |       24.3 KB |        83.2 KB |          134.9 KB |       50.0% |     90.0% |            196.0 KB |               2.8 ms |   13.6 ms |
+| **`vue-intlayer`**            | static |    **3.9 KB** |    **11.1 KB** |       **57.1 KB** |       56.8% |  **0.0%** |          **7.7 KB** |           **4.5 ms** |   13.8 ms |
+| `@intlayer/vue-i18n` (compat) | static |        7.9 KB |        23.2 KB |           47.0 KB |       15.0% |      0.0% |              8.4 KB |               1.5 ms |    9.3 ms |
+
+> ベースアプリの page-leak 列は空欄です：i18n ライブラリがない場合、フィンガープリントは共有チャンク内のハードコードされた文字列を拾ってしまい、数値に意味がありません。
+
+**読み方**
+
+- **ランタイムコスト。** `vue-i18n` はベンチマーク全体で最も重いランタイムの 1 つです：それをインポートするだけの空コンポーネントで **24.3 KB gzip / 83.2 KB minified**。`vue-intlayer` は 3.9 KB gzip です。この差は、文字列がいくつあろうと、すべてのページで支払うことになります。
+- **ページあたりの JavaScript。** i18n なしのアプリは 41.3 KB です。`vue-i18n` はそれを 3 倍以上の **134.9 KB** にします。Intlayer は **57.1 KB**、+15.8 KB で、そのほとんどはバンドルされた 10 ロケール分です（次の項目を参照）。
+- **漏れ。** `createI18n({ messages: { en, fr, ... } })` では、すべてのページがすべてのロケールとすべてのページの文字列を配信します：**50% のロケール漏れ**（フィンガープリントした 2 ロケールで）と **90% のページ漏れ**。Intlayer の `static` モードもすべてのロケールをバンドルします（そのためロケール漏れの数値は同程度）が、**ページ漏れは 0%** です：ページはレンダリングするコンポーネントの辞書だけを取り込みます。`importMode: 'dynamic'` に切り替えるとロケール漏れも解消されますが、その構成は今回の Vue 実行には含まれていません。
+- **コンポーネントサイズにアーキテクチャの差が現れます。** `useI18n()` を呼ぶコンポーネントは平均で **196 KB** にコンパイルされます。`t()` が全ロケールの全メッセージを保持するグローバルインスタンスに束縛されているからです。同じコンポーネントを `useIntlayer()` にすると **7.7 KB** にコンパイルされます：自身の辞書にしか届きません。
+- **リアクティビティ**は両者とも問題になりません（2〜5 ms）。メッセージがメモリに載ってしまえば、Vue のリアクティビティシステムによりロケール切り替えは安価です。
+- **`@intlayer/vue-i18n`**、ドロップインアダプターは `vue-i18n` の API を維持し、アプリケーションコードに手を加えずに**ページあたり 47.0 KB**、**コンポーネントあたり 8.4 KB** を計測しました。
+
+> 参考までに、同じ実行で `fluent-vue` はページあたり 171.8 KB、ランタイム 29.7 KB、コンポーネントあたり 217 KB を計測しました。
+
+## なぜ差が出るのか？グローバルインスタンス vs コンパイル済み辞書
+
+`vue-i18n` はランタイムです。`createI18n()` がロケールごとのメッセージツリーを保持するグローバルインスタンスを構築し、`useI18n()` が各コンポーネントをそれに束縛し、`t("footer.github")` がレンダリング時にキーを検索します。これが SFC の `<i18n>` ブロック、`v-t`、ランタイムでのメッセージ読み込みを可能にしている一方で、すべてのコンポーネントの依存グラフにツリー全体が含まれる理由でもあります：
+
+```bash
+.
+├── locales
+│   ├── en.json
+│   ├── fr.json
+│   └── ...                        # ロケールごとに 1 ファイル、全ページを含む
+└── src
+    ├── i18n.ts                    # createI18n({ messages: { en, fr, ... } })
+    ├── main.ts
+    └── components
+        └── Footer.vue             # const { t } = useI18n(); t("footer.github")
+```
+
+最適化するということは、**あなたが** `en.json` をルートごとのファイルに分割し、**あなたが**ルーターガードで `setLocaleMessage()` を呼び、**あなたが**コンポーネントの移動に合わせてルートとファイルの対応を正しく保つということです。ランタイムはコンポーネントがどのキーを要求するか知らないため、代わりにやってくれることはありません。
+
+Intlayer はその知識をビルドに移します。コンテンツはコンポーネントの隣で宣言され、`vite-intlayer` がどのコンポーネントがどの辞書をインポートするかを解決します：
+
+```bash
+.
+├── intlayer.config.ts
+└── src
+    ├── main.ts                    # createApp(App).use(intlayer)
+    └── components
+        └── Footer
+            ├── Footer.vue         # useIntlayer("footer")
+            └── Footer.content.ts
+```
+
+コンパイラは辞書ごと・ロケールごとに、そのコンポーネントが必要とする JSON だけを正確に出力し、どこからもインポートされない辞書は削除します。ルート単位のスコープはコンポーネント単位のスコープの帰結であって、作業ではありません。
+
+> 未使用のロケールも削除するには、`intlayer.config.ts` で `dictionary.importMode: 'dynamic'` を設定してください。[バンドル最適化のドキュメント](https://intlayer.org/doc/concept/bundle-optimization)を参照してください。
+
+## 開発者体験
+
+### セットアップ
+
+**vue-i18n**
+
+```ts fileName="src/i18n.ts"
+import { createI18n } from "vue-i18n";
+import en from "../locales/en.json";
+import fr from "../locales/fr.json";
+
+export const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+  messages: { en, fr },
+});
+```
+
+```ts fileName="src/main.ts"
+import { createApp } from "vue";
+import App from "./App.vue";
+import router from "./router";
+import { i18n } from "./i18n";
+
+createApp(App).use(router).use(i18n).mount("#app");
+```
+
+**Intlayer**
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer(), vue()],
+});
+```
+
+```ts fileName="src/main.ts"
+import { createApp } from "vue";
+import { intlayer } from "vue-intlayer";
+import App from "./App.vue";
+import router from "./router";
+
+createApp(App).use(intlayer).use(router).mount("#app");
+```
+
+### コンポーネント
+
+**vue-i18n**
+
+```json fileName="locales/en.json"
+{
+  "counter": {
+    "label": "Counter",
+    "increment": "Increment"
+  }
+}
+```
+
+```vue fileName="src/components/Counter.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { useI18n } from "vue-i18n";
+
+const { t, n } = useI18n();
+const count = ref(0);
+</script>
+
+<template>
+  <div>
+    <p>{{ n(count) }}</p>
+    <button :aria-label="t('counter.label')" @click="count++">
+      {{ t("counter.increment") }}
+    </button>
+  </div>
+</template>
+```
+
+`t('counter.label')` は、メッセージスキーマを自分で型付けするまでは単なる文字列です。タイポするとキーがそのまま表示されます。
+
+**Intlayer**
+
+```ts fileName="src/components/Counter/Counter.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const counterContent = {
+  key: "counter",
+  content: {
+    label: t({ en: "Counter", fr: "Compteur" }),
+    increment: t({ en: "Increment", fr: "Incrémenter" }),
+  },
+} satisfies Dictionary;
+
+export default counterContent;
+```
+
+```vue fileName="src/components/Counter/Counter.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { useIntlayer } from "vue-intlayer";
+import { useNumber } from "vue-intlayer/format";
+
+const { label, increment } = useIntlayer("counter");
+const number = useNumber();
+const count = ref(0);
+</script>
+
+<template>
+  <div>
+    <p>{{ number.value(count) }}</p>
+    <button :aria-label="label" @click="count++">
+      {{ increment }}
+    </button>
+  </div>
+</template>
+```
+
+`label` と `increment` は型付けされています。タイポは TypeScript エラーになり、フランス語の値の欠落はビルドエラーになります。
+
+### ロケールごとの遅延読み込み
+
+**vue-i18n**
+
+```ts fileName="src/i18n.ts"
+import { nextTick } from "vue";
+import { createI18n } from "vue-i18n";
+
+export const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+});
+
+export const loadLocaleMessages = async (locale: string) => {
+  const messages = await import(`../locales/${locale}.json`);
+  i18n.global.setLocaleMessage(locale, messages.default);
+  await nextTick();
+  i18n.global.locale.value = locale;
+};
+```
+
+その後、ルーターガードから `loadLocaleMessages()` を呼び、ページ単位のスコープが欲しければ `locales/{locale}.json` をルートごとに自分で分割します。
+
+**Intlayer**
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  // ...
+  dictionary: {
+    importMode: "dynamic",
+  },
+};
+```
+
+## vue-i18n の API を維持したまま、Intlayer の出力を得る
+
+`@intlayer/vue-i18n` はドロップインアダプターです：`useI18n()`、`t()`、`d()`、`n()`、`{name}` と `{0}` の補間、パイプ複数形（`"car | cars"`）、`v-t`、`i18n.global.locale` はそのまま動作し、`vite-intlayer` がコンパイルした Intlayer 辞書から提供されます。
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+ベンチマークでは、同じアプリの compat ビルドはコンポーネントに手を加えずに、ページあたり **134.9 KB から 47.0 KB** に、コンポーネントあたり **196 KB から 8.4 KB** になりました。既存の `locales/{locale}.json` は JSON 同期プラグインを通じて引き続き信頼できる情報源として使えます。
+
+[vue-i18n 移行ガイド](https://intlayer.org/doc/migration/vue-i18n)と[互換性ドキュメント](https://intlayer.org/doc/compatibility/vue-i18n)を参照してください。Nuxt ユーザーは [`@nuxtjs/i18n` 互換性](https://intlayer.org/doc/compatibility/nuxtjs-i18n)を通じて同じ道をたどれます。
+
+## どちらを選ぶべきか？
+
+- **vue-i18n を選ぶ**：標準的な Vue のアプローチが欲しい、ICU メッセージや SFC の `<i18n>` ブロックに依存している、すでに `@nuxtjs/i18n` を使っている、または翻訳プラットフォームが集中管理された JSON を要求する場合。バンドルサイズが重要なら、カタログの分割とルートごとの遅延読み込みに時間を確保してください。
+- **Intlayer を選ぶ**：**コンポーネントスコープのコンテンツ**、**厳密な TypeScript**、**ビルド時のキー欠落エラー**、**手間いらずのツリーシェイキングと遅延読み込み**、組み込みの編集ツール（ビジュアルエディター、CMS、AI 翻訳、MCP サーバー）が欲しい場合。大規模でモジュール化された Vue / Nuxt コードベースやデザインシステムに特に適しています。
+- **`@intlayer/vue-i18n` を選ぶ**：すでに `vue-i18n` を使っていて、書き直しなしでバンドルの削減効果を得たい場合。
+
+## 関連する比較
+
+- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)（同じベンチマーク）
+- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer)（同じベンチマーク）
+- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer)（同じベンチマーク）
+- [vue-i18n vs Intlayer（機能と DX）](https://intlayer.org/blog/vue-i18n-vs-intlayer)
+- [vue-i18n は時代遅れ？](https://intlayer.org/blog/is-vue-i18n-outdated)
+
+## GitHub スター
+
+GitHub スターはプロジェクトの人気、コミュニティの信頼、長期的な妥当性を示す強い指標です。技術的品質を直接測るものではありませんが、どれだけの開発者がそのプロジェクトを有用だと感じ、進捗を追い、採用する可能性があるかを反映しています。
+
+[![Star History Chart](https://api.star-history.com/chart?repos=intlify%2Fvue-i18n%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+
+## 結論
+
+`vue-i18n` は成熟していて柔軟で、Vue と深く統合されています。ベンチマークは、そのランタイムファーストの設計が Vite ビルドで何を犠牲にするかを示しています：**24 KB gzip のランタイム**、i18n なしなら 41 KB のアプリで**ページあたり 134.9 KB**、すべてのページに **90% の他ページコンテンツ**、そしてグローバルなメッセージツリーにぶら下がっているためにそれぞれ **196 KB** に達するコンポーネント。
+
+Intlayer はその作業をコンパイラに移します。コンポーネント単位の辞書と未使用コンテンツのパージはビルド出力であって、慣習ではありません。同じアプリで：**3.9 KB のランタイム**、**ページあたり 57.1 KB**、**ページ漏れ 0%**、コンポーネントは **25 分の 1**。そして書き直しが選択肢にない場合でも、`@intlayer/vue-i18n` はコンポーネントに手を加えずにその大部分を実現します。
+
+生データ、テストアプリ、スクリプトはすべて [Benchmark Bloom リポジトリ](https://github.com/intlayer-org/benchmark-bloom)にあります。ぜひご自身で実行してみてください。
+
+詳細は [「なぜ Intlayer？」ドキュメント](https://intlayer.org/doc/why)を参照してください。

package/blog/ko/i18next_vs_intlayer-i18next.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs @intlayer/i18next: 동일한 API, 완전히 다른 번들 크기"
 description: React 또는 Next.js 앱이 기존의 i18next, react-i18next, next-i18next 호출을 그대로 유지하면서 @intlayer/i18next 어댑터를 통해 제공될 때 무엇이 달라지는지 알아봅니다. 동일한 코드에서 측정한 페이지별 JavaScript 용량, 컴포넌트 크기, 문자열 누수 및 하이드레이션 성능과 어댑터의 지원 범위를 상세히 분석합니다.
 keywords:
@@ -28,6 +28,8 @@ author: aymericzip
 
 # i18next VS @intlayer/i18next | 동일한 API, 완전히 다른 번들 크기
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/i18next`, `@intlayer/react-i18next`, `@intlayer/next-i18next`는 호환성 어댑터입니다. 기존 코드에서 이미 사용 중인 `i18next` API(`useTranslation`, `t()`, `<Trans>`, `i18n.changeLanguage()`, `getFixedT`, `serverSideTranslations` 등)를 그대로 노출하면서, Intlayer가 컴파일한 딕셔너리로부터 번역 데이터를 공급합니다. 컴포넌트는 단 한 줄도 바꿀 필요가 없으며, 그 밑에서 동작하는 런타임만 교체됩니다.
 
 이 글은 동일한 Next.js 애플리케이션을 `next-i18next`와 `@intlayer/next-i18next`로 각각 빌드하여 측정한 결과를 다룹니다. 측정 수치는 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)에서 추출되었습니다. 라이브러리 자체의 기능 비교는 [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-vs-intlayer)를 참고하세요. 본 글은 기존 코드를 그대로 유지할 때 어댑터가 무엇을 바꾸어 놓는지를 집중 조명합니다.
@@ -109,6 +111,10 @@ const About = () => {
 
 ### Next.js 벤치마크 결과
 
+관심 있는 메트릭과 라이브러리를 선택하세요:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 설정                         | 전략           | Lib 크기 (gz) | 페이지 JS 평균 (gz) | 로케일 누수 | 페이지 누수 | 컴포넌트 평균 (gz) | E2E 반응속도 | 하이드레이션 |
 | ---------------------------- | -------------- | ------------: | ------------------: | ----------: | ----------: | -----------------: | -----------: | -----------: |
 | **base** (i18n 미사용)       | -              |        0.0 KB |            141.0 KB |        0.0% |        0.0% |             0.9 KB |      13.4 ms |      11.8 ms |
@@ -129,10 +135,21 @@ const About = () => {
 - **하이드레이션 및 로케일 전환 속도 개선.** 하이드레이션 시간은 15.6 ms에서 **11.3 ms**로 단축됩니다(백엔드 조회가 렌더링 경로를 막는 `dynamic`의 27.7 ms와 비교하면 큰 폭의 차이). 로케일 전환도 15~16 ms에서 **11~12 ms**로 빨라집니다.
 - **어댑터와 네이티브 런타임의 차이.** `next-intlayer`는 기본 앱 대비 단 +0.3 KB 늘어난 **141.3 KB**를 기록합니다. 어댑터는 Intlayer 코어 위에 `i18next` API 규격(보간 문법, 복수형/컨텍스트 해석, `<Trans>` 태그 파싱)을 탑재하므로 네이티브 대비 +9.4 KB를 가집니다. 어댑터는 완벽한 이전을 위한 다리이지 최종 종착지가 아닙니다.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 모든 라이브러리와 전략이 포함된 전체 표는 [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs)에서 확인하세요.
+
 > Vite / TanStack Start 환경에서의 `react-i18next` 어댑터는 이번 벤치마크에 포함되지 않았습니다. TanStack Start 기준 수치는 [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-vs-intlayer)에서 확인할 수 있습니다.
 
 ## 수치가 개선되는 이유
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 `components/` 디렉터리의 소스 코드는 전혀 바뀌지 않았습니다. 모든 차이는 `useTranslation`이 무엇에 바인딩되는지에서 기인합니다.
 
 **`i18next`의 경우**, 바인딩 대상은 전역 인스턴스입니다. 인스턴스에 로드된 모든 데이터(`static`의 모든 로케일, `dynamic`의 해당 언어 전체 네임스페이스)는 `useTranslation()`을 호출하는 모든 컴포넌트에서 접근 가능합니다. 번들러는 인스턴스가 쥐고 있는 단위 이하로 코드를 쪼갤 수 없으며, 런타임 역시 렌더링 시점에 어떤 키가 호출될지 알 수 없습니다.
@@ -149,6 +166,10 @@ const About = () => {
     └── About.tsx                     # useTranslation(); t("about.title")
 ```
 
+인스턴스가 보유한 모든 것이 모든 페이지로 전송되며, 낭비는 페이지와 로케일이라는 두 축에서 증가합니다:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 **`@intlayer/next-i18next`의 경우**, 바인딩 대상은 딕셔너리 그 자체입니다. `syncJSON`이 각 네임스페이스 파일을 딕셔너리로 변환하고, 최적화 단계가 컴포넌트에 해당 딕셔너리만을 직결 임포트로 넘겨주므로, 번들러가 페이지별, 로케일별로 안전하게 코드를 분할할 수 있습니다.
 
 ```bash
@@ -297,26 +318,112 @@ export default defineConfig({
 
 ## 시작 전 알아두어야 할 한계
 
-- **백엔드 및 감지기 비활성화.** `i18n.use(HttpBackend)`는 플러그인의 `init`만 호출하고 종료됩니다. 클라이언트 요청 시점에 CMS로부터 번역을 실시간으로 가져오던 방식은 중단되므로, Intlayer CMS 또는 `intlayer pull` / `push` 명령을 사용해야 합니다.
-- **`resources`는 병합되지 않고 무시됨.** 일부 어댑터와 달리, `@intlayer/i18next`는 인라인 `resources`를 폴백으로 사용하지 않습니다. 모든 키는 동기화된 딕셔너리에 실질적으로 존재해야 하며, 이는 `intlayer test`로 검증할 수 있습니다.
-- **App Router는 Provider 파일 수정 필요.** 위에서 설명한 1개 파일 수정이 요구됩니다. Pages Router에서 `appWithTranslation`을 사용 중인 경우는 추가 작업이 없습니다.
-- **`next-i18next.config.js` 무시.** `localePath`, `fallbackLng`, `reloadOnPrerender` 등의 옵션은 적용되지 않으며, 로케일과 폴백 규칙은 `intlayer.config.ts`에 정의해야 합니다.
-- **어댑터 자체의 런타임 비용.** 네이티브 `next-intlayer`에 비해 9.4 KB의 런타임과 페이지당 +9.4 KB가 추가됩니다. 모든 컴포넌트가 `useIntlayer`로 전환되면 어댑터를 제거하는 것이 좋습니다.
+<AccordionGroup>
+<Accordion header="백엔드 및 감지기는 비활성 상태임">
+
+`i18n.use(HttpBackend)`는 플러그인의 init만 호출할 뿐 다른 작업은 수행하지 않습니다. 앱이 런타임에 CMS에서 번역을 가져오는 데 의존했다면 해당 흐름은 사라집니다. 대신 [Intlayer CMS](https://intlayer.org/ko/doc/concept/cms) 또는 `intlayer pull` / `push` 명령을 사용하세요. 언어 감지는 Intlayer의 라우팅 설정(URL 접두사, 쿠키, 헤더)으로 대체됩니다.
+
+</Accordion>
+<Accordion header="resources는 병합되지 않고 무시됨">
+
+다른 어댑터와 달리 `@intlayer/i18next`는 인라인 `resources`를 폴백으로 사용하지 않습니다. 모든 키는 동기화된 사전에 존재해야 하며, 이는 `intlayer test`를 통해 검증됩니다.
+
+</Accordion>
+<Accordion header="App Router는 공급자 수정이 필요함">
+
+위에 표시된 단 하나의 파일만 수정하면 됩니다. `appWithTranslation`을 사용하는 Pages Router는 아무런 수정도 필요하지 않습니다.
+
+</Accordion>
+<Accordion header="next-i18next.config.js는 읽히지 않음">
+
+`localePath`, `fallbackLng`, `reloadOnPrerender` 등은 해당 사항이 없습니다. 로케일 및 폴백은 `intlayer.config.ts`에서 가져옵니다.
+
+</Accordion>
+<Accordion header="어댑터가 완전히 무료는 아님">
+
+`next-intlayer`에 비해 9.4 KB의 런타임 및 페이지당 +9.4 KB의 오버헤드가 발생합니다. 모든 컴포넌트가 `useIntlayer`로 전환되면 어댑터를 제거하세요.
+
+</Accordion>
+</AccordionGroup>
 
 ## 어떤 선택을 해야 할까?
 
-- **`i18next` 유지**: 요청 시점에 외부 CMS에서 번역을 실시간 수신해야 하거나, 독점적인 플러그인 생태계에 의존하거나, 어댑터가 커버하지 않는 비-React 환경인 경우.
-- **`@intlayer/*` 도입**: 기존 `react-i18next` / `next-i18next` 프로젝트에서 코드 재작성 없이 68 KB 절감, 8배 작아진 컴포넌트, 누수 0%, 타입 추론, CI 검증을 즉각 확보하고자 하는 경우.
-- **네이티브(`next-intlayer` / `react-intlayer`) 선택**: 신규 프로젝트이거나 어댑터 전환을 마친 후 최상의 성능을 원할 때. 가장 가벼운 구성(5.5 KB, 페이지당 +0.3 KB)으로 동기 서버 컴포넌트와 컴포넌트별 `.content.ts`를 지원합니다.
+<AccordionGroup>
+<Accordion header="i18next 유지">
+
+애플리케이션이 런타임 백엔드(요청 시 CMS에서 제공하는 번역), 플러그인 생태계 또는 어댑터가 지원하지 않는 비 React 환경에 의존하는 경우.
+
+</Accordion>
+<Accordion header="@intlayer/* 사용">
+
+`react-i18next` / `next-i18next`를 사용 중이며 코드 재작성 없이 68 KB 절감, 8배 더 작은 컴포넌트, 0% 누수, 타입 정의된 키 및 CI 검사를 원하는 경우. 기존 `i18next` 코드베이스의 진입점입니다.
+
+</Accordion>
+<Accordion header="네이티브로 전환 (next-intlayer / react-intlayer)">
+
+새 프로젝트이거나 어댑터가 역할을 다한 경우 적합합니다. 가장 가벼운 런타임(5.5 KB, 페이지당 +0.3 KB)을 제공하며 동기식 Server Components 및 컴포넌트별 `.content.ts` 파일을 지원합니다. [Next.js와 함께 사용하는 Intlayer](https://intlayer.org/ko/doc/environment/nextjs) 또는 [Vite 및 React와 함께](https://intlayer.org/ko/doc/environment/vite-and-react) 시작하세요.
+
+</Accordion>
+</AccordionGroup>
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="68 KB의 절감 효과는 어디서 나오나요?">
+
+`resources: { en, fr, ... }`에서 나옵니다. 기본적인 `next-i18next` 설정은 각 로케일의 JSON을 `init()`으로 가져오므로 모든 페이지가 모든 언어의 모든 네임스페이스를 끌어옵니다(페이지당 **218.5 KB**). 어댑터는 해당 블록을 번들로 묶지 않으며, 각 컴포넌트가 활성 로케일에서 지정한 사전만 전달합니다.
+
+</Question>
+
+<Question title="<Trans> 컴포넌트가 계속 작동하나요?">
+
+네, `components`, 번호가 지정된 `<1>...</1>` 태그 및 `values`를 지원합니다. `{{interpolation}}`, `$t(key)` 중첩, `key_one` / `key_other` 복수형(`Intl.PluralRules`로 평가됨), 컨텍스트 접미사 및 `returnObjects`도 지원됩니다.
+
+</Question>
+
+<Question title="로케일당 단일 translation.json을 사용하는 경우는 어떻게 되나요?">
+
+`syncJSON` 플러그인에서 `splitKeys: false`로 설정하세요. 전체 파일이 하나의 사전으로 유지되며 기본 `useTranslation()` 호출이 이에 대해 계속 확인됩니다.
+
+</Question>
+
+<Question title="이것이 Intlayer로 완전히 마이그레이션하는 것과 같나요?">
+
+아닙니다. 이것은 가교 역할을 합니다. 어댑터는 `i18next` API를 유지하며 9.4 KB의 런타임 비용이 듭니다. 네이티브 `next-intlayer`는 5.5 KB의 비용이 들며 동기식 Server Components와 동일 위치의 `.content.ts` 파일을 추가합니다. JSON과 `.content.ts` 사전이 공존하므로 컴포넌트별로 점진적 전환이 가능합니다.
+
+</Question>
+
+<Question title="번역가가 현재 작업 방식을 유지할 수 있나요?">
+
+네. `locales/{lng}/{ns}.json`이 단일 진실 공급원으로 유지됩니다. `syncJSON`이 i18next 문법으로 이를 읽고 CLI 또는 CMS가 업데이트할 때 번역을 다시 기록합니다.
+
+</Question>
+
+</FAQ>
 
 ## 관련 비교 자료
 
-- [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-vs-intlayer) (라이브러리 단독 비교, 동일 벤치마크)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/ko/blog/next-intl-vs-intlayer-next-intl) (어댑터 시리즈)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/ko/blog/lingui-vs-intlayer-lingui) (어댑터 시리즈)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-vue-i18n) (어댑터 시리즈)
-- 마이그레이션 가이드: [i18next](https://intlayer.org/ko/doc/migration/i18next), [react-i18next](https://intlayer.org/ko/doc/migration/react-i18next), [next-i18next](https://intlayer.org/ko/doc/migration/next-i18next)
-- 어댑터 규격 문서: [i18next](https://intlayer.org/ko/doc/compatibility/i18next), [react-i18next](https://intlayer.org/ko/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/ko/doc/compatibility/next-i18next)
+동일한 어댑터 시리즈:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/ko/blog/next-intl-vs-intlayer-next-intl)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ko/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+직접 비교된 라이브러리:
+
+- [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ko/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ko/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Is i18next outdated?](https://intlayer.org/ko/blog/is-i18next-outdated)
+
+참조 문서:
+
+- Compat adapters: [i18next](https://intlayer.org/ko/doc/compatibility/i18next), [react-i18next](https://intlayer.org/ko/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/ko/doc/compatibility/next-i18next)
+- Migration guides: [i18next](https://intlayer.org/ko/doc/migration/i18next), [react-i18next](https://intlayer.org/ko/doc/migration/react-i18next), [next-i18next](https://intlayer.org/ko/doc/migration/next-i18next)
+- [Next.js benchmark report](https://intlayer.org/ko/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/ko/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/ko/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/ko/doc/compiler)
+- [Visual Editor](https://intlayer.org/ko/doc/concept/editor), [CMS](https://intlayer.org/ko/doc/concept/cms) and [AI translation](https://intlayer.org/ko/doc/concept/auto-fill)
 
 ## 결론