如何将 Better i18n 与 Next.js 集成？
`@better-i18n/next` 包与 Next.js App Router 集成，并添加了支持 ISR 的 CDN 消息获取功能。按照此指南完成配置。
8 分钟阅读中级
@better-i18n/next 包与 Next.js App Router 集成，并在底层使用 next-intl。它添加了支持 ISR 的 CDN 消息获取功能。
安装
bun add @better-i18n/next next-intl
第一步：创建 i18n 配置
创建 src/i18n.ts：
import { createI18n } from '@better-i18n/next';
export const i18n = createI18n({
project: 'acme/dashboard',
defaultLocale: 'en',
localePrefix: 'as-needed', // 'always' | 'as-needed' | 'never'
manifestRevalidateSeconds: 3600, // ISR：每小时重新验证语言列表
messagesRevalidateSeconds: 30, // ISR：每 30 秒重新验证消息
});
Locale 前缀选项
| 选项 | 默认 locale URL | 其他 locale URL |
|---|---|---|
as-needed |
/about |
/tr/about |
always |
/en/about |
/tr/about |
never |
/about |
/about（从 cookie/请求头获取 locale） |
第二步：设置请求配置
创建 src/i18n/request.ts：
import { i18n } from '@/i18n';
export default i18n.requestConfig;
这告诉 next-intl 如何为每个请求加载消息。底层从 Better i18n CDN 获取，带 ISR 缓存。
第三步：添加 Middleware
创建 src/middleware.ts：
import { i18n } from '@/i18n';
export default i18n.betterMiddleware();
export const config = {
matcher: ['/((?!api|_next|.*\\..*).*)'],
};
Middleware：
- 从
Accept-Language头检测用户首选语言 - 重定向到对应的语言前缀
- 设置
x-better-locale头供下游使用
第四步：添加 Provider
在根 layout（src/app/[locale]/layout.tsx）中：
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';
export default async function LocaleLayout({
children,
params: { locale },
}) {
const messages = await getMessages();
return (
<html lang={locale}>
<body>
<NextIntlClientProvider messages={messages}>
{children}
</NextIntlClientProvider>
</body>
</html>
);
}
第五步：使用翻译
import { useTranslations } from 'next-intl';
export function WelcomeBanner() {
const t = useTranslations('common');
return (
<div>
<h1>{t('welcome_title')}</h1>
<p>{t('welcome_description')}</p>
</div>
);
}
环境变量
# .env.local
BETTER_I18N_PROJECT=acme/dashboard
公钥已内置在 SDK 中 — 只读 CDN 访问无需 API 密钥。
ISR 缓存工作原理
SDK 内部创建两个 createI18nCore 实例：
- Manifest core — 获取可用语言列表，每隔
manifestRevalidateSeconds重新验证（默认：3600s） - Messages core — 获取翻译，每隔
messagesRevalidateSeconds重新验证（默认：30s）
这意味着发布新翻译后，您的 Next.js 应用在约 30 秒内无需重新构建即可获取它们。
下一步
这篇文章对你有帮助吗？