next-i18next 项目从 v7 升级到 v8 完全指南

next-i18next 项目从 v7 升级到 v8 完全指南

next-i18next 项目地址: https://gitcode.com/gh_mirrors/nex/next-i18next

前言

next-i18next 是一个用于 Next.js 项目的国际化解决方案，它基于 i18next 构建，为开发者提供了便捷的多语言支持。随着 Next.js 自身对国际化路由的支持不断增强，next-i18next 在 v8 版本中也进行了重大架构调整。本文将详细介绍如何从 v7 版本平滑迁移到 v8 版本。

核心变化概述

v8 版本最重要的变化是移除了国际化路由功能，因为 Next.js 已经原生支持这一特性。这一变化带来了以下关键影响：

1. 翻译功能不再在全局层面初始化（如在 _app.js 中）
2. 现在需要在每个页面中使用新的 serverSideTranslations 方法
3. i18n 对象现在同时支持客户端和服务端渲染

保留的功能

尽管架构发生了变化，但以下核心功能保持不变：

1. appWithTranslation 仍然用于包装 _app.js 中的 App 组件
2. withTranslation 高阶组件的使用方式不变
3. useTranslation Hook 的使用方式不变
4. 翻译内容的结构保持不变

迁移步骤详解

1. 配置文件调整

移除原有的 i18n.js 文件，改为在项目根目录创建 next-i18next.config.js 配置文件，并在 next.config.js 中引用它。

2. 导入路径变更

将所有从 'i18n' 的导入改为从 'next-i18next' 导入：

• appWithTranslation
• withTranslation
• useTranslation

3. 页面级翻译配置

在每个需要翻译的页面中，需要在 getServerSideProps 或 getStaticProps 中添加：

return {
  props: {
    ...(await serverSideTranslations(locale, ['common', 'page-specific']))
  }
}

注意：如果 _app.js 中有组件需要翻译，则必须为所有页面添加此配置。

4. 移除废弃配置

删除 _app.js 中的 namespacesRequired: ['common'] 配置，这一配置在 v8 中不再使用。

5. 语言切换方式更新

现在可以通过以下方式强制切换语言：

router.push(router.asPath, undefined, { locale: 'zh-CN' });

可选优化项

1. 自定义错误页面国际化：为 404 和 500 页面添加 serverSideTranslations 配置
2. 语言识别优化：设置 NEXT_LOCALE cookie 以增强语言识别能力
3. 测试配置调整：更新 Jest 测试配置，正确 mock 国际化相关功能

常见问题解答

Q: 为什么必须迁移到 v8？

A: 因为新版本的 Next.js 将不再兼容 next-i18next v7，迁移可以确保项目持续获得支持和更新。

Q: 如果我的项目必须使用 getInitialProps 怎么办？

A: 可以暂时继续使用 7.x 版本，但建议尽快重构以支持新的数据获取方式。

Q: 服务端渲染和客户端渲染的 i18n 对象有什么区别？

A: 在 v8 中，i18n 对象现在是统一的，无论在服务端还是客户端都能正确获取当前语言设置。

迁移后的验证

完成迁移后，建议进行以下验证：

1. 检查所有页面的翻译是否正常显示
2. 测试语言切换功能是否正常工作
3. 验证服务端渲染页面中的国际化内容是否正确
4. 确保自定义错误页面的翻译正常

总结

next-i18next v8 的架构调整使其更好地与 Next.js 的国际化路由集成，虽然迁移需要一些工作，但最终会带来更清晰的项目结构和更好的维护性。按照本文的步骤进行迁移，可以确保平稳过渡到新版本。

next-i18next 项目地址: https://gitcode.com/gh_mirrors/nex/next-i18next