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

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

    www.youtube.com

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

    目录

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

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

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

    什么是 Intlayer 编译器？

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

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

    局限性

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

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

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

    第 1 步：安装依赖项

    使用 npm 安装必要的包：

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

    • react-intlayer 将 Intlayer 与 React 应用程序集成的包。它为 React 国际化提供上下文提供者和钩子。

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

    第 2 步：配置您的项目

    创建一个配置文件来配置应用程序的语言：

    intlayer.config.ts
    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 插件添加到您的配置中。

    vite.config.ts
    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 步：编译您的代码

    只需使用您的默认语言在组件中编写硬编码字符串。编译器会处理剩下的工作。

    您的页面可能如下所示：

    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;
    • IntlayerProvider 用于向嵌套组件提供语言环境。

    （可选）第 6 步：更改内容的语言

    要更改内容的语言，您可以使用 useLocale 钩子提供的 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.CHINESE)}>将语言更改为中文</button>  );};
    要了解有关 useLocale 钩子的更多信息，请参阅 文档。

    (可选) 第 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