@intlayer/docs 8.12.4 → 9.0.0-canary.10

package/docs/zh/intlayer_with_vite+vanilla.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-03-23
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Vanilla JS i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Vite + Vanilla JS 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -25,6 +25,7 @@ history:
   - version: 8.4.10
     date: 2026-03-23
     changes: "初始历史"
+author: aymericzip
 ---
 
 # 使用 Intlayer 翻译您的 Vite 和 Vanilla JS 网站 | 国际化 (i18n)
@@ -92,259 +93,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 Vite 和 Vanilla JS 应用程序中设置 Intlayer 的分步指南
-
-### 第 1 步：安装依赖项
-
-使用 npm 安装必要的软件包：
-
-```bash packageManager="npm"
-npm install intlayer vanilla-intlayer
-npm install vite-intlayer --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer vanilla-intlayer
-pnpm add vite-intlayer --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer vanilla-intlayer
-yarn add vite-intlayer --save-dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer vanilla-intlayer
-bun add vite-intlayer --dev
-bun x intlayer init
-```
-
-- **intlayer**
-  核心库，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、转译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md) 的国际化工具。
-
-- **vanilla-intlayer**
-  将 Intlayer 与纯 JavaScript / TypeScript 应用程序集成的库。它提供了一个发布/订阅单例 (`IntlayerClient`) 和基于回调的辅助工具 (`useIntlayer`, `useLocale` 等)，因此您的应用程序的任何部分都可以对语言更改做出反应，而不依赖于 UI 框架。
-
-- **vite-intlayer**
-  包含用于将 Intlayer 与 [Vite 打包器](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Vite 插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
-
-### 第 2 步：配置项目
-
-创建一个配置文件来配置应用程序的语言：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // 您的其他语言
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-> 通过此配置文件，您可以设置本地化 URL、中间件重定向、Cookie 名称、内容声明的位置和扩展名、在控制台中禁用 Intlayer 日志等。有关可用参数的完整列表，请参阅 [配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-### 第 3 步：在 Vite 配置中集成 Intlayer
-
-在您的配置中添加 intlayer 插件。
-
-```typescript fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [intlayer()],
-});
-```
-
-> `intlayer()` Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建并在开发模式下监控它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它还提供别名以优化性能。
-
-### 第 4 步：在入口点引导 Intlayer
-
-在渲染任何内容**之前**调用 `installIntlayer()`，以便全局语言单例准备就绪。
-
-```typescript fileName="src/main.ts" codeFormat="typescript"
-import { installIntlayer } from "vanilla-intlayer";
-
-// 必须在渲染任何 i18n 内容之前调用。
-installIntlayer();
-
-// 导入并运行您的应用模块。
-import "./app.js";
-```
-
-如果您还使用 `md()` 内容声明 (Markdown)，请同时安装 Markdown 渲染器：
-
-```typescript fileName="src/main.ts" codeFormat="typescript"
-import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";
-
-installIntlayer();
-installIntlayerMarkdown();
-
-import "./app.js";
-```
-
-### 第 5 步：声明您的内容
-
-创建并管理您的内容声明以存储翻译：
-
-```typescript fileName="src/app.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { insert, t, type Dictionary } from "intlayer";
-
-const appContent = {
-  key: "app",
-  content: {
-    title: "Vite + Vanilla",
-
-    viteLogoLabel: t({
-      en: "Vite Logo",
-      fr: "Logo Vite",
-      es: "Logo Vite",
-    }),
-
-    count: insert(
-      t({
-        en: "count is {{count}}",
-        fr: "le compte est {{count}}",
-        es: "el recuento es {{count}}",
-      })
-    ),
-
-    readTheDocs: t({
-      en: "Click on the Vite logo to learn more",
-      fr: "Cliquez sur le logo Vite pour en savoir plus",
-      es: "点击 Vite 标志了解更多信息",
-    }),
-  },
-} satisfies Dictionary;
-
-export default appContent;
-```
-
-```json fileName="src/app.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "app",
-  "content": {
-    "title": "Vite + Vanilla",
-    "viteLogoLabel": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Vite Logo",
-        "fr": "Logo Vite",
-        "es": "Logo Vite"
-      }
-    },
-    "count": {
-      "nodeType": "insertion",
-      "insertion": {
-        "nodeType": "translation",
-        "translation": {
-          "en": "count is {{count}}",
-          "fr": "le compte est {{count}}",
-          "es": "el recuento es {{count}}"
-        }
-      }
-    },
-    "readTheDocs": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Click on the Vite logo to learn more",
-        "fr": "Cliquez sur le logo Vite pour en savoir plus",
-        "es": "点击 Vite 标志了解更多信息"
-      }
-    }
-  }
-}
-```
-
-> 只要您的内容声明包含在 `contentDir` 目录（默认为 `./src`）中，就可以在应用程序的任何位置定义它们。并且匹配内容声明文件扩展名（默认为 `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`）。
->
-> 有关更多详细信息，请参阅 [内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
-
-### 第 6 步：在 JavaScript 中使用 Intlayer
-
-`vanilla-intlayer` 镜像了 `react-intlayer` 的表面 API：`useIntlayer(key, locale?)` 直接返回翻译后的内容。在结果上链式调用 `.onChange()` 以订阅语言更改 - 这相当于 React 的显式重新渲染。
-
-```typescript fileName="src/main.ts" codeFormat="typescript"
-import { installIntlayer, useIntlayer } from "vanilla-intlayer";
-
-installIntlayer();
-
-// 获取当前语言的初始内容。
-// 链式调用 .onChange()，以便在语言发生变化时得到通知。
-const content = useIntlayer("app").onChange((newContent) => {
-  // 仅重新渲染或补丁受影响的 DOM 节点
-  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
-    newContent.title
-  );
-  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
-    String(newContent.readTheDocs);
-});
-
-// 初始渲染
-document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
-  content.title
-);
-document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
-  String(content.readTheDocs);
-```
-
-> 通过将叶值包装在 `String()` 中将其作为字符串访问，这将调用节点的 `toString()` 方法并返回翻译后的文本。
->
-> 当您需要原生 HTML 属性（例如 `alt`, `aria-label`）的值时，请直接使用 `.value`：
->
-> ```typescript
-> img.alt = content.viteLogoLabel.value;
-> ```
-
-### (可选) 第 7 步：更改内容的语言
-
-要更改内容的语言，请使用 `useLocale` 公开的 `setLocale` 函数。
-
-```typescript fileName="src/locale-switcher.ts" codeFormat="typescript"
-import { getLocaleName } from "intlayer";
-import { useLocale } from "vanilla-intlayer";
-
-export function setupLocaleSwitcher(container: HTMLElement): () => void {
-  const { locale, availableLocales, setLocale, subscribe } = useLocale();
-
-  const select = document.createElement("select");
-  select.setAttribute("aria-label", "Language");
-
-  const render = (currentLocale: string) => {
-    select.innerHTML = availableLocales
-      .map(
-        (loc) =>
-          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
-            ${getLocaleName(loc)}
-          </option>`
-      )
-      .join("");
-  };
-
-  render(locale);
-  container.appendChild(select);
-
-  select.addEventListener("change", () => setLocale(select.value as any));
-
-  // 当语言从其他地方更改时，保持下拉菜单同步
-  return subscribe((newLocale) => render(newLocale));
-}
-```
-
 ### (可选) 第 8 步：渲染 Markdown 和 HTML 内容
 
 Intlayer 支持 `md()` 和 `html()` 内容声明。在纯 JS 中，编译后的输出通过 `innerHTML` 作为原始 HTML 插入。
@@ -404,178 +152,6 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 > });
 > ```
 
-### (可选) 第 9 步：在应用程序中添加本地化路由
-
-要为每种语言创建唯一的路由（对 SEO 很有用），您可以在 Vite 配置中使用 `intlayerProxy` 进行服务端语言检测。
-
-首先，在您的 Vite 配置中添加 `intlayerProxy`：
-
-> 请注意，要在生产环境中使用 `intlayerProxy`，您需要将 `vite-intlayer` 从 `devDependencies` 移动到 `dependencies`。
-
-```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayerProxy(), // 应该放在第一位
-    intlayer(),
-  ],
-});
-```
-
-### (可选) 第 10 步：语言更改时更改 URL
-
-要在语言更改时更新浏览器 URL，请在安装 Intlayer 后调用 `useRewriteURL()`：
-
-```typescript fileName="src/main.ts" codeFormat="typescript"
-import { installIntlayer, useRewriteURL } from "vanilla-intlayer";
-
-installIntlayer();
-
-// 立即重写 URL，并在随后的每次语言更改时重写。
-// 返回一个用于清理的取消订阅函数。
-const stopRewriteURL = useRewriteURL();
-```
-
-### (可选) 第 11 步：切换 HTML 语言和方向属性
-
-更新 `<html>` 标签的 `lang` 和 `dir` 属性以匹配当前语言，以提高可访问性和 SEO。
-
-```typescript fileName="src/main.ts" codeFormat="typescript"
-import { getHTMLTextDir } from "intlayer";
-import { installIntlayer, useLocale } from "vanilla-intlayer";
-
-installIntlayer();
-
-useLocale({
-  onLocaleChange: (locale) => {
-    document.documentElement.lang = locale;
-    document.documentElement.dir = getHTMLTextDir(locale);
-  },
-});
-```
-
-### (可选) 第 12 步：按语言延迟加载字典
-
-对于大型应用程序，您可能希望将每种语言的字典拆分到其自己的块中。结合 Vite 的动态 `import()` 使用 `useDictionaryDynamic`：
-
-```typescript fileName="src/app.ts" codeFormat="typescript"
-import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";
-
-installIntlayer();
-
-const unsubscribe = useDictionaryDynamic(
-  {
-    en: () => import("../.intlayer/dictionaries/en/app.mjs"),
-    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
-    es: () => import("../.intlayer/dictionaries/es/app.mjs"),
-  },
-  "app"
-).onChange((content) => {
-  document.querySelector("h1")!.textContent = String(content.title);
-});
-```
-
-> 每种语言的包仅在该语言激活时才获取，并且结果会被缓存 - 随后切换到同一语言是即时的。
-
-### (可选) 第 13 步：提取组件内容
-
-如果您已经拥有代码库，转换数千个文件可能会非常耗时。
-
-为了简化此过程，Intlayer 建议使用 [编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) / [提取器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 来转换您的组件并提取内容。
-
-要进行设置，您可以在 `intlayer.config.ts` 文件中添加 `compiler` 部分：
-
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... 配置的其余部分
-  compiler: {
-    /**
-     * 指示是否应启用编译器。
-     */
-    enabled: true,
-
-    /**
-     * 定义输出文件路径
-     */
-    output: ({ fileName, extension }) => `./${fileName}${extension}`,
-
-    /**
-     * 指示组件在被转换后是否应保存。
-     * 这样，编译器只需运行一次来转换应用程序，然后就可以移除它。
-     */
-    saveComponents: false,
-
-    /**
-     * 字典键前缀
-     */
-    dictionaryKeyPrefix: "",
-  },
-};
-
-export default config;
-```
-
-<Tabs>
- <Tab value='Extract 命令'>
-
-运行提取器来转换您的组件并提取内容
-
-```bash packageManager="npm"
-npx intlayer extract
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer extract
-```
-
-```bash packageManager="yarn"
-yarn intlayer extract
-```
-
-```bash packageManager="bun"
-bun x intlayer extract
-```
-
- </Tab>
- <Tab value='Babel 编译器'>
-
-更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // 添加编译器插件
-  ],
-});
-```
-
-```bash packageManager="npm"
-npm run build # 或 npm run dev
-```
-
-```bash packageManager="pnpm"
-pnpm run build # 或 pnpm run dev
-```
-
-```bash packageManager="yarn"
-yarn build # 或 yarn dev
-```
-
-```bash packageManager="bun"
-bun run build # 或 bun run dev
-```
-
- </Tab>
-</Tabs>
-
 ### （可选）站点地图与 robots.txt（构建时生成）
 
 Intlayer 提供 `generateSitemap` 与 `getMultilingualUrls`，可将面向爬虫的多语言 `sitemap.xml` 和 `robots.txt` 格式化并自动写入 `public/`。实践中在 Vite **之前**运行小型 Node 脚本（例如 npm 的 `predev` / `prebuild`）即可在构建或开发时生成这些文件。