使用您最喜欢的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 链接复制文档 Markdown 到剪贴板
如何将现有的 Vite 和 React 应用程序转换为多语言 (i18n) 应用（2026年 i18n 指南）
查看 GitHub 上的 应用程序模板。
目录
为什么国际化现有应用程序很困难？
如果您曾经尝试为仅针对一种语言构建的应用添加多种语言，您就会明白那种痛苦。这不仅仅是“困难”，而是繁琐。您必须梳理每一个文件，搜寻每一个文本字符串，并将它们移动到单独的字典文件中。
然后是风险部分：用代码钩子替换所有这些文本，而不破坏您的布局或逻辑。这种工作会使新功能的开发停滞数周，感觉像是无休止的重构。
什么是 Intlayer 编译器？
Intlayer 编译器 旨在跳过那些手动的琐事。编译器为您完成字符串提取，而不是由您手动提取。它扫描您的代码，找到文本，并使用 AI 在幕后生成字典。 然后，它在构建期间修改您的代码以注入必要的 i18n 钩子。基本上，您继续像编写单语言应用一样编写应用，编译器会自动处理多语言转换。
编译器文档：/zh/doc/compiler
局限性
由于编译器在 编译时 执行代码分析 and 转换（插入钩子并生成字典），它可能会 减慢应用程序的构建过程。
为了减轻开发期间的影响，您可以将编译器配置为以 'build-only' 模式运行，或在不需要时将其禁用。
在 Vite 和 React 应用程序中设置 Intlayer 的分步指南
第 1 步：安装依赖项
使用 npm 安装必要的包：
复制代码到剪贴板
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer initreact-intlayer 将 Intlayer 与 React 应用程序集成的包。它为 React 国际化提供上下文提供者和钩子。
vite-intlayer 包括用于将 Intlayer 与 Vite 构建器集成的 Vite 插件，以及用于检测用户首选语言、管理 cookie 和处理 URL 重定向的中间件。
第 2 步：配置您的项目
创建一个配置文件来配置应用程序的语言：
复制代码到剪贴板
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.CHINESE, ], defaultLocale: Locales.ENGLISH, }, compiler: { /** * 指示是否应启用编译器。 */ enabled: true, /** * 优化字典的输出目录。 */ output: ({ locale, key }) => `compiler/${locale}/${key}.json`, /** * 仅在生成的文件中插入内容，不含键。 */ noMetadata: false, /** * 字典键前缀 */ dictionaryKeyPrefix: "", // Remove base prefix /** * 指示转换后是否应保存组件。 * 这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。 */ saveComponents: false, }, ai: { provider: "openai", model: "gpt-5-mini", apiKey: process.env.OPEN_AI_API_KEY, applicationContext: "这个应用是一个地图应用", // 注意：您可以自定义此应用描述 },};export default config;注意：请确保在环境变量中设置了 OPEN_AI_API_KEY。
通过此配置文件，您可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅 配置文档。
第 3 步：在 Vite 配置中集成 Intlayer
将 intlayer 插件添加到您的配置中。
复制代码到剪贴板
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({ plugins: [react(), intlayer(), intlayerCompiler()],});intlayer() Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建并在开发模式下监控它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它提供别名以优化性能。intlayerCompiler()Vite 插件用于从组件中提取内容并编写.content文件。
第 4 步：编译您的代码
只需使用您的默认语言在组件中编写硬编码字符串。编译器会处理剩下的工作。
您的页面可能如下所示：
复制代码到剪贴板
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;IntlayerProvider用于向嵌套组件提供语言环境。
（可选）第 6 步：更改内容的语言
要更改内容的语言，您可以使用 useLocale 钩子提供的 setLocale 函数。此函数允许您设置应用程序的语言环境并相应地更新内容。
复制代码到剪贴板
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.CHINESE)}>将语言更改为中文</button> );};要了解有关 useLocale 钩子的更多信息，请参阅 文档。
(可选) 第 7 步：填充缺失的翻译
Intlayer 提供了一个 CLI 工具来帮助您填充缺失的翻译。您可以使用 intlayer 命令来测试并填充代码中缺失的翻译。
复制代码到剪贴板
npx intlayer test # 测试是否存在缺失的翻译复制代码到剪贴板
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
复制代码到剪贴板
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 之前执行脚本
复制代码到剪贴板
{ "scripts": { "dev": "vite", "prebuild": "node generate-seo.mjs", "build": "vite build", "preview": "vite preview" }}若使用 pnpm 或 yarn，请相应调整命令；也可在 CI 或其他步骤中调用该脚本。
Git 配置
建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
为此，您可以将以下指令添加到 .gitignore 文件中：
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayerVS Code 扩展
为了提升您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。
此扩展提供：
- 翻译键的 自动补全。
- 缺失翻译的 实时错误检测。
- 翻译内容的 内联预览。
- 轻松创建和更新翻译的 快速操作。
有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。