如何在使用 App Router 的 Next.js 应用程序中实现国际化
通过国际化 (i18n) 使您的 React 应用更具可访问性并开拓新市场。
随着世界日益全球化，网络开发者构建能够满足来自不同国家和文化的用户的应用变得愈发重要。实现这一目标的关键方式之一是通过国际化（i18n），它允许您将应用适配到不同的语言、货币和日期格式。
在本文中，我们将探讨如何为您的 React Next.js 应用添加国际化，并实现服务端渲染。 TL;DR: 在此查看完整示例。
本指南适用于使用 App Router 的 Next.js 应用。
如果您使用 Pages Router，请改为参阅此指南。
第 1 步： 安装一个 i18n 库
要在 Next.js 应用中实现国际化，我们首先会选择一个 i18n 库。有几个流行的库可用，包括 next-intl. 但在本示例中，我们将使用 TacoTranslate.
TacoTranslate 使用最先进的 AI 自动将你的字符串翻译成任意语言，并让你摆脱繁琐的 JSON 文件管理。
让我们在终端中使用 npm 安装它：
npm install tacotranslate第2步： 创建一个免费的 TacoTranslate 账户
既然您已经安装了该模块，现在是时候创建您的 TacoTranslate 帐户、翻译项目和相关的 API 密钥了。点击此处创建帐户。 它是免费的，且无需您提供信用卡信息。
在 TacoTranslate 应用程序的 UI 中，创建一个项目，并转到其 API 密钥选项卡。创建一个 read 密钥，以及一个 read/write 密钥。我们会将它们保存为环境变量。 read 密钥就是我们所说的 public，而 read/write 密钥是 secret。例如，你可以将它们添加到项目根目录下的 .env 文件中。
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010务必不要将机密的 read/write API 密钥泄露到客户端的生产环境中。
我们还将添加另外两个环境变量： TACOTRANSLATE_DEFAULT_LOCALE 和 TACOTRANSLATE_ORIGIN.
TACOTRANSLATE_DEFAULT_LOCALE: 默认的回退语言代码。在此示例中，我们将其设置为en（英语）。TACOTRANSLATE_ORIGIN: 存储字符串的“文件夹”，例如您网站的 URL。 在此处阅读有关来源的更多信息。
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com第 3 步： 设置 TacoTranslate
要将 TacoTranslate 集成到您的应用程序中，您需要使用前面提到的 API 密钥创建一个客户端。例如，创建一个名为 /tacotranslate-client.js 的文件。
const {default: createTacoTranslateClient} = require('tacotranslate');
const tacoTranslate = createTacoTranslateClient({
apiKey:
process.env.TACOTRANSLATE_SECRET_API_KEY ??
process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
process.env.TACOTRANSLATE_API_KEY,
projectLocale:
process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;我们将很快自动定义 TACOTRANSLATE_API_KEY 和 TACOTRANSLATE_PROJECT_LOCALE。
将客户端创建在单独的文件中，便于以后重复使用。 getLocales 只是一个带有一些内置错误处理的工具函数。现在，创建一个名为 /app/[locale]/tacotranslate.tsx 的文件，我们将在那里实现 TacoTranslate 提供者。
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}请注意 'use client';，这表明这是一个客户端组件。
现在上下文提供器已准备就绪，创建一个名为 /app/[locale]/layout.tsx 的文件，作为我们应用程序的根布局。请注意，该路径包含一个使用 Dynamic Routes 的文件夹，其中 [locale] 是动态参数。
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}首先要注意的是，我们正在使用我们的 Dynamic Route 参数 [locale] 来获取该语言的翻译。此外，generateStaticParams 确保您为项目启用的所有区域设置代码都已预渲染。
现在，让我们构建第一个页面！创建一个名为 /app/[locale]/page.tsx 的文件。
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}注意 revalidate 变量，它告诉 Next.js 在 60 秒后重新构建该页面，并保持你的翻译内容为最新状态。
第 4 步： 实现服务器端渲染
TacoTranslate 支持服务器端渲染。这大大提升了用户体验，因为它可以立即显示翻译后的内容，而不是先短暂展示未翻译的内容。除此之外，我们可以省去客户端的网络请求，因为我们已经拥有用户正在查看页面所需的翻译。
要设置服务器端渲染，请创建或修改 /next.config.js:
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
client: tacoTranslateClient,
isProduction:
process.env.TACOTRANSLATE_ENV === 'production' ||
process.env.VERCEL_ENV === 'production' ||
(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
process.env.NODE_ENV === 'production'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};修改 isProduction 检查以适应你的设置。如果 true，TacoTranslate 会展示公共 API 密钥。如果我们处于本地、测试或预发布环境（isProduction is false)，我们将使用机密的 read/write API 密钥，以确保新的字符串被发送进行翻译。
为了确保路由和重定向按预期工作，我们需要创建一个名为 /middleware.ts 的文件。使用 Middleware, 我们可以将用户重定向到以其首选语言呈现的页面。
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}请确保按照 Next.js 中间件文档 的要求设置 matcher.
在客户端，您可以修改 locale cookie 以更改用户的首选语言。请参阅 完整示例代码 以了解如何操作！
第5步： 部署并测试！
完成了！当你将任何字符串添加到 Translate 组件时，你的 React 应用将会自动被翻译。请注意，只有在 API 密钥上具有 read/write 权限的环境才能创建新的字符串以进行翻译。我们建议设置一个封闭且安全的预发布（staging）环境，在那里使用类似的 API 密钥测试你的生产应用，并在上线前添加新的字符串。这将防止任何人 任何人 窃取你的秘密 API 密钥，并通过添加新的无关字符串可能使你的翻译项目膨胀。
Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.
TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!