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

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

    www.youtube.com

    查看 GitHub 上的 应用程序模板

    目录

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

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

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

    什么是 Intlayer 编译器?

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

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

    局限性

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

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


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

    (可选)站点地图与 robots.txt(构建时生成)

    Intlayer 提供 generateSitemapgetMultilingualUrls,可将面向爬虫的多语言 sitemap.xmlrobots.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 外置您的内容。