@intlayer/docs 8.6.10 → 8.7.0-canary.1

package/docs/zh/bundle_optimization.md

@@ -0,0 +1,454 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2026-04-08
+title: 优化 i18n 构建包大小与性能
+description: 通过优化国际化 (i18n) 内容来减小应用程序构建包的大小。学习如何利用 Intlayer 对字典进行 Tree Shaking 和延迟加载。
+keywords:
+  - 构建包优化
+  - 内容自动化
+  - 动态内容
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 8.7.0
+    date: 2026-04-08
+    changes: "在构建配置中增加了 `minify` 和 `purge` 选项"
+---
+
+# 优化 i18n 构建包大小与性能
+
+依赖 JSON 文件的传统 i18n 解决方案面临的最常见挑战之一是管理内容大小。如果开发人员不手动将内容分离到命名空间中，用户往往为了查看单个页面而下载每个页面甚至每种语言的翻译。
+
+例如，一个包含 10 个页面并翻译成 10 种语言的应用程序，可能会导致用户下载 100 个页面的内容，即使他们只需要**一页**（当前语言的当前页面）。这会导致带宽浪费和加载速度变慢。
+
+**Intlayer 通过构建时优化解决了这个问题。** 它分析您的代码以检测每个组件实际使用的字典，并仅将必要的内容重新注入到您的构建包中。
+
+## 目录
+
+<TOC />
+
+## 扫描您的构建包
+
+分析构建包是识别“重型”JSON 文件和代码分割机会的第一步。这些工具可以生成应用程序编译后代码的可视化树图 (treemap)，让您确切地看到哪些库占用了最多的空间。
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite 底层使用 Rollup。`rollup-plugin-visualizer` 插件生成一个交互式 HTML 文件，显示图中每个模块的大小。
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // 在浏览器中自动打开报告
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+对于使用 App Router 和 Turbopack 的项目，Next.js 提供了一个内置的实验性分析器，不需要额外的依赖。
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+如果您在 Next.js 中使用默认的 Webpack 打包器，请使用官方的构建包分析器。通过在构建期间设置环境变量来触发它。
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // 您的 Next.js 配置
+});
+```
+
+**用法：**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### 标准 Webpack
+
+对于 Create React App (ejected)、Angular 或自定义 Webpack 设置，请使用行业标准的 `webpack-bundle-analyzer`。
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>
+
+## 工作原理
+
+Intlayer 使用**按组件优化**的方法。与全局 JSON 文件不同，您的内容定义在组件旁边或内部。在构建过程中，Intlayer 会：
+
+1.  **分析**您的代码以查找 `useIntlayer` 调用。
+2.  **构建**相应的字典内容。
+3.  根据您的配置用优化后的代码**替换** `useIntlayer` 调用。
+
+这确保了：
+
+- 如果一个组件没有被引入，它的内容就不会包含在构建包中（Dead Code Elimination）。
+- 如果一个组件是延迟加载的，它的内容也会被延迟加载。
+
+## 按平台设置
+
+<Tabs>
+ <Tab value="nextjs">
+
+### Next.js
+
+Next.js 需要 `@intlayer/swc` 插件来处理转换，因为 Next.js 使用 SWC 进行构建。
+
+> 该插件默认不安装，因为 SWC 插件对 Next.js 仍处于实验阶段。未来可能会发生变化。
+
+```bash packageManager="npm"
+npm install -D @intlayer/swc
+```
+
+```bash packageManager="yarn"
+yarn add -D @intlayer/swc
+```
+
+```bash packageManager="pnpm"
+pnpm add -D @intlayer/swc
+```
+
+```bash packageManager="bun"
+bun add -d @intlayer/swc
+```
+
+安装后，Intlayer 将自动检测并使用该插件。
+
+ </Tab>
+ <Tab value="vite">
+
+### Vite
+
+Vite 使用 `@intlayer/babel` 插件，该插件作为 `vite-intlayer` 的依赖项包含在内。优化默认启用。无需额外操作。
+
+ </Tab>
+ <Tab value="webpack">
+
+### Webpack
+
+要在 Webpack 上启用 Intlayer 构建包优化，您需要安装并配置相应的 Babel (`@intlayer/babel`) 或 SWC (`@intlayer/swc`) 插件。
+
+```bash packageManager="npm"
+npm install -D @intlayer/babel
+```
+
+```bash packageManager="yarn"
+yarn add -D @intlayer/babel
+```
+
+```bash packageManager="pnpm"
+pnpm add -D @intlayer/babel
+```
+
+```bash packageManager="bun"
+bun add -d @intlayer/babel
+```
+
+```typescript fileName="babel.config.js"
+const {
+  getOptimizePluginOptions,
+  intlayerOptimizeBabelPlugin,
+} = require("@intlayer/babel");
+
+module.exports = {
+  plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],
+};
+```
+
+ </Tab>
+</Tabs>
+
+## 配置
+
+您可以通过 `intlayer.config.ts` 中的 `build` 属性来控制 Intlayer 如何优化您的构建包。
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * 压缩字典以减小构建包大小。
+     */
+     minify: true;
+
+    /**
+     * 清除字典中未使用的键
+     */
+     purge: true;
+
+    /**
+     * 指示构建是否应检查 TypeScript 类型
+     */
+    checkTypes: false;
+  },
+};
+
+export default config;
+```
+
+> 在绝大多数情况下，建议保持 `optimize` 的默认选项。
+
+> 有关更多详情，请参见配置文档：[配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+
+### 构建选项
+
+`build` 配置对象下提供以下选项：
+
+| 属性           | 类型      | 默认值      | 描述                                                                                                                                    |
+| :------------- | :-------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`** | `boolean` | `undefined` | 控制是否启用构建优化。如果为 `true`，Intlayer 使用优化后的注入替换字典调用。如果为 `false`，则禁用优化。建议在生产环境中设置为 `true`。 |
+| **`minify`**   | `boolean` | `false`     | 是否压缩字典以减小构建包大小。                                                                                                          |
+| **`purge`**    | `boolean` | `false`     | 是否清除字典中未使用的键。                                                                                                              |
+
+### 压缩 (Minification)
+
+压缩字典可以删除不必要的空格、注释，并减小 JSON 内容的大小。这对于大型字典尤其有用。
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    minify: true,
+  },
+};
+
+export default config;
+```
+
+> 注意：如果禁用 `optimize` 或启用了可视化编辑器（因为编辑器需要完整内容以便编辑），则会忽略压缩。
+
+### 清除 (Purging)
+
+清除确保只有代码中实际使用的键才会包含在最终的字典构建包中。如果您的大型字典包含许多并非在应用程序每个部分都使用的键，这可以显著减小构建包的大小。
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true,
+  },
+};
+
+export default config;
+```
+
+> 注意：如果禁用 `optimize`，则会忽略清除。
+
+### 导入模式 (Import Mode)
+
+对于包含多个页面和语言的大型应用程序，您的 JSON 文件可能占用构建包大小的很大一部分。Intlayer 允许您控制字典的加载方式。
+
+导入模式可以在 `intlayer.config.ts` 文件中全局定义默认值。
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    minify: true,
+  },
+};
+
+export default config;
+```
+
+也可以在您的 `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}` 文件中为每个字典定义。
+
+```ts
+import { type Dictionary, t } from "intlayer";
+
+const appContent: Dictionary = {
+  key: "app",
+  importMode: "dynamic", // 覆盖默认导入模式
+  content: {
+    // ...
+  },
+};
+
+export default appContent;
+```
+
+| 属性             | 类型                               | 默认值     | 描述                                                                         |
+| :--------------- | :--------------------------------- | :--------- | :--------------------------------------------------------------------------- |
+| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'` | **已弃用**：请改用 `dictionary.importMode`。确定字典的加载方式（详见下文）。 |
+
+`importMode` 设置规定了字典内容如何注入到您的组件中。
+您可以在 `intlayer.config.ts` 文件的 `dictionary` 对象下全局定义它，或者在字典的 `.content.ts` 文件中覆盖它。
+
+### 1. 静态模式 (`default`)
+
+在静态模式下，Intlayer 将 `useIntlayer` 替换为 `useDictionary`，并将字典直接注入 JavaScript 构建包中。
+
+- **优点：** 即时渲染（同步），水合过程中零额外网络请求。
+- **缺点：** 构建包包含该特定组件**所有**可用语言的翻译。
+- **最适合：** 单页应用程序 (SPA)。
+
+**转换后的代码示例：**
+
+```tsx
+// 您的代码
+const content = useIntlayer("my-key");
+
+// 优化后的代码（静态）
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. 动态模式
+
+在动态模式下，Intlayer 将 `useIntlayer` 替换为 `useDictionaryAsync`。这使用 `import()`（类似于 Suspense 的机制）来延迟加载当前语言特定的 JSON。
+
+- **优点：** **语言级别的 Tree Shaking。** 查看英文版本的用户将*仅*下载英文字典，永远不会加载法文字典。
+- **缺点：** 在水合过程中每个组件都会触发一次网络请求（资源获取）。
+- **最适合：** 大型文本块、文章或支持多种语言且构建包大小至关重要的应用程序。
+
+**转换后的代码示例：**
+
+```tsx
+// 您的代码
+const content = useIntlayer("my-key");
+
+// 优化后的代码（动态）
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+      (mod) => mod.default
+    ),
+});
+```
+
+> 使用 `importMode: 'dynamic'` 时，如果您在单个页面上有 100 个组件使用 `useIntlayer`，浏览器将尝试 100 次单独的获取。为了避免这种请求“瀑布”，请将内容分组到更少的 `.content` 文件中（例如，每个页面部分一个字典），而不是每个原子组件一个。
+
+### 3. 获取模式 (Fetch Mode)
+
+行为类似于动态模式，但首先尝试从 Intlayer Live Sync API 获取字典。如果 API 调用失败或内容未标记为实时更新，则会回退到动态导入。
+
+> 有关更多详情，请参见 CMS 文档：[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)
+
+> 在获取模式下，不能使用清除和压缩。
+
+## 总结：静态 vs 动态
+
+| 特性              | 静态模式                   | 动态模式                 |
+| :---------------- | :------------------------- | :----------------------- |
+| **JS 构建包大小** | 较大（包含组件的所有语言） | 最小（仅代码，无内容）   |
+| **初始加载**      | 即时（内容在构建包中）     | 轻微延迟（获取 JSON）    |
+| **网络请求**      | 0 次额外请求               | 每个字典 1 次请求        |
+| **Tree Shaking**  | 组件级                     | 组件级 + 语言级          |
+| **最佳用例**      | UI 组件、小型应用          | 文本较多的页面、多种语言 |

package/docs/zh/intlayer_with_next-i18next.md

@@ -257,7 +257,7 @@ export default function LocaleLayout({
   params: { locale: string };
 }) {
   const locale: Locale = (locales as readonly string[]).includes(params.locale)
-    ? (params.locale as any)
+    ? params.locale
     : defaultLocale;
 
   const dir = isRtl(locale) ? "rtl" : "ltr";

package/docs/zh/intlayer_with_next-intl.md

@@ -103,7 +103,7 @@ async function loadMessages(locale: string) {
 }
 
 export default getRequestConfig(async ({ locale }) => {
-  if (!locales.includes(locale as any)) notFound();
+  if (!locales.includes(locale)) notFound();
 
   return {
     messages: await loadMessages(locale),

package/docs/zh/intlayer_with_tanstack+solid.md

@@ -194,9 +194,7 @@ const RootComponent: ParentComponent = (props) => {
       </head>
       <body>
         <IntlayerProvider locale={locale}>
-          <Suspense>
-            {props.children}
-          </Suspense>
+          <Suspense>{props.children}</Suspense>
         </IntlayerProvider>
         <Scripts />
       </body>
@@ -506,12 +504,33 @@ export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
     const { locale } = params;
-    const metaContent = getIntlayer("page-metadata", locale);
+    const path = "/"; // The path for this route
+
+    const metaContent = getIntlayer("app", locale);
 
     return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
       meta: [
         { title: metaContent.title },
-        { content: metaContent.description, name: "description" },
+        { name: "description", content: metaContent.meta.description },
       ],
     };
   },

package/docs/zh/intlayer_with_tanstack.md

@@ -225,9 +225,7 @@ function RootDocument({ children }: { children: ReactNode }) {
         <HeadContent />
       </head>
       <body>
-        <IntlayerProvider locale={locale}>
-          {children}
-        </IntlayerProvider>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
         <Scripts />
       </body>
     </html>
@@ -330,30 +328,20 @@ import { getPrefix } from "intlayer";
 
 export const LOCALE_ROUTE = "{-$locale}" as const;
 
-// 主要工具类型
-export type RemoveLocaleParam<T> = T extends string
-  ? RemoveLocaleFromString<T>
-  : T;
+export type To = StripLocalePrefix<LinkComponentProps["to"]>;
 
-export type To = RemoveLocaleParam<LinkComponentProps["to"]>;
-
-type CollapseDoubleSlashes<S extends string> =
-  S extends `${infer H}//${infer T}` ? CollapseDoubleSlashes<`${H}/${T}`> : S;
+export type StripLocalePrefix<T extends string | undefined> = T extends
+  | `/${typeof LOCALE_ROUTE}/`
+  | `/${typeof LOCALE_ROUTE}`
+  ? "/"
+  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
+    ? `/${Rest}`
+    : T;
 
 type LocalizedLinkProps = {
   to?: To;
 } & Omit<LinkComponentProps, "to">;
 
-// 辅助类型
-type RemoveAll<
-  S extends string,
-  Sub extends string,
-> = S extends `${infer H}${Sub}${infer T}` ? RemoveAll<`${H}${T}`, Sub> : S;
-
-type RemoveLocaleFromString<S extends string> = CollapseDoubleSlashes<
-  RemoveAll<S, typeof LOCALE_ROUTE>
->;
-
 export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
   const { locale } = useLocale();
   const { localePrefix } = getPrefix(locale);
@@ -382,26 +370,26 @@ export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
 import { useNavigate } from "@tanstack/react-router";
 import { getPrefix } from "intlayer";
 import { useLocale } from "react-intlayer";
-import { LOCALE_ROUTE } from "@/components/localized-link";
+import type { StripLocalePrefix } from "@/components/localized-link";
 import type { FileRouteTypes } from "@/routeTree.gen";
 
-type StripLocalePrefix<T extends string> = T extends
-  | `/${typeof LOCALE_ROUTE}`
-  | `/${typeof LOCALE_ROUTE}/`
-  ? "/"
-  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
-    ? `/${Rest}`
-    : never;
+type NavigateFn = ReturnType<typeof useNavigate>;
+type BaseNavigateOptions = Parameters<NavigateFn>[0];
 
 type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
 
-type LocalizedNavigate = {
-  (to: LocalizedTo): ReturnType<ReturnType<typeof useNavigate>>;
-  (
-    opts: { to: LocalizedTo } & Record<string, unknown>
-  ): ReturnType<ReturnType<typeof useNavigate>>;
+export type LocalizedNavigateOptions = Omit<
+  BaseNavigateOptions,
+  "to" | "params"
+> & {
+  to: LocalizedTo;
+  params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
 };
 
+type LocalizedNavigate = (
+  options: LocalizedNavigateOptions
+) => ReturnType<NavigateFn>;
+
 export const useLocalizedNavigate = () => {
   const navigate = useNavigate();
 
@@ -448,38 +436,6 @@ import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
-  head: ({ params }) => {
-    const { locale } = params;
-    const path = "/"; // The path for this route
-
-    const metaContent = getIntlayer("app", locale);
-
-    return {
-      links: [
-        // Canonical link: Points to the current localized page
-        { rel: "canonical", href: getLocalizedUrl(path, locale) },
-
-        // Hreflang: Tell Google about all localized versions
-        ...localeMap(({ locale: mapLocale }) => ({
-          rel: "alternate",
-          hrefLang: mapLocale,
-          href: getLocalizedUrl(path, mapLocale),
-        })),
-
-        // x-default: For users in unmatched languages
-        // Define the default fallback locale (usually your primary language)
-        {
-          rel: "alternate",
-          hrefLang: "x-default",
-          href: getLocalizedUrl(path, defaultLocale),
-        },
-      ],
-      meta: [
-        { title: metaContent.title },
-        { name: "description", content: metaContent.meta.description },
-      ],
-    };
-  },
 });
 
 function RouteComponent() {
@@ -634,12 +590,33 @@ export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
     const { locale } = params;
-    const metaContent = getIntlayer("page-metadata", locale);
+    const path = "/"; // The path for this route
+
+    const metaContent = getIntlayer("app", locale);
 
     return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
       meta: [
         { title: metaContent.title },
-        { content: metaContent.description, name: "description" },
+        { name: "description", content: metaContent.meta.description },
       ],
     };
   },