翻译 Next.js App Router 应用
为每个页面加上语言区域前缀,重定向无前缀路径,并使用 @lingo.dev/react-next 渲染已翻译的服务器组件和客户端组件。
在 App Router 中,每个语言区域都有自己的 URL 前缀,源语言区域也不例外:读者访问的是 /en/pricing 和 /de/pricing。@lingo.dev/react-next 从 app/[locale] 路由段读取语言区域,在服务器端加载该语言区域的翻译目录,并为服务器组件和客户端组件提供相同的消息。本指南将为一个英语应用添加德语和法语支持。
请使用 Next.js 16 或更高版本以及 React 19;这些入口通过 next/root-params 读取语言区域。安装以下包:
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest定义语言区域 #
在 app/ 旁边创建 i18n.ts(如果应用使用 src/,则创建 src/i18n.ts):
import { createLocaleRouter } from "@lingo.dev/locale-router";
export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });
export const localePath = (pathname: string, locale: string) =>
locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);在 .lingo/config.json 中列出语言区域,并将源语言区域设为 defaultLocale。exclude 用于指定无需添加前缀的首个路径段,例如 app/api/ 下的路由处理程序。不要传入 slugs:每个语言区域的 URL 段必须是其小写标签(例如 pt-BR 对应 /pt-br),因为 getLingo() 仅凭该路径段来确定语言区域。如果使用自定义短标识,提供程序会抛出错误,并在错误信息中指明该标识。代理、服务器组件和客户端组件都会导入此文件,因此请勿在其中添加其他导入。
重定向无前缀路径 #
在 app/ 旁边创建 proxy.ts:
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";
export const proxy = lingoProxy(locales);
export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };lingoProxy(locales) 处理两类请求:
| 请求 | 响应 |
|---|---|
首个路径段以短标识以外的形式指定语言区域,例如 /DE/about、/de-AT 或 /de_DE | 301 到规范地址。 |
不带语言区域的本地化路径,例如 /about | 307 到根据 Accept-Language 协商出的语言区域,并附带 Cache-Control: private, no-store 和 Vary: Accept-Language。 |
| 其他所有情况 | undefined。 |
重定向会保留查询字符串以及应用的 basePath。Next.js 在构建时读取匹配器,因此请保持其为字面量,并确保其 api 与 exclude 同步。如果应用已有代理,请先调用 lingoProxy,在其返回 undefined 时再继续执行你自己的逻辑。middleware.ts 就是该文件的旧名称;请将其重命名为 proxy.ts,并将其中的函数重命名为 proxy。
将路由移至语言区域目录下 #
将根布局和所有页面向下移动一层,放入 app/[locale]/。app/[locale]/layout.tsx 将成为根布局,此后不再需要 app/layout.tsx。app/api/ 下的路由处理程序、globals.css、图标、robots.ts 和 sitemap.ts 保持原位不动。从 next.config 中移除所有 i18n 键,因为 App Router 不会读取它。
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";
export function generateStaticParams() {
return lingoStaticParams(locales);
}
export default async function RootLayout({ children }: { children: ReactNode }) {
const l = await getLingo();
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoAppProvider locales={locales}>{children}</LingoAppProvider>
</body>
</html>
);
}lingoStaticParams 为每个语言区域返回一个 { locale },因此构建时每个页面都会针对每个语言区域预渲染一次。对于不在列表中的语言区域,LingoAppProvider 会返回 404。不要添加 export const dynamicParams = false:启用 cacheComponents 时,Next.js 会拒绝该设置。
翻译服务器组件和客户端组件 #
服务器组件、页面、布局和 generateMetadata 调用 @lingo.dev/react-next/app/server 中的 await getLingo()。客户端组件调用 @lingo.dev/react 中的 useLingo(),由 LingoAppProvider 为它们提供语言区域和翻译目录。两者都无需逐层传递语言区域。
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";
export default async function Home() {
const l = await getLingo();
return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}服务器组件可以从其服务器父组件接收 l 作为属性,但切勿将 l 传给客户端组件:函数无法从服务器传递到客户端。在 app/[locale]/ 之外调用 getLingo() 会因找不到 [locale] 路径段而抛出错误。
添加元数据 #
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
export async function generateMetadata() {
const l = await getLingo();
return {
title: l.text("Pricing", { context: "Title of the pricing page" }),
...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
};
}lingoMetadata({ locales, pathname, origin, ogLocale? }) 返回 alternates.canonical、每个语言区域对应的 alternates.languages 以及 x-default,还有 openGraph.url 和 openGraph.locale。传入的页面路径不应包含语言区域前缀、查询字符串或哈希片段;动态路由可根据其参数构建该路径。请将示例源地址替换为你网站的源地址。语言区域 URL 策略介绍了用于构建这些值的 lingoHead,以及 ogLocale 覆盖设置。
添加链接与切换语言 #
使用 i18n.ts 中的 localePath("/pricing", l.locale) 为每个内部链接加上前缀。l.locale 是普通字符串,因此需要先由 localePath 将其收窄为路由器支持的某个语言区域,再由 locales.prefix 添加前缀。不带前缀的链接会被代理拦截,并重定向到浏览器的语言,而非当前页面的语言。redirect()、router.push() 以及指定路径的表单操作同样适用此规则。
"use client";
import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";
export function LocaleSwitcher() {
const options = useLocaleSwitch(locales);
return (
<nav aria-label="Language">
{options.map((option) => (
<Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
{option.label}
</Link>
))}
</nav>
);
}useLocaleSwitch(locales) 为每个语言区域返回一个 { locale, label, href, current }:包括当前页面在该语言区域下的版本、以该语言书写的语言名称,以及它是否为当前语言区域。查询字符串会在水合完成后添加,因此渲染语言切换器的页面依然可以保持静态。点击链接会重新渲染布局,从而加载新语言区域的翻译目录。
提取并加载翻译目录 #
服务器使用 fs,从运行 next 的文件夹中读取 locales/<locale>.jsonc,因此请将 i18n.messagesPath 保持为默认值 locales。它会丢弃孤立条目,并在每次请求时重新读取文件,因此 next dev 会在下一次请求时就提供编辑后的翻译目录。文件缺失时会使用空翻译目录,并在开发环境中给出警告;文件格式错误或存在非字符串值时,则会抛出指明文件名的错误。在生产环境中,源语言区域不会向浏览器发送翻译目录,因为其文本本身就是回退内容。
如果 app/ 位于项目根目录且没有 src/ 文件夹,请在 .lingo/config.json 中设置 "i18n": { "src": "." },让提取过程扫描 app/ 和 components/。提取时会跳过 node_modules 以及 .next 等以点开头的文件夹。新建配置的示例如下:
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait请在 init 之后再设置 i18n.src,因为前者会重写 i18n 部分。在单体仓库中,.lingo/config.json 位于仓库根目录,其路径也从根目录起算,因此 messagesPath 应为应用文件夹加上 locales,例如 apps/web/locales;详见 CLI 配置中按名称列出应用的 i18n 映射。服务器仍会从应用自身的文件夹中读取 locales/。
执行 next build 和 next start 后,打开 /,确认它会重定向到某个语言区域;然后打开 /de,检查 HTML 中是否为德语文本。
运行时 #
预渲染页面可在任何托管环境中运行。按需渲染的页面需要从磁盘读取翻译目录,因此必须使用 Node.js 运行时;Cloudflare Workers 和 Edge 运行时无法读取这些文件。
导出项 #
| 入口 | 导出项 |
|---|---|
@lingo.dev/react-next/app/server | getLingo()、LingoAppProvider、lingoMetadata(options)、lingoStaticParams(locales)。 |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) 和 LocaleOption 类型。 |
@lingo.dev/react-next/app/proxy | lingoProxy(locales)。 |
安装该包后,编程智能体即可按照 lingo agent-guide react-next-app 完成设置,也可按照 lingo agent-guide react-next-migrate 从 next-intl 迁移。详见使用编程智能体进行设置。