18ways 博客

如何为 Next.js 应用添加多种语言

如何在不伤害 SEO、也不从头重建的情况下,为现有的 Next.js 应用添加多语言 i18n 和本地化。

I18n(国际化)、l10n(本地化)、多语言支持……不管你怎么叫它,最终你都需要更新你的 Next.js 应用,让它支持一种以上的语言。

难点不在于翻译一句话。而在于把多种语言加入一个真实的 Next.js 应用里,同时不破坏 SEO、不把代码库搞得一团乱,也不给自己埋下维护难题。

If you want to jump straight to the code, check out the 18ways-next GitHub examples .

先把基础设施搭好

首先,我们需要安装所需的软件包。我们会配置 18ways 的库,但如果你的项目比较简单,只包含静态内容,那么 i18next 之类的工具也很好用。

bash
npm install @18ways/next @18ways/react

创建你的配置文件:

js
// 18ways.config.js
module.exports = {
  apiKey: 'pk_dummy_demo_token',
  baseLocale: 'en-GB',
  router: 'app', // 'app', or 'path' depending on which Next.js router you are using
};

把你的 Next.js 配置包起来:

js
// next.config.js
const { withWays } = require('@18ways/next/config');
 
const nextConfig = {
  /*
   * your normal Next.js config here
   */ 
};
 
module.exports = withWays(nextConfig);

添加一个根代理,这样 / 就能重定向到正确的语言区域:

js
// proxy.js
export { default, config } from '@18ways/next/proxy';

然后添加一个本地化布局:

jsx
// app/layout.jsx
import './styles.css';
import { WaysRoot } from '@18ways/next/server';
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="next-demo-body">
        <WaysRoot>{children}</WaysRoot>
      </body>
    </html>
  );
}

好了,完成!你现在拥有:

翻译你的第一个页面

现在你可以翻译第一页了。像 i18next 这样的工具会要求你把所有文本拆成翻译键,然后在代码中引用它们。具体会是什么样,取决于你选择的库。

如果你在使用 18ways,那么只需把想要翻译的文本包在 <T> 组件里即可:

jsx
// src/components/MyExampleComponent.jsx
import { useT, T } from '@18ways/react';
 
export default function MyExampleComponent() {
  const t = useT();
 
  return (
    <div>
      <T>Hello world!</T>
      <img
        src="https://example.com/image.png"
        alt={t('Example image')}
      />
    </div>
  );
}

你大概会希望允许用户切换自己的语言选择:

jsx
// src/components/Footer.jsx
import { T, LanguageSwitcher } from '@18ways/react';
 
export default function Footer() {
  return (
    <footer>
      <T>My footer content</T>
      <LanguageSwitcher />
    </footer>
  );
}

注意这些坑

一旦底层配置到位,这些项目通常会在几个地方出问题。

服务端渲染

服务端渲染(SSR)能让你的 Next.js 应用在服务端预渲染 HTML。这对 SEO 至关重要,也能避免用户看到内容闪烁不对或语言错误的情况。

如果你用的是像 i18next 这样的库,你需要非常小心,确保翻译内容在服务端渲染时已经被加载并填充进去。你可以通过查看页面的 view-source: 来测试这一点,例如 view-source:http://localhost:3000/。在生产环境里也要检查一下,确保它在生产构建中同样可用。

如果你用的是 18ways,就不用担心这个。它都会帮你处理好。

翻译键

如果你在使用 18ways,就完全不用担心这个。18ways 不需要翻译键,你可以像平常一样把文本原样放在原处。

许多 i18n 系统都要求你把代码拆成一个个翻译键。为这些键命名时一定要小心。

糟糕的键很含糊:

js
// bad-keys.en-GB.js
module.exports = {
  title: 'Continue',
  button: 'Pay now',
  label: 'Home',
};

这些键几乎无法让译者和开发者知道文本会出现在哪里。

更好的键会包含上下文:

js
// better-keys.en-GB.js
module.exports = {
  'checkout.payment.primaryButton': 'Pay now',
  'checkout.payment.stepTitle': 'Complete your payment',
  'account.sidebar.homeLink': 'Home',
};

也要避免动态生成键:

js
// bad-dynamic-keys.js
const key = `checkout.${status}.${buttonType}`;
const translatedText = t(key);

这会破坏那些试图让翻译键不那么难受的 IDE 工具。它也会让查找和清理旧翻译键变得极其困难。

js
// better-dynamic-keys.js
const keyMap = {
  success: {
    primary: t('checkout.success.primary'),
    default: t('checkout.success.default'),
  },
  error: {
    primary: t('checkout.error.primary'),
    default: t('checkout.error.default'),
  },
};
 
const translatedText = keyMap[status][buttonType];

这虽然不够 DRY,但却是避免翻译键变得难以管理的最佳方式。

更好的做法是使用像 18ways 这样的工具,那样你根本不需要翻译键:

jsx
// app/[lang]/checkout/page.jsx
<T>Pay now</T>

区域设置检测

区域设置检测指的是:在用户明确切换之前,先决定用户应该看到哪种语言。

这通常需要以下几种组合:

在普通的 Next.js 中间件里,这通常会像这样:

js
// middleware.js
 
/**
 * You don't need any of this if you're using 18ways 
 */
 
import { NextResponse } from 'next/server';
 
const acceptedLocales = ['en-GB', 'fr-FR'];
 
export function middleware(request) {
  const savedLocale =
    request.cookies.get('preferred-locale')?.value;
  const browserLocale =
    request.headers
      .get('accept-language')
      ?.split(',')[0] || 'en-GB';
 
  const locale = acceptedLocales.includes(savedLocale)
    ? savedLocale
    : acceptedLocales.includes(browserLocale)
      ? browserLocale
      : 'en-GB';
 
  if (request.nextUrl.pathname === '/') {
    return NextResponse.redirect(
      new URL(`/${locale}`, request.url)
    );
  }
 
  return NextResponse.next();
}

有些库提供了辅助功能,让这件事更容易一些,但程度各不相同。使用 18ways 时,初始检测和重定向层都会为你处理好。

日期和特定区域设置的基础类型

不同地区对日期、数字和货币的格式各不相同。

例如:

在原生 JavaScript 里,你需要用 Intl 自己处理这些:

js
// formatting-dates-and-currency.js
const myLocale = getCurrentLocale(); // depends on your lib
 
const someTimestamp = new Date('2026-04-13T09:00:00Z');
const dateLabel = new Intl.DateTimeFormat('fr-FR', {
  dateStyle: 'long',
}).format(someTimestamp);
 
const someMoney = {
  amount: 1999,
  currency: 'EUR',
};
const moneyLabel = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: someMoney.currency,
}).format(someMoney.amount);
 
const translatedText = t(
  'my.translation.key',
  { dateLabel, moneyLabel }
);

如果你使用 18ways,这些都会替你处理好:

jsx
const someTimestamp = new Date('2026-04-13T09:00:00Z');
const someMoney = {
  amount: 1999,
  currency: 'EUR',
};
 
<T>My text with {{ someTimestamp }} and {{ someMoney }}</T>

拼接字符串

不要通过拼接片段来构建翻译后的界面:

jsx
// bad-string-joining.jsx
const clickHereText = t('click.here');
const toGetStartedText = t('to.get.started')
<p><a href="#">{clickHereText}</a> {toGetStartedText}.</p>

这在多种语言里会出问题。

你可能会用英语说“👉👉点击这里👈👈开始”,但在法语中,更自然的说法是“Pour commencer,👉👉cliquez ici👈👈”。像日语这样的语言,甚至需要在前后都加上词语,比如“始めるには👉👉こちら👈👈をクリックしてください”。

句子结构可能会变化,所以把它拆成碎片会让翻译难得多。

完整的句子更容易翻译,因为译者可以自然地调整词序,并把意思作为一个完整单元来理解。

如果你正在翻译这样的 JSX:

jsx
// rich-text-message.jsx
<p>
  Something <strong>that we want to be bold</strong>
</p>

你需要查阅所用 i18n 库的文档,了解如何处理这一点,因为不同库的处理方式差异很大。

如果你使用的是 18ways,你只需像平常一样直接翻译整个 JSX 块。

jsx
// rich-text-message.jsx
<p>
  <T>Something <strong>that we want to be bold</strong></T>
</p>

变量

变量让你既能保留完整句子,又能在运行时插入值。

大多数 i18n 库都以某种方式支持这一点。使用 18ways:

jsx
// app/[lang]/page.jsx
<T>Hello {{ name: 'Ada' }}</T>

这种模式非常适合:

句子依然通顺,值也依然明确。

如果你还需要把变量本身也翻译掉,记得把它包进 t(...) 里:

jsx
const animal = t('dog');
<T>Favourite animal: {{ animal }}</T>

复数形式

复数规则因语言而异。英语只有一种复数形式(1 year、2 years 等)。波兰语有多种复数形式(1 rok、2 lata、5 lat)。日语则根本没有复数形式(1 年、2 年、3 年)。

大多数 i18n 库都允许你指定类似 ICU 的语法来处理复数:

jsx
// app/[lang]/page.jsx
<T>
  {{
    unreadCount,
    format:
      'plural, =0{No unread messages} =1{One unread message} other{{unreadCount} unread messages}',
  }}
</T>

上面的做法在 18ways 中可行,但在大多数情况下,你也可以直接这样做:

jsx
// app/[lang]/page.jsx
<T>{{ unreadCount }} unread messages</T>

18ways 会帮你处理复数形式!

立即开始

给 Next.js 应用添加多种语言,不必变成一次重写工程。

如果你没有使用像 18ways 这样的解决方案——请确保路由和 SSR 配置正确,然后继续把文案迁移到翻译键,同时务必避开常见的 i18n 陷阱。

如果你正在使用 18ways,那么这些都会为你自动处理,你只需要开始把文本用 <T> 包起来就行!