如何在使用 Pages Router 的 Next.js 应用中实现国际化
通过国际化 (i18n),让你的 React 应用更具可访问性并开拓新市场。
随着世界日益全球化,网络开发者构建能够满足来自不同国家和文化的用户需求的应用变得越来越重要。实现这一目标的关键方法之一是国际化 (i18n),它使您能够将应用适配为不同的语言、货币和日期格式。
在本教程中,我们将探讨如何为你的 React Next.js 应用添加国际化,并实现服务器端渲染。 TL;DR: 在此查看完整示例。
本指南适用于使用 Pages Router 的 Next.js 应用。
如果您使用 App Router,请参阅此指南。
第 1 步:安装一个 i18n 库
要在你的 Next.js 应用中实现国际化,我们首先要选择一个 i18n 库。有几个流行的库可供选择,包括 next-intl. 不过在本示例中,我们将使用 TacoTranslate.
TacoTranslate 使用最先进的 AI 自动将你的字符串翻译成任意语言,免去了你对 JSON 文件的繁琐管理。
让我们在终端中使用 npm 来安装它:
npm install tacotranslate
第 2 步: 创建一个免费的 TacoTranslate 账户
现在您已经安装了该模块,是时候创建您的 TacoTranslate 帐户、翻译项目以及相关的 API 密钥。在此创建帐户。 这是免费的,且无需您添加信用卡。
在 TacoTranslate 应用的 UI 中,创建一个项目,然后导航到其 API keys 选项卡。创建一个 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。在此处了解有关 origins 的更多信息。
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_DEFAULT_LOCALE ?? '',
});
module.exports = tacoTranslate;
我们将很快自动定义 TACOTRANSLATE_API_KEY
。
将客户端创建在单独的文件中可以让以后更容易再次使用。现在,使用自定义的 /pages/_app.tsx
,我们将添加 TacoTranslate
提供程序。
import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';
type PageProperties = {
origin: Origin;
locale: Locale;
locales: Locale[];
localizations: Localizations;
};
export default function App({Component, pageProps}: AppProps<PageProperties>) {
const {origin, locale, locales, localizations} = pageProps;
return (
<TacoTranslate
client={tacoTranslate}
origin={origin}
locale={locale}
localizations={localizations}
>
<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
<Component {...pageProps} />
</TacoTranslate>
);
}
如果您已经有自定义 pageProps
和 _app.tsx
,请将上述属性和代码添加到定义中。
第4步: 实现服务器端渲染
TacoTranslate 支持对翻译内容进行服务端渲染。这能显著提升用户体验,能够立即显示翻译后的内容,避免先出现未翻译内容的闪烁。此外,由于我们已经拥有所需的所有翻译,客户端可以跳过网络请求。
我们将从创建或修改 /next.config.js
开始。
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = {};
return withTacoTranslate(config, {
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'),
});
};
根据你的设置修改 isProduction
检查。若 true
,TacoTranslate 将使用公共 API 密钥;如果我们处于本地、测试或预发布环境(isProduction
is false
),我们将使用秘密的 read/write
API 密钥,以确保新字符串被发送进行翻译。
到目前为止,我们只是在 Next.js 应用中设置了支持的语言列表。接下来我们要为你所有的页面获取翻译。为此,你可以根据需要使用 getTacoTranslateStaticProps
或 getTacoTranslateServerSideProps
。
这些函数接受三个参数:一个 Next.js Static Props Context 对象、TacoTranslate 的配置,以及可选的 Next.js 属性。注意 revalidate
在 getTacoTranslateStaticProps
上默认设置为 60,以便你的翻译保持最新。
要在页面中使用任一函数,假设你有一个类似 /pages/hello-world.tsx
的页面文件。
import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';
export async function getStaticProps(context) {
return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}
export default function Page() {
return <Translate string="Hello, world!"/>;
}
现在你应该可以使用 Translate
组件在你所有的 React 组件中翻译字符串了。
import {Translate} from 'tacotranslate/react';
function Component() {
return <Translate string="Hello, world!"/>
}
第 5 步: 部署并测试!
我们完成了!当你将任何字符串添加到 Translate
组件时,你的 React 应用将会自动被翻译。请注意,只有在 API 密钥具有 read/write
权限的环境中,才可以创建新的字符串以供翻译。我们建议准备一个受限且安全的预发布(staging)环境,在那里使用具有该权限的 API 密钥测试你的生产应用,并在上线前添加新字符串。这将防止任何人窃取你的秘密 API 密钥,并避免有人添加新的、不相关的字符串从而可能使你的翻译项目膨胀。
请务必在我们的 GitHub 页面上查看完整示例。在那里,您还可以找到一个使用 App Router 的示例!如果遇到任何问题,欢迎随时 联系我们,我们会非常乐意提供帮助。
TacoTranslate 可让您快速将 React 应用在超过 75 种语言之间实现自动本地化。 立即开始使用!