访问官网
Github
文档next-i18next
翻译你的Next.js应用的最简单方法(使用pages设置)。**
如果你正在生产环境中使用next-i18next*(pages目录)*，并想释放一些超能力，可以看看这篇博文。
如果你正在使用带有app目录的Next.js 13/14，则不需要next-i18next，你可以直接使用i18next和react-i18next，就像这篇博文中描述的那样。
这是什么？
虽然Next.js直接提供国际化路由，但它不处理任何翻译内容的管理，也不处理实际的翻译功能。Next.js所做的只是保持你的语言环境和URL同步。
为了补充这一点，next-i18next提供了剩余的功能 - 翻译内容的管理，以及翻译React组件的组件/钩子 - 同时完全支持SSG/SSR、多个命名空间、代码分割等。
虽然next-i18next在底层使用了i18next和react-i18next，但next-i18next的用户只需要将他们的翻译内容作为JSON文件包含进来，不需要担心其他太多事情。
这里有一个在线演示。这个演示应用是简单示例 - 没有更多，也没有更少。
为什么选择next-i18next？
易于设置，易于使用：设置只需几个步骤，配置简单。
没有其他要求：next-i18next简化了你的Next.js应用的国际化，无需额外依赖。
生产就绪：next-i18next支持将翻译和配置选项作为props传递到页面，并支持SSG/SSR。
它是如何工作的？
你的next-i18next.config.js文件将为next-i18next提供配置。
配置后，appWithTranslation允许我们通过钩子在组件中使用t（翻译）函数。
然后我们在页面级组件中的getStaticProps或getServerSideProps（取决于你的情况）中添加serverSideTranslation。
现在我们的Next.js应用完全可以翻译了！
设置
1. 安装
yarn add next-i18next react-i18next i18next
你还需要安装react和next。
2. 翻译内容
默认情况下，next-i18next期望你的翻译按以下方式组织：
.
└── public
└── locales
├── en
| └── common.json
└── de
└── common.json
这种结构也可以在简单示例中看到。
如果你想以自定义方式组织你的翻译/命名空间，你需要在初始化配置中传入修改后的localePath和localeStructure值。
3. 项目设置
首先，在项目根目录创建一个next-i18next.config.js文件。嵌套的i18n对象的语法直接来自Next.js。
这告诉next-i18next你的defaultLocale和其他语言环境是什么，以便它可以在服务器上预加载翻译：
next-i18next.config.js
/** @type {import('next-i18next').UserConfig} */
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'de'],
},
}
现在，创建或修改你的next.config.js文件，通过将i18n对象传入你的next.config.js文件，以启用本地化URL路由：
next.config.js
const { i18n } = require('./next-i18next.config')
module.exports = {
i18n,
}
next-i18next导出了三个函数，你需要使用它们来翻译你的项目：
appWithTranslation
这是一个HOC，它包装你的_app：
import { appWithTranslation } from 'next-i18next'
const MyApp = ({ Component, pageProps }) => (
<Component {...pageProps} />
)
export default appWithTranslation(MyApp)
appWithTranslation HOC主要负责添加一个I18nextProvider。
serverSideTranslations
这是一个异步函数，你需要在页面级组件中通过getStaticProps或getServerSideProps（取决于你的用例）包含它：
import { serverSideTranslations } from 'next-i18next/serverSideTranslations'
export async function getStaticProps({ locale }) {
return {
props: {
...(await serverSideTranslations(locale, [
'common',
'footer',
])),
// 将作为props传递给页面组件
},
}
}
注意，serverSideTranslations必须从next-i18next/serverSideTranslations导入 - 这是一个包含NodeJs特定代码的单独模块。
另外，注意serverSideTranslations与getInitialProps不兼容，因为它_只能_在服务器环境中执行，而getInitialProps在页面间导航时会在客户端调用。
serverSideTranslations HOC主要负责将翻译和配置选项作为props传入页面 - 你需要将它添加到任何有翻译的页面中。
useTranslation
这是你实际用来进行翻译的钩子。useTranslation钩子来自react-i18next，但需要直接从next-i18next导入。
不要使用react-i18next的useTranslation导出，而只使用next-i18next的导出！
import { useTranslation } from 'next-i18next'
export const Footer = () => {
const { t } = useTranslation('footer')
return (
<footer>
<p>{t('description')}</p>
</footer>
)
}
4. 声明命名空间依赖
默认情况下，next-i18next会在每次初始请求时将_所有你的命名空间_发送到客户端。对于内容较少的小型应用来说，这可能是一种合适的方法，但许多应用会受益于基于路由拆分命名空间。
要实现这一点，你可以将每个页面所需的命名空间数组传递给serverSideTranslations。你可以在examples/simple/pages/index.tsx中看到这种方法。传入一个空的所需命名空间数组将不会发送任何命名空间。
注意：useTranslation为你使用它的组件提供命名空间。然而，serverSideTranslations为整个React树提供可用的命名空间总数，属于页面级别。两者都是必需的。
5. 声明语言依赖
默认情况下，next-i18next在每个请求中只会向客户端发送_当前活动的语言_。这有助于减少发送给客户端的初始负载大小。然而，在某些情况下，可能还需要在运行时使用其他语言的翻译。例如，当使用useTranslation钩子的getFixedT时。
要改变这种行为并加载额外的语言，只需将语言数组作为最后一个参数传递给serverSideTranslations。
import { serverSideTranslations } from 'next-i18next/serverSideTranslations';
export async function getStaticProps({ locale }) {
return {
props: {
- ...(await serverSideTranslations(locale, ['common', 'footer'])),
+ ...(await serverSideTranslations(locale, ['common', 'footer'], null, ['en', 'no'])),
},
};
}
结果是，无论当前语言如何，'no'和'en'两种语言的翻译都会被加载。
注意：额外的参数应该添加到所有使用
getFixedT函数的页面中。
后备语言
默认情况下，next-i18next会添加defaultLocale作为后备语言。要更改这一点，你可以设置fallbackLng。i18next支持的所有值（字符串、数组、对象和函数）也都被next-i18next支持。
此外，可以将nonExplicitSupportedLngs设置为true，以支持一种语言的所有变体，而无需为每个变体提供JSON文件。请注意，所有变体仍然必须包含在locales中，以启用next.js内的路由。
注意：
fallbackLng和nonExplicitSupportedLngs可以同时使用。只有一个例外：当nonExplicitSupportedLngs为true时，不能将fallbackLng设置为函数。
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr', 'de-AT', 'de-DE', 'de-CH'],
},
fallbackLng: {
default: ['en'],
'de-CH': ['fr'],
},
nonExplicitSupportedLngs: true,
// de, fr和en将作为de-CH的后备语言加载
}
请注意，使用fallbackLng和nonExplicitSupportedLngs可能会轻易增加页面的初始大小。
提示：将fallbackLng设置为false将不会序列化你的后备语言（通常是defaultLocale）。这将减少初始页面加载的大小。
6. 高级配置
传递其他配置选项
如果你需要修改更多高级配置选项，可以通过next-i18next.config.js传递它们。例如：
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'de'],
},
localePath:
typeof window === 'undefined'
? require('path').resolve('./my-custom/path')
: '/public/my-custom/path',
ns: ['common'],
}
不可序列化的配置
一些i18next插件（可以通过config.use传入）是不可序列化的，因为它们包含函数和其他JavaScript原语。
如果你的用例比较高级，可能会遇到这种情况。你会看到Next.js抛出类似这样的错误：
Error: Error serializing `._nextI18Next.userConfig.use[0].process` returned from `getStaticProps` in "/my-page".
Reason: `function` cannot be serialized as JSON. Please only return JSON serializable data types.
要解决这个问题，你需要将config.serializeConfig设置为false，并手动将你的配置传递给appWithTranslation：
import { appWithTranslation } from 'next-i18next'
import nextI18NextConfig from '../next-i18next.config.js'
const MyApp = ({ Component, pageProps }) => (
<Component {...pageProps} />
)
export default appWithTranslation(MyApp, nextI18NextConfig)
import { serverSideTranslations } from 'next-i18next/serverSideTranslations'
import nextI18NextConfig from '../next-i18next.config.js'
export const getStaticProps = async ({ locale }) => ({
props: {
...(await serverSideTranslations(
locale,
['common', 'footer'],
nextI18NextConfig
)),
},
})
在fallback SSG页面中的使用
当在使用getStaticPaths和fallback: true或fallback: 'blocking'的服务器端生成页面中使用时，上面指示的默认设置将导致应用在每次加载时被卸载和重新挂载，这会导致各种不利后果，如每个useEffect(() => {...}, [])钩子被调用两次以及轻微的性能下降。
这是因为对于这些页面，Next.js会先用空的serverSideProps进行第一次渲染，然后用包含next-i18next翻译的serverSideProps进行第二次渲染。在默认设置下，当serverSideProps为空时，i18n实例最初是undefined，导致卸载-重新挂载。
要缓解这个问题，你可以这样做：
import { UserConfig } from 'next-i18next';
import nextI18NextConfig from '../next-i18next.config.js'
const emptyInitialI18NextConfig: UserConfig = {
i18n: {
defaultLocale: nextI18NextConfig.i18n.defaultLocale,
locales: nextI18NextConfig.i18n.locales,
},
};
const MyApp = ({ Component, pageProps }) => (
<Component {...pageProps} />
)
export default appWithTranslation(MyApp, emptyInitialI18NextConfig) // 确保初始i18n实例不是undefined
只要你确保在fallback页面状态下，你的客户端代码不试图显示任何翻译，这就可以正常工作。否则，你会从Next.js得到一个"服务器-客户端不匹配"错误（因为服务器在其html中有实际的翻译，而客户端html在相同位置有翻译键）。 这是正常的，也是没问题的：你本来就不应该向用户显示翻译键！
通过HTTP客户端加载翻译
自v11.0.0版本起，next-i18next也提供了客户端加载翻译的支持。
在某些用例中，你可能想要动态加载翻译文件，而不必使用serverSideTranslations。这对于你不想降低页面速度的懒加载组件特别有用。
更多相关信息可以在这里找到。
在开发中重新加载资源
因为资源在服务器启动时只加载一次，所以在开发过程中对翻译JSON文件所做的任何更改都不会被加载，直到服务器重新启动。
在生产环境中，这通常不是一个问题，但在开发环境中，你可能希望看到翻译JSON文件的更新，而不必每次都重新启动开发服务器。要做到这一点，可以将reloadOnPrerender配置选项设置为true。
这个选项会在每次调用serverSideTranslations（在getStaticProps或getServerSideProps中）时重新加载你的翻译。如果你在getServerSideProps中使用serverSideTranslations，建议在生产环境中禁用reloadOnPrerender，以避免在每次服务器调用时重新加载资源。
选项
| 键名 | 默认值 | 说明 |
|---|---|---|
defaultNS | 'common' | |
localePath | './public/locales' | 可以是一个函数，详见下方注释。(如果直接通过配置传递resources选项，也可以为null，如此处所示) |
localeExtension | 'json' | 如果localePath是一个函数，则忽略此项。 |
localeStructure | '{{lng}}/{{ns}}' | 如果localePath是一个函数，则忽略此项。 |
reloadOnPrerender | false | |
serializeConfig | true | |
use (用于插件) | [] | |
onPreInitI18next | undefined | 例如：(i18n) => i18n.on('failedLoading', handleFailedLoading) |
作为函数的localePath的形式为(locale: string, namespace: string, missing: boolean) => string，返回包含文件名和扩展名的完整路径。当missing为true时，返回i18next-fs-backend的addPath选项的路径；当为false时，返回loadPath选项的路径。更多信息请参见i18next-fs-backend仓库。
如果localePath是一个函数，请确保同时定义ns选项，因为在服务器端我们无法预加载命名空间。
所有其他i18next选项和react-i18next选项也可以传入。
您也可以直接传入resources，同时将localePath设置为null。
自定义插值前缀/后缀
默认情况下，i18next使用{{作为前缀，}}作为后缀进行插值。
如果您想/需要覆盖这些插值设置，您必须同时指定一个与您自定义前缀和后缀匹配的替代localeStructure设置。
例如，如果您想使用{和}，配置将如下所示：
{
i18n: {
defaultLocale: 'en',
locales: ['en', 'nl'],
},
interpolation: {
prefix: '{',
suffix: '}',
},
localeStructure: '{lng}/{ns}',
}
自定义next-i18next.config.js路径
如果您想更改默认配置路径，可以设置环境变量I18NEXT_DEFAULT_CONFIG_PATH。
例如，在.env文件中，您可以设置一个静态路径：
I18NEXT_DEFAULT_CONFIG_PATH=/path/to/project/apps/my-app/next-i18next.config.js
或者，您可以在next.config.js中使用一个技巧来设置动态路径：
process.env.I18NEXT_DEFAULT_CONFIG_PATH = `${__dirname}/next-i18next.config.js`;
// ... 其他导入
const { i18n } = require('./next-i18next.config');
// ... 其他代码
module.exports = {
i18n,
...
};
这意味着i18n配置文件将与next.config.js在同一目录中，无论您当前的工作目录是什么。这对于例如使用nx的单体仓库非常有帮助，当您从项目根目录启动应用程序，但应用程序位于apps/{appName}中时。
注意 如果您的配置next-i18next.config.js不在与next.config.js相同的目录中，您必须手动（或通过自定义脚本）复制它。
逐步添加next-i18next
如果您计划逐步将next-i18next添加到您的项目中，我们建议您将next-i18next.config传递给appWithTranslation以避免任何问题。
例如：
import nextI18nextConfig from '../../next-i18next.config';
//...
export default appWithTranslation(MyApp, nextI18nextConfig);
更多信息请参见问题#2259。
注意事项
Vercel和Netlify
一些无服务器PaaS可能无法找到您的翻译路径，需要额外配置。如果您在使用serverSideTranslations时遇到文件系统问题，请将config.localePath设置为使用path.resolve。这里有一个示例。
Docker
对于Docker部署，请注意如果您使用Next.js文档中的Dockerfile，不要忘记将next.config.js和next-i18next.config.js复制到Docker镜像中。
COPY --from=builder /app/next.config.js ./next.config.js
COPY --from=builder /app/next-i18next.config.js ./next-i18next.config.js
异步i18next后端
如果您选择使用内置i18next-fs-backend以外的i18next后端，您需要确保在调用t函数之前加载翻译资源。
由于React suspense尚不支持SSR，这可以通过两种不同的方式解决：
1) 预加载命名空间：
设置ns选项，如这个例子所示。这样做将确保在初始化时加载所有翻译资源。
2) 检查ready标志：
如果您不能或不想提供ns数组，对t函数的调用将导致命名空间即时加载。这意味着您需要通过检查ready === true或props.tReady === true来处理"未就绪"状态。如果不这样做，将导致在翻译加载之前渲染翻译，这将导致尽管翻译实际存在（只是尚未加载）却调用"save missing"。
这可以通过useTranslation钩子或withTranslation HOC来完成。
静态HTML导出SSG
您是否尝试通过执行next export生成静态HTML导出并遇到这个错误？
Error: i18n support is not compatible with next export. See here for more info on deploying: https://nextjs.org/docs/deployment
但是有一种方法可以通过next-language-detector的帮助来解决这个问题。
查看这篇博文和这个示例项目。
在子组件中翻译
您有多种方式在子组件中使用t函数：
- 通过props将
t函数传递给子组件 - 通过props将已翻译的文本传递给子组件，如这个例子：https://github.com/i18next/next-i18next/blob/master/examples/simple/components/Header.tsx#L12
- 使用
useTranslation函数，如这个例子：https://github.com/i18next/next-i18next/blob/e6b5085b5e92004afa9516bd444b19b2c8cf5758/examples/simple/components/Footer.tsx#L6 - 使用
withTranslation函数
总的来说，您始终需要确保serverSideTranslations包含树中所需的所有命名空间。
贡献者
感谢这些优秀的人（表情符号键）：
 Rob Capellini 💻 ⚠️ |  Alexander Kachkaev 📢 💬 🤔 💻 ⚠️ |  Mathias Wøbbe 💻 🤔 ⚠️ |  Lucas Feliciano 🤔 👀 |  Ryan Leung 💻 |  Nathan Friemel 💻 📖 💡 🤔 |  Isaac Hinman ️️️️♿️ 💬 🔊 📝 🐛 💼 💻 🖋 🔣 🎨 📖 📋 💡 💵 🔍 🤔 🚇 🚧 🧑🏫 📦 🔌 📆 🔬 👀 🛡️ 📢 ⚠️ 🔧 🌍 ✅ 📓 📹 |
 Adriano Raiano ️️️️♿️ 💬 🔊 📝 🐛 💼 💻 🖋 🔣 🎨 📖 📋 💡 💵 🔍 🤔 🚇 🚧 🧑🏫 📦 🔌 📆 🔬 👀 🛡️ 📢 ⚠️ 🔧 🌍 ✅ 📓 📹 |  Felix Mosheev 💬 💻 📢 ⚠️ |  Sébastien Vanvelthem 💻 📖 💡 🚧 📓 |
黄金赞助商
本地化即服务 - locize.com
需要翻译管理工具吗？想要使用上下文编辑器编辑你的翻译吗？使用 i18next 维护者为你提供的原创工具！
使用 locize 可以直接支持 i18next 和 next-i18next 的未来发展。
