当前位置：首页 > article >正文

Next.js国际化：next-i18next

article 2026/4/19 16:45:43

引言

next-i18next 是专门为 Next.js 项目量身定制的国际化解决方案，它基于强大的 i18next 库，能帮助开发者轻松地为 Next.js 应用添加多语言支持

next-i18next 初相识

项目简介

next-i18next 是一个专为 Next.js 应用程序打造的国际化解决方案，它建立在 i18next 和 react-i18next 这两个强大的库之上。i18next 是一个功能丰富的国际化框架，提供了全面的翻译功能，包括语言的切换、复数形式的处理、插值等；react-i18next 则是 i18next 在 React 应用中的桥梁，使得在 React 组件中使用 i18next 的功能变得更加便捷。next-i18next 集成了这两者的优势，为 Next.js 项目提供了一站式的国际化服务。

它全面支持静态站点生成（SSG）和服务器端渲染（SSR）。在 SSG 模式下，next-i18next 可以在构建时生成不同语言版本的静态页面，提高页面的加载速度和性能；对于 SSR，它能够在服务器端就完成翻译工作，将翻译后的内容直接发送给客户端，增强了用户体验，特别是对于那些对首次加载时间敏感的应用场景，如电商网站、新闻门户等，具有重要意义。

安装依赖

在项目根目录下，通过 npm 或 yarn 安装 next-i18next 及其相关依赖。next-i18next 依赖于 i18next 和 react-i18next，因此需要一并安装：

npm install --save next-i18next i18next react-i18next

或者使用 yarn：

yarn add next-i18next i18next react-i18next

next-i18next 配置全解析

创建配置文件

在项目根目录下创建next-i18next.config.js文件，这是 next-i18next 的核心配置文件，用于定义国际化的基本设置。以下是一个基本的配置示例：

module.exports = {i18n: {defaultLocale: 'en', // 默认语言，当用户未指定语言时使用locales: ['en', 'zh', 'de'], // 支持的语言列表localePath: typeof window === 'undefined'? require('path').resolve('./public/locales'): '/locales' // 翻译文件的存储路径，在服务器端和客户端环境下的不同设置},// 其他配置项，如命名空间、回退语言策略等
};

在上述配置中，defaultLocale指定了默认语言为英语（en）。这意味着当用户首次访问应用且没有明确选择语言时，应用将以英语呈现内容。locales数组列出了应用支持的所有语言，这里包括英语（en）、中文（zh）和德语（de）。你可以根据项目的实际需求添加或删除语言。

localePath配置项用于指定翻译文件的存储路径。通过typeof window === 'undefined'判断当前环境是服务器端还是客户端。
在服务器端，使用require('path').resolve('./public/locales')将路径解析为项目根目录下的public/locales文件夹，这是一个相对稳定的服务器端路径表示；
在客户端，直接使用/locales，这是基于浏览器路径的表示，确保客户端能够正确访问到翻译文件

集成到 Next.js

在next.config.js文件中引入并配置国际化相关设置，使 next-i18next 与 Next.js 项目集成。修改next.config.js如下：

const { i18n } = require('./next-i18next.config');module.exports = {i18n,// 其他Next.js配置项，如页面路径、样式加载等
};

上述代码中，首先通过const { i18n } = require('./next-i18next.config');
从next-i18next.config.js文件中导入i18n配置对象。然后，在next.config.js的module.exports中直接使用i18n，这样 Next.js 就会识别并应用这些国际化配置。

实战：用 next-i18next 实现多语言切换

准备翻译文件

在项目的public/locales目录下，按照语言代码创建对应的文件夹，每个文件夹中放置该语言的 JSON 翻译文件。例如，对于英语（en）和中文（zh），可以创建以下结构：

public/
└── locales/├── en/│   └── common.json└── zh/└── common.json

在common.json文件中，定义需要翻译的文本内容。例如，en/common.json文件内容如下：

{"greeting": "Hello","welcome": "Welcome to our application"
}

zh/common.json文件内容如下：

{
"greeting": "你好",
"welcome": "欢迎来到我们的应用"
}

这里的greeting和welcome是翻译键，对应不同语言的翻译值。通过这种键值对的方式，可以方便地管理和维护翻译内容，并且在后续的代码中，只需要根据翻译键来获取对应的翻译文本。

页面组件集成

在页面组件中，使用next-i18next提供的高阶组件appWithTranslation来包裹顶级组件，通常是_app.js文件中的MyApp组件。这样可以为整个应用提供翻译上下文。

import { appWithTranslation } from 'next-i18next';
import MyApp from '../pages/_app';export default appWithTranslation(MyApp);

在具体的页面组件中，使用useTranslation钩子来获取翻译函数t，从而实现文本的翻译。例如，在index.js页面组件中：

import { useTranslation } from 'next-i18next';const IndexPage = () => {const { t } = useTranslation('common');return (<div><h1>{t('greeting')}</h1><p>{t('welcome')}</p></div>);
};export default IndexPage;

useTranslation('common')表示从common命名空间中获取翻译内容。
通过const { t } = useTranslation('common');解构出翻译函数t，然后在组件中使用{t('greeting')}和{t('welcome')}来显示对应的翻译文本。
当语言切换时，t函数会根据当前的语言环境返回相应语言的翻译内容。

服务器端翻译加载

对于动态生成的页面，在getStaticProps或getServerSideProps函数中，使用serverSideTranslations函数来获取服务器端的翻译数据。这确保了在静态生成或服务器端渲染时，页面能够正确地加载翻译内容。

import { serverSideTranslations } from 'next-i18next/serverSideTranslations';export async function getStaticProps({ locale }) {return {props: {...(await serverSideTranslations(locale, ['common'])),// 其他props数据},};
}

serverSideTranslations(locale, ['common'])函数接收当前的语言环境locale和需要加载的命名空间数组['common']作为参数。
它会返回一个包含翻译数据的对象，通过展开运算符...将这些翻译数据合并到props中，传递给页面组件。这样，在页面渲染时，就可以使用这些预加载的翻译数据，避免了客户端再去请求翻译文件，提高了页面的加载速度和性能。

优化

动态加载语言包

在大型应用中，一次性加载所有语言包可能会导致初始加载时间过长，影响用户体验。

next-i18next 支持动态加载语言包，让你仅在需要时加载特定语言的资源文件。

首先，在next-i18next.config.js中配置load选项为currentOnly，表示只加载当前语言的资源：

module.exports = {i18n: {defaultLocale: 'en',locales: ['en', 'zh', 'de'],localePath: typeof window === 'undefined'? require('path').resolve('./public/locales'): '/locales',load: 'currentOnly'},
};

然后，在组件中使用useTranslation钩子时，可以通过fallbackLng选项指定回退语言，确保在当前语言包加载失败时仍有可用的翻译：

import { useTranslation } from 'next-i18next';const MyComponent = () => {const { t } = useTranslation('common', { fallbackLng: 'en' });return (<div><p>{t('message')}</p></div>);
};export default MyComponent;

这样，当用户切换语言时，next-i18next 会自动加载对应的语言包，而不是在应用启动时全部加载，有效提升了应用的加载性能和响应速度。

多级菜单和路径国际化

在处理具有多级菜单和深层导航结构的应用时，确保所有链接都能正确处理语言前缀是至关重要的。Next.js 的动态路由功能为实现这一目标提供了便利。

假设你的应用有一个多级菜单，其中包含不同语言版本的页面链接。在next-i18next的配置下，你需要在链接中正确添加语言前缀。例如，在next/link组件中：

import Link from 'next/link';
import { useRouter } from 'next/router';const MenuItem = ({ href, label }) => {const router = useRouter();const { locale } = router;return (<Link href={`/${locale}${href}`}><a>{label}</a></Link>);
};export default MenuItem;

href={/\({locale}\){href}}动态地将当前语言代码locale添加到链接路径前，确保无论用户在哪个语言环境下，点击链接都能正确导航到对应语言版本的页面。

对于动态路由页面，如pages/post/[id].js，你可以在getStaticProps或getServerSideProps中获取当前语言环境，并根据需要返回相应语言的内容：

import { serverSideTranslations } from 'next-i18next/serverSideTranslations';export async function getStaticProps({ params, locale }) {const postId = params.id;// 根据postId和locale获取相应语言的文章数据const post = await getPostByLocale(postId, locale);return {props: {...(await serverSideTranslations(locale, ['common'])),post},};
}

通过这种方式，可以确保在深层导航结构中，无论是静态页面还是动态页面，都能正确地处理语言国际化，为用户提供一致的多语言浏览体验。

常见问题与解决方案

在使用 next-i18next 的过程中，开发者可能会遇到一些常见问题，下面将列举并提供相应的解决方案。

翻译文件加载失败

问题描述：在应用启动或语言切换时，可能会出现翻译文件无法加载的情况，导致页面显示原始的翻译键，而不是翻译后的文本。这可能是由于翻译文件路径配置错误、文件缺失或网络问题等原因引起。

解决方案：

检查路径配置：仔细核对next-i18next.config.js中的localePath配置项，确保它指向正确的翻译文件存储目录。在服务器端和客户端环境下，路径的表示可能不同，需要分别确认。例如，在服务器端，使用require('path').resolve('./public/locales')确保路径解析正确；在客户端，/locales应与实际的文件路径相对应。
确认文件存在：检查localePath指定目录下，是否存在对应语言和命名空间的翻译文件。例如，如果配置了支持英语（en）和中文（zh），并且使用了common命名空间，那么public/locales/en/common.json和public/locales/zh/common.json文件应该存在且内容正确。
网络请求排查：在浏览器的开发者工具中，查看网络请求，确认翻译文件的请求是否成功。如果出现 404 错误，说明文件未找到；如果是其他网络错误，如 500 错误，可能是服务器端的问题，需要进一步检查服务器日志，排查文件读取或传输过程中的错误。

语言切换异常

问题描述：当用户切换语言时，页面内容没有及时更新为新语言的翻译，或者出现闪烁、卡顿等异常现象。这可能是由于语言切换逻辑未正确实现，或者组件没有正确响应语言变化。
解决方案：
使用正确的切换方法：确保在切换语言时，使用next-i18next提供的changeLanguage方法，并且在组件中正确处理语言切换后的更新。例如，在useTranslation钩子所在的组件中，当changeLanguage被调用时，组件会自动重新渲染，以显示新语言的翻译内容。如果组件没有自动更新，可以尝试使用useEffect钩子，监听语言变化并手动触发更新。
避免重复初始化：在应用中，确保i18next实例只被初始化一次，避免在不必要的地方重复调用init方法，以免导致配置冲突和语言切换异常。通常在应用的入口文件（如_app.js）中进行一次初始化即可。
优化性能：对于大型应用，语言切换时可能会因为加载大量翻译数据而导致卡顿。可以采用动态加载语言包的方式，减少初始加载的数据量，提高语言切换的响应速度。同时，合理使用缓存机制，避免频繁重复加载相同的翻译文件。

服务器端渲染时翻译问题

问题描述：在服务器端渲染（SSR）过程中，可能出现翻译数据未正确加载或传递的问题，导致页面在服务器端渲染的结果与客户端不一致，或者出现翻译缺失的情况。

解决方案：

正确配置服务器端翻译：在getStaticProps或getServerSideProps函数中，使用serverSideTranslations函数获取服务器端的翻译数据，并将其正确传递给页面组件。确保函数接收的locale参数正确，它决定了加载哪个语言的翻译数据。
处理异步操作：由于serverSideTranslations是异步函数，需要正确处理异步操作，确保翻译数据在页面渲染前已经加载完成。可以使用await关键字等待翻译数据的获取，避免在数据未准备好时就进行页面渲染。

引言