语言区域 URL 策略
定义语言区域前缀、协商语言偏好,并生成重定向和替代路径决策,无需绑定特定框架。
本地化 URL 需要一套一致的策略:支持哪些语言、如何在路径中表示这些语言,以及无前缀路径应将读者引导到哪里。@lingo.dev/locale-router 通过原生 Intl 做出这些决策。服务器负责发送重定向,应用负责加载选定的翻译目录。
定义支持的语言区域和路径别名 #
npm install @lingo.dev/locale-router@0.2.1import { createLocaleRouter } from "@lingo.dev/locale-router";
const locales = createLocaleRouter(["en", "de", "pt-BR"] as const, {
defaultLocale: "en",
exclude: ["api", "assets"],
slugs: { "pt-BR": "br" },
});语言区域 pt-BR 标识巴西葡萄牙语;br 只是它在 URL 中的路径别名。未指定覆盖值时,路径别名默认使用小写的语言区域标签。请使用有效标签,从支持的语言区域中选择默认值,并确保小写路径别名各不相同。构造函数不会检查所有配置冲突。
createLocaleRouter<L extends string>(locales, options) 接受一个只读的语言区域数组,并返回 LocaleRouter<L>。defaultLocale 为必填项;exclude 和 slugs 为可选项。排除规则按路径名的首个分段进行匹配。如果首个分段以 _ 开头或包含 .,也会被排除,确保内部路径和文件路径不参与本地化。
为无前缀 URL 生成重定向决策 #
const target = locales.redirect(
new URL("https://example.com/account?tab=billing#details"),
"de-CH,de;q=0.8,en;q=0.5",
);
if (target) {
console.log(target.href);
}这会生成 https://example.com/de/account?tab=billing#details。瑞士德语偏好会匹配到受支持的德语。该辅助函数返回一个新 URL,不会发送 HTTP 响应,也不会设置 Cookie。服务器负责选择状态码并发送重定向地址。实际的 HTTP 请求不包含浏览器中的片段标识符,但 URL 辅助函数会保留传入的片段标识符。
如果要优先采用已保存的偏好,请通过 toLocale 验证其语言区域标签,再将结果作为 redirect 的可选第三个参数传入。不要将任意字符串当作受支持的语言区域传入。
检查和构建路径 #
| 使用上述策略调用 | 结果 |
|---|---|
locales.toLocale("pt_BR") | "pt-BR"。精确匹配语言区域之前,会先对下划线进行规范化处理。 |
locales.toLocale("br") | undefined。URL 路径别名不等同于语言区域标签。 |
locales.split("/br/account") | { locale: "pt-BR", rest: "/account" }。 |
locales.isLocalized("/account") | true。这表示路径可以进行本地化,并不表示已添加前缀。 |
locales.prefix("/account", "de") | "/de/account"。 |
locales.prefix("/", "de") | "/de"。 |
locales.prefix("/api/status", "de") | "/api/status",保持不变。 |
locales.canonical("/DE/account") | "/de/account"。 |
如果无法识别首个分段中的路径别名,split 会返回 undefined。请向路径方法传入路径名,而不是包含查询参数或片段标识符的字符串。
prefix 和 alternates 要求传入无前缀路径。要将 /br/account 改为德语,请先拆分路径,再传入 rest:
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;结果为 /de/account。直接为原始路径添加前缀,可能会多出一个语言区域分段。
协商语言偏好 #
negotiate(acceptLanguage: string | null): L 会按质量权重对权重大于零的偏好排序,并依次尝试匹配。对于每个偏好,它会先尝试精确匹配语言区域,再尝试匹配受支持的语言。如果多个受支持的地区性语言区域使用同一种语言,其配置顺序可能会决定语言回退结果。
无效的质量权重值和权重为零的偏好会被丢弃。无效标签不会匹配,通配符也不会取代默认策略。如果没有匹配的偏好,该方法会返回 defaultLocale。这里的语言选择依据是明确指定的偏好,而不是地理位置。
将规范化与无前缀路径重定向分开处理 #
如果首个分段类似语言区域标签且可被识别,canonical(pathname): string | undefined 会建议使用规范化的路径别名。它并不是通用的规范 URL 生成器。对于已有前缀的路径、被排除的路径,以及 canonical 能给出修正建议的路径,redirect 会返回 undefined。
如果应用需要 /DE/account 规范化,请单独处理。服务器可以在请求 URL 的副本上替换路径名并保留查询部分,然后发送所选的重定向。TanStack 的中间件会处理无前缀路径的语言协商,但不会额外执行这一步独立的规范化处理。
生成其他语言的 URL #
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
hrefLang: locale,
href: new URL(pathname, "https://example.com").href,
}));请使用站点可信的源地址,而不是示例中的地址。alternates 会为每个受支持的语言区域返回一个 { locale, pathname },并额外返回指向默认语言区域路径的 x-default。pt-BR 语言条目使用 /br/account;在此策略下,默认英语条目使用 /en/account。
调用方将这些结果渲染为元数据。TanStack 页面头部元数据会在此策略的基础上添加规范 URL 和 Open Graph 字段。Next Pages 适配器遵循 Next 的默认语言区域 URL 策略,与此处的策略不同,因此不要混用两者的输出。