Next.js 国际化：使用 next-intl 完成 i18n 指南

超过 75% 的互联网用户更喜欢用母语浏览，进行本地化的企业在非英语市场的转化率提高了 70%。 Next.js 与 next-intl 相结合，提供了一个强大的国际化框架，可以跨任意数量的区域设置处理路由、翻译、格式化和 SEO。

要点

• next-intl 与 Next.js App Router 和服务器组件无缝集成
• 区域设置前缀路由保持英语 URL 干净，同时添加其他语言的前缀
• 服务器组件加载翻译，无需客户端 JavaScript 捆绑开销
• 正确的 hreflang 标签和多语言站点地图对于国际 SEO 至关重要

---

项目设置

安装 next-intl 并使用包含routing.ts、navigation.ts 和 request.ts 的 i18n 目录组织您的项目。将您的应用程序放置在应用程序路由器的 [locale] 下。将翻译 JSON 文件存储在项目根目录的消息目录中。

路由配置

使用defineRouting() 定义路由，指定区域设置数组、默认区域设置和区域设置前缀策略。 “按需”策略省略默认区域设置（英语）的前缀，同时添加其他区域设置的 /es/、/fr/、/ar/ 前缀。

使用 createNavigation(routing) 创建导航包装器以获取区域设置感知的 Link、useRouter、usePathname 和重定向功能。在整个应用程序中使用这些而不是 Next.js 原生导航。

中间件设置

在 Next.js 16 中，创建 proxy.ts 文件（替换旧的 middleware.ts 模式）。导出由createMiddleware(routing)创建的代理函数。配置匹配器以排除 API 路由、静态文件和 _next 路径。

---

翻译文件

JSON 结构（嵌套，非扁平）

使用按命名空间组织的嵌套键。切勿使用平点分隔的键，例如“home.title”——它们会破坏 next-intl 命名空间解析。结构翻译为：

• 常见：共享术语（按钮、标签、加载状态）
• nav：导航项目
• 主页：主页内容
• 关于：关于页面内容
• admin.common：共享管理术语
• admin.products：产品管理页面

服务器组件

在异步服务器组件中使用 getTranslations("namespace")。这会将翻译加载到服务器上，对客户端捆绑包的影响为零。调用 t("key") 进行字符串翻译，调用 t.rich("key", { bold: (chunks) => ... }) 进行富文本。

客户端组件

在标有“use client”的客户端组件中使用 useTranslations("namespace") 挂钩。该钩子提供相同的 t() 函数。客户端捆绑包中仅包含活动命名空间的翻译。

---

RTL（从右到左）支持

对于阿拉伯语、希伯来语、乌尔都语和其他 RTL 语言，请根据当前区域设置在 HTML 元素上设置 dir="rtl"。在区域设置布局中，检查区域设置是否在您的 rtlLocales 数组中并相应地设置方向。

使用 Tailwind CSS 逻辑属性（ps、pe、ms、me，而不是 pl、pr、ml、mr）来实现在 RTL 模式下自动翻转的布局。为 RTL 脚本加载适当的字体（例如，针对阿拉伯语和乌尔都语的 Noto Sans Canadian）。

---

SEO：元数据和 Hreflang

动态元数据

每个页面都必须使用generateMetadata()（绝不是静态导出常量元数据）来获取区域设置感知的标题、描述和hreflang 替代项。构建一个将每个区域设置映射到其 URL 路径的替代.语言对象，以及指向英语版本的 x-default 条目。

多语言站点地图

为每个区域设置中的每个页面生成站点地图条目。每个条目应包含映射所有语言环境变体的替代项。这使得搜索引擎能够在每个市场提供正确的语言版本。

内容语言元标记

在区域设置布局中设置内容语言元标记，以帮助搜索引擎和人工智能爬虫识别页面语言。这对于 Bing 和新兴的人工智能搜索引擎尤其重要。

---

翻译工作流程

1. 编辑 en.json 作为所有可翻译字符串的单一事实来源
2. 运行翻译脚本 将新密钥传播到所有语言环境文件（使用 Google Translate API 或 DeepL 进行初始草稿）
3. 与母语人士一起审查翻译的质量和文化适应性
4. 彻底测试 RTL 语言 - 检查布局翻转、文本对齐和表单输入
5. 使用 hreflang 验证器工具和 Google Search Console 国际定位验证 SEO

处理大型翻译文件

对于具有 5,000 多个翻译键的应用程序，按命名空间组织 JSON 文件以提高可维护性。 next-intl 仅加载当前页面所需的命名空间，从而保持最佳性能。

---

性能考虑因素

• 服务器渲染：翻译在服务器上加载。除非该组件是客户端组件，否则不会将任何翻译 JSON 发送到客户端。
• 命名空间分割：每页仅加载活动命名空间，而不是整个翻译文件。
• 静态生成：使用 getTranslations() 的页面可以在构建时为所有语言环境静态生成。
• 捆绑包大小：客户端组件仅包含其名称空间翻译。使用 useTranslations("home") 的页面仅提供“home”命名空间。

---

常见陷阱

1. 平面键：使用“home.title”作为键而不是嵌套的 { "home": { "title": "..." } } 会破坏命名空间解析
2. 缺少翻译：始终提供后备行为 - 如果缺少翻译，next-intl 会显示密钥名称，但这对用户来说看起来很糟糕
3. 硬编码字符串：审核代码库中翻译系统之外的任何字符串
4. 日期/数字格式化：使用 next-intl 格式化程序而不是 toLocaleDateString() 以获得一致的行为
5. 静态元数据：使用导出常量元数据而不是generateMetadata()可以防止区域设置感知的标题和描述

---

常见问题

问：next-intl 可以处理多少个语言环境？

没有实际限制。具有 11 多个语言环境和 7,000 多个翻译键的应用程序运行时不会出现性能问题。服务器端渲染意味着翻译不会使客户端包膨胀。

问：i18n 会影响页面加载性能吗？

对于服务器组件，翻译加载发生在服务器上。性能影响可以忽略不计。客户端组件仅包含其命名空间翻译，通常为几 KB。

问：我们如何处理多种语言的动态数据库内容？

静态 UI 文本使用 JSON 文件。数据库内容（博客文章、产品描述）需要将翻译存储在专用列或表中，或使用具有内置翻译工作流程的 CMS。 Some teams use a hybrid: JSON for UI, database for content.

问：数字和日期格式怎么样？

next-intl 提供 useFormatter() 用于数字、货币、日期和相对时间的区域设置感知格式。所有格式均遵循 Intl 标准并自动遵守区域设置约定。

---

下一步是什么

国际化是一项在每个非英语市场都能带来红利的投资。从价值最高的区域开始，然后从那里扩展。

联系 ECOSIRE 获取国际化实施帮助，或探索我们的 Odoo 实施服务 进行多语言 ERP 部署。

---

由 ECOSIRE 发布——帮助企业利用企业软件解决方案进行扩展。