作者:

Creation:2024-03-07Last update:2026-06-23

在 GitHub 上查看应用程序模板

此页面有可用的应用程序模板。

查看展示应用

此页面链接到模板的在线演示。

观看视频教程

此页面有视频教程。

将此文档参考到您的 AI 助手ChatGPT Claude DeepSeek Google AI mode Gemini Perplexity Mistral Grok

使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商

版本历史

"更新 Solid useIntlayer API 用法以直接访问属性"
v8.9.02026/5/4
"Update compiler options, add FilePathPattern support"
v8.2.02026/3/9
"首次发布"
v8.1.62026/2/23

此页面的内容已使用 AI 翻译。

查看英文原文的最新版本

编辑此文档

如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。

文档的 GitHub 链接

Copy

复制文档 Markdown 到剪贴板

如何将现有的 Vite 和 React 应用程序转换为多语言 (i18n) 应用（2026年 i18n 指南）

Name: Intlayer
Rating: 4.92 (64 reviews)
Author: Intlayer

www.youtube.com

ide.intlayer.org

intlayer-vite-react-template.vercel.app

查看 GitHub 上的应用程序模板。

为什么国际化现有应用程序很困难？

如果您曾经尝试为仅针对一种语言构建的应用添加多种语言，您就会明白那种痛苦。这不仅仅是“困难”，而是繁琐。您必须梳理每一个文件，搜寻每一个文本字符串，并将它们移动到单独的字典文件中。

然后是风险部分：用代码钩子替换所有这些文本，而不破坏您的布局或逻辑。这种工作会使新功能的开发停滞数周，感觉像是无休止的重构。

什么是 Intlayer 编译器？

Intlayer 编译器 旨在跳过那些手动的琐事。编译器为您完成字符串提取，而不是由您手动提取。它扫描您的代码，找到文本，并使用 AI 在幕后生成字典。然后，它在构建期间修改您的代码以注入必要的 i18n 钩子。基本上，您继续像编写单语言应用一样编写应用，编译器会自动处理多语言转换。

编译器文档：/zh/doc/compiler

局限性

由于编译器在 编译时 执行代码分析 and 转换（插入钩子并生成字典），它可能会 减慢应用程序的构建过程。

为了减轻开发期间的影响，您可以将编译器配置为以 'build-only' 模式运行，或在不需要时将其禁用。

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

1
安装依赖

使用 npm 安装必要的包：
bash
复制代码
复制代码到剪贴板
npx intlayer init --interactive
--interactive 标志是可选的。如果你是 AI 代理，请使用 intlayer-cli init。

此命令将检测你的环境并安装所需的包。例如：
bash
复制代码
复制代码到剪贴板
npm install intlayer react-intlayer npm install vite-intlayer --save-dev
- intlayer 核心包，提供国际化工具用于配置管理、翻译、内容声明、转译和 CLI 命令。
- react-intlayer 将 Intlayer 与 React 应用集成的包。它为 React 国际化提供上下文提供程序和 hooks。
- vite-intlayer 包含用于将 Intlayer 与 Vite bundler 集成的 Vite 插件，以及用于检测用户首选语言环境、管理 cookie 和处理 URL 重定向的中间件。

配置你的项目

创建配置文件以配置应用程序的语言：

intlayer.config.ts

复制代码

复制代码到剪贴板

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  compiler: {
    /**
     * 指示编译器是否应启用。
     */
    enabled: true,

    /**
     * 优化字典的输出目录。
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * 仅在生成的文件中插入内容，不包含键。
     */
    noMetadata: false,

    /**
     * 字典键前缀
     */
    dictionaryKeyPrefix: "", // 移除基础前缀

    /**
     * 指示转换后的组件是否应保存。
     *
     * - 如果为 `true`，编译器将在磁盘上重写组件文件。因此转换将是永久的，编译器将在下一个过程中跳过转换。这样，编译器可以转换应用，然后可以将其移除。
     *
     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，保持基础代码库完整。转换仅在内存中进行。
     */
    saveComponents: false,
  },
  ai: {
    provider: "openai",
    model: "gpt-5-mini",
    apiKey: process.env.OPEN_AI_API_KEY,
    applicationContext: "This app is an map app", // 注意：你可以自定义此应用描述
  },
};

export default config;

注意：确保你的 OPEN_AI_API_KEY 已在环境变量中设置。

通过此配置文件，你可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用 Intlayer 控制台日志等。有关可用参数的完整列表，请参阅配置文档。

3
在你的 Vite 配置中集成 Intlayer

将 intlayer 插件添加到你的配置中。
vite.config.ts
复制代码
复制代码到剪贴板
import { defineConfig } from "vite"; import react from "@vitejs/plugin-react-swc"; import { intlayer } from "vite-intlayer"; // https://vitejs.dev/config/ export default defineConfig({ plugins: [ react(), intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api"), }, }), ], });
intlayer() Vite 插件用于将 Intlayer 与 Vite 集成。它确保构建内容声明文件并在开发模式下监视它们。它在 Vite 应用中定义 Intlayer 环境变量。此外，它提供别名以优化性能。

intlayerCompiler() Vite 插件用于从组件提取内容并写入 .content 文件。

从 Intlayer v9 开始，编译器直接捆绑到 intlayer() 插件中，一旦设置了 compiler.enabled 和 compiler.output 路径，就会自动激活。如下所示单独注册 intlayerCompiler() 现在是可选的——如果也添加了它，它会自动去重。请参阅 v9 发布说明。

编译你的代码

仅需使用默认语言中的硬编码字符串编写组件。编译器会处理其余部分。

你的页面可能看起来的示例：

src/App.tsx

复制代码

复制代码到剪贴板

import { useState, type FC } from "react";
import reactLogo from "./assets/react.svg";
import viteLogo from "/vite.svg";
import "./App.css";
import { IntlayerProvider } from "react-intlayer";

const AppContent: FC = () => {
  const [count, setCount] = useState(0);

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} className="logo" alt="Vite logo" />
        </a>
        <a href="https://react.dev" target="_blank">
          <img src={reactLogo} className="logo react" alt="React logo" />
        </a>
      </div>
      <h1>Vite + React</h1>
      <div className="card">
        <button onClick={() => setCount((count) => count + 1)}>
          count is {count}
        </button>
        <p>
          Edit <code>src/App.tsx</code> and save to test HMR
        </p>
      </div>
      <p className="read-the-docs">
        Click on the Vite and React logos to learn more
      </p>
    </>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

i18n/app-content.content.json

复制代码

复制代码到剪贴板

{
  key: "app-content",
  content: {
    nodeType: "translation",
    translation: {
      en: {
        viteLogo: "Vite logo",
        reactLogo: "React logo",
        title: "Vite + React",
        countButton: "count is",
        editMessage: "Edit",
        hmrMessage: "and save to test HMR",
        readTheDocs: "Click on the Vite and React logos to learn more",
      },
      fr: {
        viteLogo: "Logo Vite",
        reactLogo: "Logo React",
        title: "Vite + React",
        countButton: "compte est",
        editMessage: "Modifier",
        hmrMessage: "et enregistrer pour tester HMR",
        readTheDocs: "Cliquez sur les logos Vite et React pour en savoir plus",
      },
    }
  }
}

src/App.tsx

复制代码

复制代码到剪贴板

import { useState, type FC } from "react";
import reactLogo from "./assets/react.svg";
import viteLogo from "/vite.svg";
import "./App.css";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const [count, setCount] = useState(0);
  const content = useIntlayer("app-content");

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
        </a>
        <a href="https://react.dev" target="_blank">
          <img
            src={reactLogo}
            className="logo react"
            alt={content.reactLogo.value}
          />
        </a>
      </div>
      <h1>{content.title}</h1>
      <div className="card">
        <button onClick={() => setCount((count) => count + 1)}>
          {content.countButton} {count}
        </button>
        <p>
          {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}
        </p>
      </div>
      <p className="read-the-docs">{content.readTheDocs}</p>
    </>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

IntlayerProvider 用于向嵌套组件提供语言环境。

更改内容的语言

可选

要更改内容的语言，你可以使用 useLocale hook 提供的 setLocale 函数。此函数允许你设置应用程序的语言环境并相应地更新内容。

src/components/LocaleSwitcher.tsx

复制代码

复制代码到剪贴板

import type { FC } from "react";
import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher: FC = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.English)}>
      Change Language to English
    </button>
  );
};

要了解更多关于 useLocale hook 的信息，请参阅文档。

7
填充缺失的翻译
可选

Intlayer 提供了一个 CLI 工具来帮助你填充缺失的翻译。你可以使用 intlayer 命令来测试和填充代码中缺失的翻译。
bash
复制代码
复制代码到剪贴板
npx intlayer test # 测试是否有缺失的翻译
bash
复制代码
复制代码到剪贴板
npx intlayer fill # 填充缺失的翻译
有关更多详细信息，请参阅 CLI 文档

（可选）站点地图与 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 或其他步骤中调用该脚本。

Git 配置

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

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

.gitignore

复制代码

复制代码到剪贴板

# 忽略 Intlayer 生成的文件
.intlayer

VS Code 扩展

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

从 VS Code 市场安装

此扩展提供：

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

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

深入了解

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

React Router v7 (fs-routes)Vite和Vue

版本历史

如何将现有的 Vite 和 React 应用程序转换为多语言 (i18n) 应用（2026年 i18n 指南）

目录

为什么国际化现有应用程序很困难？

什么是 Intlayer 编译器？

局限性

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

安装依赖

配置你的项目

在你的 Vite 配置中集成 Intlayer

编译你的代码

更改内容的语言

填充缺失的翻译

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

站点地图

Robots.txt

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

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

Git 配置

VS Code 扩展

深入了解

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