作者:
    Aymeric PINEAU
    Creation:2026-03-23Last update:2026-06-23

    使用 Intlayer 翻译您的 Vite 和 Vanilla JS 网站 | 国际化 (i18n)

    ide.intlayer.org
    intlayer-vite-vanilla.vercel.app

    目录

    为什么选择 Inlayer 而不是替代品？

    与“i18next”或“i18n.js”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：

    Vite 全面覆盖

    Intlayer 经过优化，可与 Vite 完美配合，提供与框架无关的内容管理、TypeScript 支持以及扩展国际化 (i18n) 所需的所有功能。

    捆绑尺寸

    不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于将捆绑包和页面大小减少多达 50%。

    </Accordion>

    可维护性

    确定应用程序内容的范围有利于大型应用程序的维护。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有完全类型化 (fully typed)，以确保您的内容的准确性。

    人工智能代理

    共置内容减少大型语言模型 (LLM) 所需的上下文。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 CLI、LSP、MCP 和 agent skills，使 AI 代理的开发者体验 (DX) 更加流畅。

    自动化

    使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个编译器来自动提取内容，以及一个网络平台来帮助在后台翻译。

    </Accordion>

    表现

    将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。

    无需开发即可扩展

    Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个自托管的可视化编辑器和一个完整的 CMS 来帮助您管理多语言内容实时，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。

    </AccordionGroup>

    在 Vite 和 Vanilla JS 应用中设置 Intlayer 的分步指南

    1. 安装依赖

      使用 npm 安装必要的包：

      bash
      npx intlayer init --interactive
      --interactive 标志是可选的。如果你是 AI 代理，请使用 intlayer-cli init。
      此命令将检测你的环境并安装所需的包。例如：
      bash
      npm install intlayer vanilla-intlayer
npm install vite-intlayer --save-dev

      • intlayer 核心包，提供国际化工具，用于配置管理、翻译、内容声明、代码转换和 CLI 命令。

      • vanilla-intlayer 将 Intlayer 与纯 JavaScript / TypeScript 应用集成的包。它提供一个 pub/sub 单例 (IntlayerClient) 和基于回调的辅助函数 (useIntlayer、useLocale 等)，使你的应用的任何部分都可以对语言环境变化做出反应，而无需依赖 UI 框架。

      • vite-intlayer 包含用于将 Intlayer 与 Vite bundler 集成的 Vite 插件，以及用于检测用户首选语言环境、管理 cookie 和处理 URL 重定向的中间件。

    2. 项目配置

      创建一个配置文件以配置应用的语言：

      intlayer.config.ts
      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 日志等。有关可用参数的完整列表，请参考 配置文档。

    3. 在你的 Vite 配置中集成 Intlayer

      将 intlayer 插件添加到你的配置中。

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
      intlayer() Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建，并在开发模式下监视它们。它在 Vite 应用中定义 Intlayer 环境变量。此外，它提供别名以优化性能。

    4. 在你的入口点引导 Intlayer

      在渲染任何内容之前调用 installIntlayer()，以便全局语言环境单例已准备好。

      src/main.ts
      import { installIntlayer } from "vanilla-intlayer";

// 必须在渲染任何 i18n 内容之前调用。
installIntlayer();

// 导入并运行你的应用模块。
import "./app.js";

      如果你还使用 md() 内容声明（Markdown），请也安装 markdown 渲染器：

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";

installIntlayer();
installIntlayerMarkdown();

import "./app.js";

    5. 声明你的内容

      创建并管理内容声明以存储翻译：

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      zh: "Vite 标志",
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        zh: "计数是 {{count}}",
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      zh: "点击 Vite 标志以了解更多信息",
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Haga clic en el logotipo de Vite para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

      你的内容声明可以在应用的任何地方定义，只要它们包含在 contentDir 目录中（默认情况下为 ./src）。并匹配内容声明文件扩展名（默认为 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

      有关更多详细信息，请参考 内容声明文档。

    6. 在你的 JavaScript 中使用 Intlayer

      vanilla-intlayer 镜像了 react-intlayer 的表面 API：useIntlayer(key, locale?) 直接返回翻译的内容。在结果上链接 .onChange() 以订阅语言环境变化 - 这是 React 重新渲染的显式等效物。

      src/main.ts
      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 函数。

      src/locale-switcher.ts
      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() 内容声明。在 vanilla JS 中，编译的输出通过 innerHTML 作为原始 HTML 插入。

      编译并注入 HTML：

      src/main.ts
      import {
  compileMarkdown,
  installIntlayerMarkdown,
  useIntlayer,
} from "vanilla-intlayer";

installIntlayerMarkdown();

const content = useIntlayer("app").onChange((newContent) => {
  const el = document.querySelector<HTMLDivElement>(".edit-note")!;
  el.innerHTML = compileMarkdown(String(newContent.editNote));
});

document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
  compileMarkdown(String(content.editNote));
      TIP
      String(content.editNote) 调用 IntlayerNode 上的 toString()，它返回原始 Markdown 字符串。将其传递给 compileMarkdown 以获取 HTML 字符串，然后通过 innerHTML 设置它。
      WARNING

      仅对受信任的内容使用 innerHTML。如果 markdown 来自用户输入，请先进行清理（例如使用 DOMPurify）。你可以动态安装清理渲染器：

      typescript
      import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";

await installIntlayerMarkdownDynamic(async () => {
  const DOMPurify = await import("dompurify");
  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));
});

    9. 向你的应用添加本地化路由

      可选

      要为每种语言创建唯一的路由（对 SEO 有用），你可以在 Vite 配置中使用 intlayerProxy 进行服务器端语言环境检测。

      首先，将 intlayerProxy 添加到你的 Vite 配置：

      请注意，要在生产中使用 intlayerProxy，你需要将 vite-intlayer 从 devDependencies 移到 dependencies。
      从 Intlayer v9 开始，intlayerProxy() 直接捆绑到 intlayer() 插件中，并通过 routing.enableProxy 选项默认启用（默认为 true）。单独注册如下所示现在是可选的 — 为了向后兼容和需要控制插件顺序的设置而保留。设置 routing.enableProxy: false 以选择退出。有关更多信息，请参见 v9 发布说明。
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

    10. 当语言环境更改时更改 URL

      可选

      要在语言环境更改时更新浏览器 URL，请在安装 Intlayer 后调用 useRewriteURL()：

      src/main.ts
      import { installIntlayer, useRewriteURL } from "vanilla-intlayer";

installIntlayer();

// 立即重写 URL，并在随后的每次语言环境更改时重写。
// 返回一个用于清理的取消订阅函数。
const stopRewriteURL = useRewriteURL();

    11. 切换 HTML 语言和方向属性

      可选

      更新 <html> 标签的 lang 和 dir 属性以匹配当前语言环境，以实现可访问性和 SEO。

      src/main.ts
      import { getHTMLTextDir } from "intlayer";
import { installIntlayer, useLocale } from "vanilla-intlayer";

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    12. 按语言环境延迟加载字典

      可选

      对于大型应用，你可能希望将每个语言环境的字典拆分为其自己的块。使用 useDictionaryDynamic 以及 Vite 的动态 import()：

      src/app.ts
      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. 提取你的组件的内容

      可选

      如果你有现有的 codebase，转换数千个文件可能会耗时。

      为了简化此过程，Intlayer 提供了一个 编译器 / 提取器 来转换你的组件并提取内容。

      要设置它，你可以在 intlayer.config.ts 文件中添加一个 compiler 部分：

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 配置的其余部分
  compiler: {
    /**
     * 指示是否应启用编译器。
     */
    enabled: true,

    /**
     * 定义输出文件路径
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 指示转换后是否应保存组件。
     *
     * - 如果为 `true`，编译器将在磁盘中重写组件文件。所以转换将是永久的，编译器将跳过下一个过程的转换。这样，编译器可以转换应用，然后可以被移除。
     *
     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，并保持基础 codebase 完整。转换将仅在内存中进行。
     */
    saveComponents: false,

    /**
     * 字典键前缀
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      运行提取器来转换你的组件并提取内容

      bash
      npx intlayer extract
      从 v9 开始，intlayerCompiler 包含在 intlayer 插件中。所以你不需要手动添加它。

      更新你的 vite.config.ts 以包含 intlayerCompiler 插件：

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // 添加编译器插件
  ],
});
      bash
      npm run build # 或 npm run dev

    （可选）站点地图与 robots.txt（构建时生成）

    Intlayer 提供 generateSitemap 与 getMultilingualUrls，可将面向爬虫的多语言 sitemap.xml 和 robots.txt 格式化并自动写入 public/。实践中在 Vite 之前运行小型 Node 脚本（例如 npm 的 predev / prebuild）即可在构建或开发时生成这些文件。

    站点地图

    Intlayer 的站点地图生成会尊重你的语言配置，并包含爬虫所需的元数据。

    生成的站点地图支持 xhtml:link（hreflang）。与只列出扁平 URL 不同，Intlayer 会在各语言版本之间建立双向关联（例如 /about、/fr/about 或 /about?lang=fr，取决于路由模式）。

    Robots.txt

    使用 getMultilingualUrls，使 Disallow 覆盖敏感路径的每一种本地化写法。

    1. 在项目根目录添加 generate-seo.mjs

    generate-seo.mjs
    import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

    需已安装 intlayer 以便脚本导入。生产环境请设置环境变量 SITE_URL（例如在 CI 中）。

    建议在 Node 中使用 generate-seo.mjs（ESM）。若使用 generate-seo.js，请在 package.json 中设置 "type": "module" 或以其他方式启用 ESM。

    2. 在运行 Vite 之前执行脚本

    package.json
    {
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

    若使用 pnpm 或 yarn，请相应调整命令；也可在 CI 或其他步骤中调用该脚本。

    配置 TypeScript

    确保您的 TypeScript 配置包含自动生成的类型。

    tsconfig.json
    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    Git 配置

    建议忽略由 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。

    为此，您可以在 .gitignore 文件中添加以下指令：

    bash
    # 忽略由 Intlayer 生成的文件
.intlayer

    VS Code 扩展

    为了改善您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。

    从 VS Code Marketplace 安装

    此扩展提供：

    • 翻译键的自动补全。
    • 缺失翻译的实时错误检测。
    • 翻译内容的内联预览。
    • 轻松创建和更新翻译的快速操作。

    有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。

    深入了解

    要深入了解，您可以实现 可视化编辑器 或使用 CMS 外置您的内容。

    Vite和PreactVanilla JS (无打包器)