# @dts-stn/react-router-i18n-routes 中文文档规范地址：https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/ 版本：1\.0\.1 npm 元数据更新时间：2026-10-18T20:21:21.612Z 中文译文更新时间：2026-11-12T23:48:35.946Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40dts-stn/react-router-i18n-routes 原文对照：https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/?lang=original 项目主页：https://github.com/STN-DTS/react-router-i18n-routes#readme 源码仓库：https://github.com/STN-DTS/react-router-i18n-routes ## 关键信息（来自 npm 元数据） - 包体积（解压后）：121 kB，19 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.0\.0 - 运行依赖：0 个 - peer 依赖：react \>=18\.0\.0，react-router ^7\.0\.0 \|\| ^8\.0\.0，@react-router/dev ^7\.0\.0 \|\| ^8\.0\.0 - 首次发布：2026-10-18T19:05:22.813Z - 最新版本发布：2026-10-18T19:11:13.403Z - 近 30 天下载量：2909（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：3（近 12 个月 3 个） ## 中文简介类型安全,为React Routers(帧模式)所翻译的(i18n)路由定义. ## 安装 ```sh npm install @dts-stn/react-router-i18n-routes ``` 也可以使用：`pnpm add @dts-stn/react-router-i18n-routes`、`yarn add @dts-stn/react-router-i18n-routes`、`bun add @dts-stn/react-router-i18n-routes` ## README # @dts-stn/ react-router-i18n-routes (英语) [![npm version](https://img.shields.io/npm/v/@dts-stn/react-router-i18n-routes)](https://www.npmjs.com/package/@dts-stn/react-router-i18n-routes) [![CI](https://github.com/STN-DTS/react-router-i18n-routes/actions/workflows/ci.yaml/badge.svg)](https://github.com/STN-DTS/react-router-i18n-routes/actions/workflows/ci.yaml) [![types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)](https://www.typescriptlang.org/) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/STN-DTS/react-router-i18n-routes/blob/main/LICENSE) **类型安全, 翻译 URL for [反应路由器](https://reactrouter.com/) 框架模式.** 申报每页一次,每种语言都有路径. 您可以得到 React 路由器路由配置, 本地化链接和重新定向,语言检测,和一个语言切换器. 每个路由文件和语言都是字符串字元类型,所以断开的链接是编译错误,而不是404. ```ts const i18nRoutes = defineI18nRoutes([ { id: 'CASE-0001', file: 'routes/case.tsx', paths: { en: '/en/case/:caseId', fr: '/fr/dossier/:caseId' }, }, ]); const i18nRouting = createI18nRouting(i18nRoutes); i18nRouting.getPath('routes/case.tsx', 'fr', { params: { caseId: '42' } }); // '/fr/dossier/42' i18nRouting.translatePath('/en/case/42', 'fr'); // '/fr/dossier/42' i18nRouting.getPath('routes/case.tsx', 'de'); // ❌ type error: 'de' is not a supported language i18nRouting.getPath('routes/cases.tsx', 'en'); // ❌ type error: no such route file ``` ## 为什么? A 类 `/:lang/...` 当只有语言段更改时,前缀就足够了。许多地点,包括政府驻地官方语文规则、需要 **完全翻译路径** 相反: `/en/dashboard` 财务报告和审定财务报表 `/fr/tableau-de-bord`进行中通过手工方式,每个语言登记每一页,保持路径同步,并重复绘图每一个链接、方向和语言切换。这个软件包保留了一个路线表,并构建了它以外的一切. ## 特征 - 🗺️ **一个真理的来源.** 每页声明一次,React路由器获得每个语言的一个路由. - 🔒 **完全输入, 不 `as const`。。。 .** 路由文件、身份证和语言被推断为文字结合。未知的文件, 排版文件,编译时拒绝不支持的语言. - 🔗 **链接和重定向.** `` 替换 ``,以及 `redirect()` 正在建设 `Response`s 用于装载器和动作,有参数,搜索和散列. - 🌐 **语言切换.** `` 链接到其它语言的当前页面并保留其 parms,搜索,和散列. - 🧭 **URL匹配 .** URL 使用 React Router 自身的排名映射回路由和语言, 所以静态片段总是击败动态的. - 🗣️ **语言谈判.** 语言来自 URL, 有可选的 `Accept-Language` 倒计时. - ✅ **失败的验证.** 重复的ID或文件,缺少翻译,以及启动时抛出的路由ID相撞. - 🪶 **小而可树.** 仅限无害环境管理, `sideEffects: false`,没有运行时间依赖超出它的同行,它的工作与回放18和19以及回放路由器7和8. ## 目录 - [安装](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-installation) - [快开始](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-quick-start) - [概念](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-concepts) - [食谱](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-recipes) - [API 参考](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-api-reference) - [行为细节](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-behavior-details) - [财务问题](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-faq) - [捐款](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-contributing) - [许可证](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-license) ## 安装 ```sh npm install @dts-stn/react-router-i18n-routes # or pnpm add @dts-stn/react-router-i18n-routes # or yarn add @dts-stn/react-router-i18n-routes ``` ### 所需资源 | 软件包 | 版本 | 需要时间 | | --- | --- | --- | | `react-router` | `^7.0.0 || ^8.0.0` | 所有的东西 | | `react` | `>=18.0.0` | [`@dts-stn/react-router-i18n-routes/react`](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-dts-stnreact-router-i18n-routesreact) | | `@react-router/dev` | `^7.0.0 || ^8.0.0` | [`@dts-stn/react-router-i18n-routes/route-config`](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-dts-stnreact-router-i18n-routesroute-config) | `react` 财务报告和审定财务报表 `@react-router/dev` 是可选的同伴。只有当您使用需要的切入点时才安装它们 . 软件包是 **仅限无害环境管理** 并且需要20号或以后的节点。类型推论依赖 [`const` 类型参数](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters), (中文(简体) ), 因此,需要TypeScript 5.0或更晚. ### 入境点 | 导入路径 | 目录 | 从 | | --- | --- | --- | | `@dts-stn/react-router-i18n-routes` | 路线定义, `createI18nRouting()`类型和错误 | 任何地方(客户端和服务器) | | `@dts-stn/react-router-i18n-routes/react` | 钩和连接组件 | 反应组件 | | `@dts-stn/react-router-i18n-routes/route-config` | 转换为 React 路由器路由配置 | `app/routes.ts` | ## 快开始 ### 1\. 确定路线将定义保留在自己的模块中这样 `app/routes.ts`,组件、装载器和动作都可以导入. ```ts // app/i18n-routes.ts import type { I18nLanguageOf, I18nRouteFileOf } from '@dts-stn/react-router-i18n-routes'; import { createI18nRouting, defineI18nRoutes } from '@dts-stn/react-router-i18n-routes'; export const i18nRoutes = defineI18nRoutes([ { id: 'HOME-0001', file: 'routes/index.tsx', paths: { en: '/en/', fr: '/fr/' }, }, { // A pathless layout route file: 'routes/protected/layout.tsx', children: [ { id: 'DASH-0001', file: 'routes/protected/dashboard.tsx', paths: { en: '/en/dashboard', fr: '/fr/tableau-de-bord' }, }, { id: 'CASE-0001', file: 'routes/protected/case.tsx', paths: { en: '/en/case/:caseId', fr: '/fr/dossier/:caseId' }, }, ], }, ]); export const i18nRouting = createI18nRouting(i18nRoutes); export type I18nRouteFile = I18nRouteFileOf; // 'routes/index.tsx' | 'routes/protected/dashboard.tsx' | 'routes/protected/case.tsx' export type Language = I18nLanguageOf; // 'en' | 'fr' ``` ### 2\. 用回放路由器登记路线 ```ts // app/routes.ts import type { RouteConfig } from '@react-router/dev/routes'; import { route } from '@react-router/dev/routes'; import { toRouteConfigEntries } from '@dts-stn/react-router-i18n-routes/route-config'; import { i18nRoutes } from './i18n-routes'; export default [ route('/api/health', 'routes/api/health.ts'), // non-translated routes work as usual ...toRouteConfigEntries(i18nRoutes), ] satisfies RouteConfig; ``` > \[大反应路由器的配置加载器不能解决路径的别名, 例如 `~/`,所以导入定义到 `app/routes.ts` 和相对路径. ### 3\. 连接、重新定向和切换语言 ```tsx import { I18nLanguageSwitchLink, I18nLink, useIsCurrentRoute, useIsNavigatingTo, useLanguage, } from '@dts-stn/react-router-i18n-routes/react'; import { i18nRouting } from '~/i18n-routes'; export function Navigation() { const { alternateLanguage } = useLanguage(i18nRouting); const isDashboard = useIsCurrentRoute(i18nRouting, 'routes/protected/dashboard.tsx'); const isLoadingCase = useIsNavigatingTo(i18nRouting, 'routes/protected/case.tsx', { params: { caseId: '42' } }); return ( ); } ``` ```ts // app/routes/protected/layout.tsx import { i18nRouting } from '~/i18n-routes'; import type { Route } from './+types/layout'; export function loader({ request }: Route.LoaderArgs) { if (!isSignedIn(request)) { const language = i18nRouting.getLanguage(request) ?? 'en'; throw i18nRouting.redirect('routes/index.tsx', language); } } ``` 就是这样。每个 `file`, (中文(简体) ), `language`,以及 `params` 以上值的键入 `app/i18n-routes.ts`。。。 . ## 概念 ### 页路由一个页面路由有一个 `id`,路径模块 `file`,以及每种语言的路径: ```ts { id: 'DASH-0001', file: 'routes/protected/dashboard.tsx', paths: { en: '/en/dashboard', fr: '/fr/tableau-de-bord' } } ``` - **`file`** 是路由模块,相对于应用程序目录,如: `app/routes.ts`。这也是 **查找密钥**数字 : 链接、重定向和钩子是指其文件中的一页. - **`paths`** 使用 React 路由器路径语法:活性区段( R)`:caseId`),可选部分(`:tab?`),和花板 (单位:千美元)`*`)所有作业. 每个页面路径必须声明 **同一套语言**。。。 . - **`id`** 必须是独一无二的。 React 路由器每个语言获得一条路由,并带有 id `${id}-${LANGUAGE}` (单位:千美元)`DASH-0001-EN`, (中文(简体) ), `DASH-0001-FR`) (中文(简体) ). 把这些身份传递给 `useRouteLoaderData()`,或用 [`getI18nRouteId()`](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-geti18nrouteidid-language)。。。 . ### 布局路线一个布局路线有一个 `file` 财务报告和审定财务报表 `children` 但是没有 `id` 或者说 `paths`。它会变成一个无路径回放路由器 `layout()` 路径让孩子度过难关 ``,用于认证卫士、共享铬和共享装载机布局可以筑巢. 排版不能成为链接目标, 因此将排版文件传递到 `getPath()` 是类型错误. ### 路径实例 `createI18nRouting(i18nRoutes)` 验证定义一次并返回 [`I18nRouting`](https://npmcn.com/package/%40dts-stn/react-router-i18n-routes/#readme-i18nrouting) 对象,每个查找和 URL 构建器。在模块级别创建并导入一次无论需要什么反应钩和组件把它当作他们的第一个论据或 `routing` 道具 (英语). ## 食谱 ### 设定 `` 在根布局中 ```tsx // app/root.tsx import type { ReactNode } from 'react'; import { Links, Meta, Scripts, ScrollRestoration } from 'react-router'; import { useCurrentLanguage } from '@dts-stn/react-router-i18n-routes/react'; import { i18nRouting } from '~/i18n-routes'; export function Layout({ children }: { children: ReactNode }) { const language = useCurrentLanguage(i18nRouting) ?? 'en'; return ( {children} ); } ``` ### 重定向 `/` 改为客家首选语言在 i18n 路由旁注册一个平面索引路由,并谈判语言 `Accept-Language` 页眉 : ```ts // app/routes.ts export default [index('routes/language-redirect.ts'), ...toRouteConfigEntries(i18nRoutes)] satisfies RouteConfig; ``` ```ts // app/routes/language-redirect.ts import { i18nRouting } from '~/i18n-routes'; import type { Route } from './+types/language-redirect'; export function loader({ request }: Route.LoaderArgs) { // The language of the URL path, then the Accept-Language header, then English const language = i18nRouting.getLanguage(request, { acceptLanguage: true }) ?? 'en'; return i18nRouting.redirect('routes/index.tsx', language); } ``` ### 用正确的语言显示404页 `getLanguage()` 当没有页面路由匹配时, 返回到第一个路径段, 所以一个覆盖所有路由仍然知道 `/fr/page-inexistante` 法语: ```ts // app/routes.ts export default [...toRouteConfigEntries(i18nRoutes), route('*', 'routes/not-found.tsx')] satisfies RouteConfig; ``` ```tsx // app/routes/not-found.tsx export default function NotFound() { const language = useCurrentLanguage(i18nRouting) ?? 'en'; return

{language === 'fr' ? 'Page introuvable' : 'Page not found'}

; } ``` ### 添加 `hreflang` sEO 的替代链接 ```tsx import { useLocation } from 'react-router'; import { i18nRouting } from '~/i18n-routes'; const ORIGIN = 'https://www.example.com'; export function AlternateLinks() { const { pathname } = useLocation(); return i18nRouting.languages.map((language) => { const path = i18nRouting.translatePath(pathname, language); return path && ; }); } ``` 渲染器 `` 内部 `` 内 `app/root.tsx`。。。 . ### 支持三种或三种以上语言 `alternateLanguage` 仅适用于双语应用程序。更多语言,列表 `alternateLanguages` 并传递每个 `I18nLanguageSwitchLink`数字 : ```tsx const LANGUAGE_NAMES = { en: 'English', fr: 'Français', es: 'Español' } as const; export function LanguageMenu() { const { alternateLanguages } = useLanguage(i18nRouting); return (

{LANGUAGE_NAMES[language]}

); } ``` `I18nLanguageSwitchLink` 套装 `lang` 财务报告和审定财务报表 `hrefLang` 编辑 ``,所以屏幕阅读器宣告每个语言名称对. ### 切换语言时重新装入文档如果每个文档都装入过一次翻译( 例如, 服务器上创建的 i18next 实例), 则通过 `reloadDocument` 这样切换语言就可以完成一个完整的页面负载 : ```tsx Français ``` ### 构建特定应用链接组件捆绑 `routing` 和默认样式 : ```tsx import type { I18nLinkProps } from '@dts-stn/react-router-i18n-routes/react'; import { I18nLink } from '@dts-stn/react-router-i18n-routes/react'; import type { i18nRoutes } from '~/i18n-routes'; import { i18nRouting } from '~/i18n-routes'; export function AppLink(props: Omit, 'routing'>) { return ; } ``` ```tsx Dashboard // ✅ Dashboard // ❌ type error ``` 用于非链接导航( U)`navigate()`, (中文(简体) ), `