翻译 Next.js Pages 应用

加载页面的翻译消息,通过 Pages 包装器渲染,并添加语言区域切换功能和备用链接。

Next.js Pages 路由会为每个请求解析语言区域。@lingo.dev/react-next 根据该语言区域提供 React 消息,让页面数据和翻译文本保持在一起。本示例用英语和法语渲染“关于”页面,即使翻译后的 JSONC 丢失了元数据,也能保留路由选择。

使用现有的 Pages 应用,并搭配 React 19。该软件包将 Next.js 13+ 和 React 18/19 声明为对等依赖,但当前的运行时提供器使用了 React 19 的上下文简写语法。它导出 /pages、/pages/client 和 /pages/server,不提供根导出或 App Router 入口。

配置语言区域和应用包装器 #

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

在现有的 next.config.mjs 中添加 i18n,保留其他设置:

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

在 pages/_app.tsx 中包装应用:

tsx
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";

function App({ Component, pageProps }: AppProps) {
  const { locale, defaultLocale } = useRouter();
  useEffect(() => {
    document.documentElement.lang = locale ?? defaultLocale ?? "en";
  }, [locale, defaultLocale]);
  return <Component {...pageProps} />;
}

export default withLingoApp(App);

包装器读取 pageProps.__lingoMessages,解析 Next 当前使用的语言区域,并提供 LingoProvider。URL 策略由 Next 自身的 i18n 设置决定;默认的英语路径通常不带前缀。

编写页面并加载消息 #

首先,将 消息目录加载中的 loadMatchedMessages 函数添加为 lib/catalog.ts。它会验证 JSONC 中的值是否为字符串,并将目标值与当前源键关联。

然后创建 pages/about.tsx:

tsx
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";

export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
  const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
  if (!["en", "fr"].includes(locale)) return { notFound: true };
  const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
  const target =
    locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
  const messages = loadMatchedMessages(source, target, (entry) => {
    const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
    return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
  });
  return { props: { __lingoMessages: messages } };
};

export default function About() {
  const l = useLingo();
  return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}

此判断函数会保留页面自身的条目和共享组件消息,并从源元数据中去除扩展名和旧版行号后缀。如果页面位于 src/pages/about.tsx,请同步更新导入路径和路由比较条件,使两者与页面位置一致。

自定义加载器在必需文件缺失或格式错误时会主动报错,防止构建过程悄悄用英语回退内容替代预期的法语消息目录。个别缺失的目标键不会被补入,而是使用正常的运行时回退机制。

提取、翻译并打开两个路由 #

在项目根目录运行 npx lingo extract --src pages --source-locale en。要新建 Lingo.dev 项目配置,请运行:

sh
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

对于已配置的项目,请保留现有绑定和其他文件选项。提取后,先按常规流程更新现有目标语言区域,获取并检查结果,再添加 fr 并补全翻译,期间不要更改源修订版本。消息目录加载介绍了配置步骤,添加语言说明了必须遵循的顺序。如果共享组件位于 pages 之外,请从包含所有消息调用的目录中提取,或将这些组件统一放在同一个 src 目录树下,并使用 --src src。

获取 locales/fr.jsonc 后,运行常规的 Next 开发或构建命令。打开 /about 和 /fr/about:前者使用英语源文本,后者使用同一标题键对应的法语目标文本。检查实际显示的法语文本,并故意留一个条目缺失,确认它能回退到源文本。

内置静态属性加载 #

如果每个语言区域文件都保留了正确的 @src 和 @orphan 元数据,就可以用服务端辅助函数替代上面的自定义 getStaticProps:

ts
import { withLingoProps } from "@lingo.dev/react-next/pages/server";

export const getStaticProps = withLingoProps({ route: "pages/about" });

withLingoProps({ route, handler? }) 从相对于工作目录的固定 locales/<locale>.jsonc 路径读取文件。它会过滤掉孤立条目和其他页面的条目,并将非页面来源的条目以及没有 @src 的条目视为共享内容。通用 JSONC 翻译会保留 @orphan 标记,但会移除 @src 注释,因此这类输出应使用上面的源键关联方案;辅助函数不会恢复元数据。

文件缺失时会返回 {},并在开发环境中发出警告;已有文件无效时则可能抛出异常。可选的异步处理函数可以添加属性,或返回重定向或未找到结果。成功的结果会保留 revalidate 等字段,并添加 __lingoMessages。其公开类型使用静态属性上下文和结果;不要假定所有服务端请求处理函数都遵循相同约定。CLI 的消息目录路径覆盖设置也不会改变此加载器使用的固定目录。

扩展动态静态路径 #

对于动态路由,服务端辅助函数会将每个参数条目扩展到 Next 配置的所有语言区域:

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

默认回退值为 "blocking",也支持 false 和 true。扩展操作不会翻译路径标识,也不会确认每个消息目录都包含该路由的消息。

切换语言并添加备用链接 #

在应用包装器下渲染语言切换器:

tsx
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";

export function Languages() {
  const switchLocale = useLocaleSwitch();
  return (
    <nav aria-label="Language">
      <LingoHead baseUrl="https://example.com" />
      <button onClick={() => switchLocale("en")}>English</button>
      <button onClick={() => switchLocale("fr")}>Français</button>
    </nav>
  );
}

将示例源地址替换为站点在生产环境中的绝对源地址。LingoHead 会为已配置的语言区域和 x-default 输出备用链接,并省略默认语言区域的前缀。它不会输出规范链接或 Open Graph 元数据。请检查生成的 URL 是否符合你的路由和查询参数策略。

切换回调会在 / 位置写入有效期为一年的 NEXT_LOCALE,并设置 SameSite=Lax,随后使用当前的 asPath 通过 Next 路由器导航。请按上面的方式传入已配置的语言区域;它不会对照支持列表验证任意输入。

设置初始文档属性 #

在 pages/_document.tsx 中设置初始属性,保留现有的文档自定义设置:

tsx
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";

export default class LocalizedDocument extends Document {
  render() {
    const locale = this.props.__NEXT_DATA__.locale ?? "en";
    return (
      <Html lang={locale} dir={createLingo(locale).direction}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

withLingoApp 会在语言区域更改后设置文本方向,并为初始渲染输出内联 RTL 脚本,但不会设置 lang。上面的 _app 副作用会在导航时更新 lang;自定义文档则提供这两个属性的初始值。严格的内容安全策略可能阻止包装器的内联脚本,而包装器不提供 nonce 选项。自定义文档无需依赖该脚本即可设置初始文本方向。也请检查应用在导航时的脚本策略。

最后,使用相同的消息目录和显式时间输入检查 水合。确认切换语言时,消息和文档属性会同步更新。