使用您最喜欢的AI助手总结文档，并引用此页面和AI提供商
通过将 Intlayer MCP 服务器集成到您的 AI 助手，您可以直接从 ChatGPT、DeepSeek、Cursor、VSCode 等获取所有文档。
查看 MCP 服务器文档此页面的内容已使用 AI 翻译。
查看英文原文的最新版本如果您有改善此文档的想法，请随时通过在GitHub上提交拉取请求来贡献。
文档的 GitHub 链接复制文档 Markdown 到剪贴板
使用 Intlayer 和 React Router v7 开始国际化 (i18n)
本指南演示了如何在 React Router v7 项目中集成 Intlayer，实现无缝国际化，支持基于区域设置的路由、TypeScript 支持以及现代开发实践。
什么是 Intlayer？
Intlayer 是一个创新的开源国际化 (i18n) 库，旨在简化现代 Web 应用中的多语言支持。
使用 Intlayer，您可以：
- 通过组件级声明式字典轻松管理翻译。
- 动态本地化元数据、路由和内容。
- 通过自动生成的类型确保 TypeScript 支持，提升自动补全和错误检测能力。
- 享受高级功能，如动态区域设置检测和切换。
- 通过 React Router v7 的基于配置的路由系统启用区域设置感知路由。
在 React Router v7 应用中设置 Intlayer 的分步指南
第一步：安装依赖
使用你喜欢的包管理器安装必要的包：
复制代码到剪贴板
npm install intlayer react-intlayernpm install vite-intlayer --save-devintlayer
intlayer
react-intlayer 将 Intlayer 集成到 React 应用中的包。它提供了用于 React 国际化的上下文提供者和钩子。
vite-intlayer 包含用于将 Intlayer 集成到Vite 打包工具的 Vite 插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
第 2 步：项目配置
创建一个配置文件来配置您的应用程序语言：
复制代码到剪贴板
import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, locales: [Locales.ENGLISH, Locales.TURKISH], }, middleware: { prefixDefault: true, // 始终在 URL 中添加默认语言前缀 },};export default config;通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅配置文档。
第3步：配置 React Router v7 路由
设置支持多语言的路由配置：
复制代码到剪贴板
import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [ layout("routes/layout.tsx", [ route("/", "routes/page.tsx"), // 根页面 - 重定向到语言版本 route("/:lang", "routes/[lang]/page.tsx"), // 本地化首页 route("/:lang/about", "routes/[lang]/about/page.tsx"), // 本地化关于页面 ]),] satisfies RouteConfig;第4步：在 Vite 配置中集成 Intlayer
将 intlayer 插件添加到你的配置中：
复制代码到剪贴板
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ reactRouter(), tsconfigPaths(), intlayer(), intlayerMiddlewarePlugin(), ],});intlayer() 是用于将 Intlayer 集成到 Vite 中的插件。它确保内容声明文件的构建，并在开发模式下监视这些文件。它在 Vite 应用中定义了 Intlayer 的环境变量。此外，它还提供别名以优化性能。
第五步：创建布局组件
设置你的根布局和特定语言环境的布局：
根布局
复制代码到剪贴板
tsx;// app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";export default function RootLayout() { return ( <IntlayerProvider> <Outlet /> </IntlayerProvider> );}第6步：声明您的内容
创建并管理您的内容声明以存储翻译：
复制代码到剪贴板
import { t, type Dictionary } from "intlayer";const pageContent = { key: "page", content: { title: t({ en: "Welcome to React Router v7 + Intlayer", tr: "React Router v7 + Intlayer'a Hoş Geldiniz", }), description: t({ en: "Build multilingual applications with ease using React Router v7 and Intlayer.", tr: "使用 React Router v7 和 Intlayer 轻松构建多语言应用程序。", }), aboutLink: t({ en: "了解我们", tr: "关于我们", }), homeLink: t({ en: "首页", tr: "主页", }), },} satisfies Dictionary;export default pageContent;您的内容声明可以在应用程序中的任何位置定义，只要它们被包含在 contentDir 目录中（默认是 ./app）。并且文件扩展名需匹配内容声明文件扩展名（默认是 .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}）。
更多详情，请参阅内容声明文档。
第7步：创建支持多语言的组件
创建一个 LocalizedLink 组件以实现基于语言环境的导航：
复制代码到剪贴板
// app/components/localized-link.tsximport { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";import React from "react";import { Link, useLocation } from "react-router";type RouterLinkProps = React.ComponentProps<typeof Link>;export default function LocalizedLink({ to, ...props }: RouterLinkProps) { const { locale } = useLocale(); const location = useLocation(); const isExternal = (path: string) => /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:"); if (typeof to === "string") { if (to.startsWith("/") && !isExternal(to)) { return <Link to={getLocalizedUrl(to, locale)} {...props} />; } return <Link to={to} {...props} />; } if (to && typeof to === "object") { const pathname = (to as { pathname?: string }).pathname; if (pathname && pathname.startsWith("/") && !isExternal(pathname)) { return ( <Link to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }} {...props} /> ); } return <Link to={to} {...props} />; } return ( <Link to={getLocalizedUrl(location.pathname + location.search, locale)} {...props} /> );}第8步：在您的页面中使用 Intlayer
在您的整个应用程序中访问内容字典：
根重定向页面
复制代码到剪贴板
// app/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() { const { locale } = useLocale(); return <Navigate replace to={locale} />;}本地化主页
复制代码到剪贴板
import { useIntlayer } from "react-intlayer";import LocalizedLink from "~/components/localized-link";export default function Page() { const content = useIntlayer("page"); return ( <div style={{ padding: "2rem", textAlign: "center" }}> <h1>{content.title}</h1> <p>{content.description}</p> <nav style={{ marginTop: "2rem" }}> <LocalizedLink to="/about" style={{ display: "inline-block", padding: "0.5rem 1rem", backgroundColor: "#007bff", color: "white", textDecoration: "none", borderRadius: "4px", }} > {content.aboutLink} </LocalizedLink> </nav> </div> );}想了解更多关于 useIntlayer 钩子的内容，请参考文档。
第9步：创建语言切换组件
创建一个组件，允许用户切换语言：
复制代码到剪贴板
import { getLocalizedUrl, getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";import { useLocation, useNavigate } from "react-router";export default function LocaleSwitcher() { const { locale, availableLocales, setLocale } = useLocale(); const location = useLocation(); const navigate = useNavigate(); const handleLocaleChange = (newLocale: string) => { const localizedUrl = getLocalizedUrl( location.pathname + location.search, newLocale ); setLocale(newLocale); navigate(localizedUrl); }; return ( <div style={{ margin: "1rem 0" }}> <label htmlFor="locale-select">选择语言: </label> <select id="locale-select" value={locale} onChange={(e) => handleLocaleChange(e.target.value)} style={{ padding: "0.25rem", marginLeft: "0.5rem" }} > {availableLocales.map((availableLocale) => ( <option key={availableLocale} value={availableLocale}> {getLocaleName(availableLocale)} </option> ))} </select> </div> );}想了解更多关于 useLocale 钩子的内容，请参考文档。
第10步：添加 HTML 属性管理（可选）
创建一个钩子来管理 HTML 的 lang 和 dir 属性：
复制代码到剪贴板
// app/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};然后在你的根组件中使用它：
复制代码到剪贴板
// app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // 导入钩子export default function RootLayout() { useI18nHTMLAttributes(); // 调用钩子 return ( <IntlayerProvider> <Outlet /> </IntlayerProvider> );}第11步：构建并运行你的应用程序
构建内容字典并运行您的应用程序：
复制代码到剪贴板
# 构建 Intlayer 字典npm run intlayer:build# 启动开发服务器npm run dev第12步：配置 TypeScript（可选）
Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更健壮。
确保您的 TypeScript 配置包含自动生成的类型：
复制代码到剪贴板
{ compilerOptions: { // ... 您现有的 TypeScript 配置 }, include: [ // ... 你现有的包含项 ".intlayer/**/*.ts", // 包含自动生成的类型 ],}Git 配置
建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到你的 Git 仓库。
为此，你可以在 .gitignore 文件中添加以下内容：
复制代码到剪贴板
# 忽略 Intlayer 生成的文件.intlayer生产环境部署
部署你的应用时：
构建你的应用：
bash复制代码复制代码到剪贴板
npm run build构建 Intlayer 字典：
bash复制代码复制代码到剪贴板
npm run intlayer:build如果在生产环境使用中间件，需将 vite-intlayer 移动到依赖中：
bash复制代码复制代码到剪贴板
npm install vite-intlayer --save
您的应用程序现在将支持：
- URL 结构：/en，/en/about，/tr，/tr/about
- 基于浏览器偏好的自动语言环境检测
- 使用 React Router v7 的语言环境感知路由
- 具有自动生成类型的TypeScript 支持
- 具有正确语言环境处理的服务器端渲染
VS Code 扩展
为了提升您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。
该扩展提供：
- 翻译键的自动补全
- 缺失翻译的实时错误检测
- 翻译内容的内联预览
- 快速操作，轻松创建和更新翻译。
有关如何使用该扩展的更多详细信息，请参阅Intlayer VS Code 扩展文档。
深入了解
要进一步使用，您可以实现可视化编辑器或使用内容管理系统（CMS）将内容外部化。
文档参考
本综合指南提供了将 Intlayer 与 React Router v7 集成所需的一切，支持完全国际化的应用程序，具备基于语言环境的路由和 TypeScript 支持。
文档历史
| 版本 | 日期 | 变更内容 |
|---|---|---|
| 5.8.2 | 2025-09-4 | 新增 React Router v7 支持 |