react国际化配置react-i18next详解

react PC端项目构建TS，react@18.2.0+antd+vite+axios+redux+sass+ts 完整版代码下载：
https://download.csdn.net/download/randy521520/88922625
react PC端项目构建，react@18.2.0+antd+vite+axios+redux+sass完整版代码下载：
https://download.csdn.net/download/randy521520/88922569
react移动端项目构建TS，react@18.2.0+react-vant+vite+axios+redux+sass+ts完整版代码下载：
https://download.csdn.net/download/randy521520/88917557
react移动端项目构建，react@18.2.0+react-vant+vite+axios+redux+sass完整版代码下载：
https://download.csdn.net/download/randy521520/88917543

一、简介

react-i18next 是一个用于在 React 应用中实现国际化（Internationalization，简称 i18n）的库，它是基于 i18next 的 React 封装版本。国际化是指将应用程序设计成能够适应不同语言和文化习惯的过程，使得应用能够在不同地区和语言环境下使用。
react-i18next 提供了一种简单且强大的方式来实现 React 应用的国际化，它支持以下主要特性：
1.多语言支持： 可以轻松地在应用中集成多种语言的支持，使用户能够切换不同的语言版本。
2.文本翻译： 可以通过配置文件或者 API 来管理应用中的文本内容，实现文本的国际化翻译。
3.变量替换： 支持在翻译文本中插入变量，以便动态替换内容。
4.Pluralization（复数处理）： 提供了复数形式处理的功能，以适应不同语言的复数规则。
5.Context（上下文）支持： 可以根据不同的上下文环境加载不同的翻译内容。
6.React Hooks 和 Higher-Order Components（HOC）： 提供了方便的 React Hooks 和 HOC，使得在 React 组件中使用国际化变得更加简单。

二、配置国际化，需安装react-i18next、i18next

1.lang.js

import i18n from "i18next";
import { initReactI18next } from "react-i18next";//英文配置
const enConfig ={ok: 'OK',
};//中文配置
let zhConfig = {ok: '确定',
};//切换语言
export const changeLanguage = (events)=>{const lang = events.target.value;i18n.changeLanguage(lang)
};const resources = {'zh_CN': {translation: zhConfig,},'en': {translation: enConfig,},
};i18n.use(initReactI18next).init({resources,lng: 'zh_CN',fallbackLng: 'zh_CN',interpolation: {escapeValue: false,},
});export default i18n;

2.main.jsx

import ReactDOM from "react-dom/client";
import {BrowserRouter} from "react-router-dom";
import App from "./App.jsx";
import "@lang/lang.js";ReactDOM.createRoot(document.getElementById('root')).render(<BrowserRouter><App /></BrowserRouter>,
)

3.使用

import {useTranslation} from "react-i18next";const Home = () => {const {t} = useTranslation()return (<>{t('ok')}</>)
}export default Home;

三、i18next相关API

1.i18next.use(module)：将其他插件加载到 i18next。
2.i18next.init(options, callback)：初始化国际化配置

• options：配置项

debug：控制台输出信息的调试级别。用于查找加载问题。
resources：初始化时使用的资源（如果不使用加载或不使用addResourceBundle进行附加）。
partialBundledLanguages：允许在使用后端加载非捆绑资源的同时使用捆绑资源进行初始化。
lng：要使用的语言（覆盖语言检测）。
fallbackLng：如果用户语言的翻译不可用，则使用的语言。
supportedLngs：允许的语言数组。
nonExplicitSupportedLngs：如果为true，将传递例如en-US，如果在supportedLngs中找到en。
load：要查找的语言代码，给定设置语言为'en-US'：'all' --> ['en-US'，'en'，'dev']，'currentOnly' --> 'en-US'，'languageOnly' --> 'en'。
preload：要预加载的语言数组。在服务器端很重要，以确保在呈现视图之前加载翻译。
lowerCaseLng：语言将转换为小写，例如en-US --> en-us。
cleanCode：将语言转换为小写，EN --> en，同时保留完整的区域设置，如en-US。
ns：要加载的命名空间的字符串或数组。
defaultNS：如果未传递给翻译函数的默认命名空间。
fallbackNS：如果在给定命名空间中找不到键，则查找键的字符串或数组。
saveMissing：如果未找到键，则在后端调用保存缺失键功能。
saveMissingPlurals：如果未找到键，也为复数形式调用后端的保存缺失键功能。
updateMissing：启用以使用saveMissing更新默认值（仅在defaultValue与翻译值不同的情况下起作用）。
saveMissingTo：在使用saveMissing功能时不返回键作为默认值。
missingKeyNoValueFallbackToKey：用于自定义缺失键处理（需要将saveMissing设置为true）。
parseMissingKeyHandler：接收在't()'中未找到的键并返回一个值，该值将被't()'返回。
appendNamespaceToMissingKey：将命名空间附加到缺失键。
missingInterpolationHandler：在插值值未定义时调用。如果值为空字符串或null，则不会调用此方法。
simplifyPluralSuffix：对于只有1个复数形式的语言，将使用'plural'作为后缀。
postProcess：要应用的默认后处理器的字符串或数组。
postProcessPassResolved：将已解析的对象传递到后处理器的选项对象中作为'i18nResolved'属性。
returnNull：允许空值作为有效的翻译。
returnEmptyString：允许空字符串作为有效的翻译。
returnObjects：允许对象作为有效的翻译结果。
returnDetails：返回包含有关所使用的语言、命名空间、键和值的信息的对象。
returnedObjectHandler：如果作为键传递了对象但returnObjects设置为false，则调用此方法。
joinArrays：用于连接数组的字符，例如'\n'。
overloadTranslationOptionHandler：设置defaultValue的函数。
interpolation：插值选项。
react：用于React的选项。
initImmediate：在setTimeout内触发init函数中的资源加载（默认异步行为）。
keySeparator：用于分隔键的字符。
nsSeparator：用于分隔命名空间和键的字符。
pluralSeparator：用于分隔复数和键的字符。
contextSeparator：用于分隔上下文和键的字符。
appendNamespaceToCIMode：在使用'cimode'时将命名空间前缀到返回的键。
compatibilityJSON：兼容性JSON版本。
locizeLastUsed：用于locize-lastused的选项。
locizeLastUsed.projectId：您的locize项目的ID。
locizeLastUsed.apiKey：如果要发送缺失的键，则使用的API密钥。
locizeLastUsed.referenceLng：项目的参考语言，默认为'en'。
locizeLastUsed.version：版本，默认为'latest'。
locizeLastUsed.debounceSubmit：发送数据的防抖间隔（毫秒），默认为90000。
locizeLastUsed.allowedHosts：允许发送最后使用数据的主机名数组。请将这些主机限制在本地系统、演示、测试服务器（而非生产环境）。默认为['localhost']。
ignoreJSONStructure：自动查找嵌套键，如果未找到则查找平面键，反之亦然。
maxParallelReads：调用后端的并行度限制。
maxRetries：执行重试的最大次数。
retryTimeout：在失败请求的重试之间等待的时间。

• callback：用于处理错误
  3.i18next.t(keys, options)：获取对应key的配置文本，options省略获取当前语言的
  4.i18next.exists(key, options)：判断对应的key是否存在
  5.i18next.getFixedT(lng, ns, keyPrefix)：

const t = i18next.getFixedT(null, null, 'user.accountSettings.changePassword')
const title = t('title');

6.i18next.changeLanguage(lng, callback)：切换当前语言

• lng：需要切换的语言
• callback：用于处理错误
  7.i18next.language、i18next.resolvedLanguage：获取当前是哪种语言
  8.i18next.languages：获取总共配置了哪些语言
  9.i18next.hasLoadedNamespace(ns, options)：检查命名空间是否已加载
  10.i18next.loadLanguages(lngs, callback)：预加载init中未定义的其他语言
  11.i18next.reloadResources()：重新加载资源
  12.i18next.setDefaultNamespace(ns)：更改默认命名空间
  13.i18next.dir(lng)：获取语言读取方向， rtl 或 ltr
  14.i18next.format(data, format, lng)：用于格式化文本

// key = 'hello {{what}}'
i18next.t('key', { what: i18next.format('world', 'uppercase') }); // -> hello WORLD

四、i18next相关事件

1.i18next.on(‘initialized’, function(options) {})：初始化事件
2.i18next.on(‘languageChanged’, function(lng) {})：语言改变事件
3.i18next.on(‘loaded’, function(loaded) {})：资源加载事件
4.i18next.on(‘failedLoading’, function(lng, ns, msg) {})：资源加载失败事件
5.i18next.on(‘missingKey’, function(lngs, namespace, key, res) {})：在访问不存在的密钥时被触发。需要将 saveMissing 设置为 true。
6.i18next.store.on(‘removed’, function(lng, ns) {})：资源删除事件
7.i18next.store.on(‘added’, function(lng, ns) {})：资源添加事件

五、react-i18next相关hook之useTranslation：获取函数组件中的 t 函数和 i18n 实例

1.基本使用

import i18n from "i18next";
import { initReactI18next } from "react-i18next";const resources = {zh_CN: {translation: {ok:'确认',common:{placeholder: '请输入'}},},en: {translation: {ok:'确定',common:{placeholder: 'Please enter'}},},
};i18n.use(initReactI18next).init({resources,lng: 'zh_CN',fallbackLng: 'zh_CN',interpolation: {escapeValue: false,},
});export default i18n;

import {useTranslation} from "react-i18next";const Home = () => {const {t,i18n} = useTranslation();console.log(t('ok'))return (<>{t('common.placeholder')}</>)
}export default Home;

2.配置命名空间

import i18n from "i18next";
import { initReactI18next } from "react-i18next";const resources = {zh_CN: {common:{placeholder: '请输入'},translation: {ok:'确认',},},en: {common:{placeholder: 'Please enter'},translation: {ok:'ok',},},
};i18n.use(initReactI18next).init({resources,lng: 'zh_CN',fallbackLng: 'zh_CN',ns: ['common'], // 定义命名空间数组defaultNS: 'translation', // 指定默认的命名空间interpolation: {escapeValue: false,},
});export default i18n;

import {useTranslation} from "react-i18next";const Home = () => {const {t} = useTranslation(['common','translation']);console.log(t('ok',{ ns: 'translation' })); //数组的第一个可以不传nsreturn (<>{t('placeholder')}</>)
}export default Home;

3.指定获取的前缀

import i18n from "i18next";
import { initReactI18next } from "react-i18next";const resources = {zh_CN: {common:{placeholder: '请输入'},translation: {ok:'确认',very: {deeply: {nested: {test: '测试'}}}},},en: {common:{placeholder: 'Please enter'},translation: {ok:'ok',very: {deeply: {nested: {test: 'test'}}}},},
};i18n.use(initReactI18next).init({resources,lng: 'zh_CN',fallbackLng: 'zh_CN',ns: ['common'], // 定义命名空间数组defaultNS: 'translation', // 指定默认的命名空间interpolation: {escapeValue: false,},
});export default i18n;

import {useTranslation} from "react-i18next";const Home = () => {const { t } = useTranslation('translation', { keyPrefix: 'very.deeply.nested' });return (<>{t('test')}</>)
}export default Home;

4.覆盖i18n实例

import i18n from './i18n';
const { t, i18n } = useTranslation('ns1', { i18n });

5.不使用 React Suspense 来处理翻译加载

const { t, i18n, ready } = useTranslation('ns1', { useSuspense: false });

6.使用方法：useTranslation(ns,options)。ns命名空间可以是字符串、数组；options配置如下

• i18n：i18next 实例，用于提供国际化功能。
• useSuspense：是否启用 React Suspense 模式来处理翻译加载。
• keyPrefix：键前缀，用于在翻译键前添加前缀。
• bindI18n：绑定 i18n 实例的方式，可以是字符串或 false。
• nsMode：命名空间模式，指定命名空间的加载方式，可以是 ‘fallback’ 或 ‘default’。
• lng：指定要使用的语言代码。

六、react-i18next高阶组件之withTranslation，服务端对应withSSR

1.基本使用

import {withTranslation} from "react-i18next";const Home = ({ t, i18n }) => {return (<>{t('ok')}</>)
}export default withTranslation()(Home);

2.指定命名空间获取

import {withTranslation} from "react-i18next";const Home = ({ t, i18n }) => {console.log(t('placeholder',{ns:'common'}))return (<>{t('ok')}</>)
}export default withTranslation(['translation','common'])(Home);

3.指定获取的前缀

import {withTranslation} from "react-i18next";const Home = ({ t, i18n }) => {return (<>{t('test')}</>)
}export default withTranslation('translation', { keyPrefix: 'very.deeply.nested' })(Home);

4.覆盖i18n实例

import i18n from './i18n';const ExtendedComponent = withTranslation('ns1')(MyComponent);<ExtendedComponent i18n={i18n} />

5.不使用 React Suspense 来处理翻译加载

const ExtendedComponent = withTranslation()(MyComponent);<ExtendedComponent useSuspense={false} />

七、react-i18next组件之Translation

1.基本使用

import {Translation} from "react-i18next";const Home = () => {return (<Translation>{(t, {i18n}) => <p>{t('ok')}</p>}</Translation>)
}export default Home;

2.指定命名空间获取

import {Translation} from "react-i18next";const Home = () => {return (<Translation ns={['translation','common']}>{(t, {i18n}) => <p>{t('placeholder',{ns:'common'})}</p>}</Translation>)
}export default Home;

3.指定获取的前缀

import {Translation} from "react-i18next";const Home = () => {return (<Translation ns='translation' keyPrefix='very.deeply.nested'>{(t, {i18n}) => <p>{t('test')}</p>}</Translation>)
}export default Home;

4.覆盖i18n实例

import i18n from './i18n';<Translation i18n={i18n}>
{(t, { i18n }) => <p>{t('my translated text')}</p> // will be looked up from namespace ns1
}
</Translation>

5.不使用 React Suspense 来处理翻译加载

import {Translation} from "react-i18next";const Home = () => {return (<Translation ns='translation' useSuspense={false}>{(t, {i18n}) => <p>{t('test')}</p>}</Translation>)
}export default Home;

6.相关属性

• children：一个函数，接受三个参数（翻译函数 t、选项对象和加载状态 ready），返回 React 节点。
• ns：命名空间，用于指定翻译内容所属的命名空间。
• i18n：i18next 实例，用于提供国际化功能。
• useSuspense：是否启用 React Suspense 模式来处理翻译加载。
• keyPrefix：键前缀，用于在翻译键前添加前缀。
• nsMode：命名空间模式，指定命名空间的加载方式，可以是 ‘fallback’ 或 ‘default’。

八、react-i18next组件之Trans

1.基本使用

import {Trans, useTranslation} from "react-i18next";const Home = () => {const { t } = useTranslation();return (<><Trans t={t}>ok</Trans><Trans t={t} i18nKey="ok"></Trans></>)
}export default Home;

2.指定命名空间获取

import {Trans, useTranslation} from "react-i18next";const Home = () => {const { t } = useTranslation(['translation','common']);return <Trans t={t} ns="common">placeholder</Trans>;
}export default Home;

3.覆盖i18n实例

import i18n from './i18n';<Trans t={t} i18n={i18n}>ok</Trans>

4.相关属性

• children：子元素内容，可以是一个或多个 TransChild 元素。
• components：自定义组件，可以是一个包含 React 元素的数组或对象，用于替换默认的标签渲染。
• count：用于处理复数形式的计数。
• context：上下文信息，用于指定翻译的上下文环境。
• defaults：默认翻译文本，用于指定在未找到翻译时的默认文本。
• i18n：i18next 实例，用于提供国际化功能。
• i18nKey：指定的翻译键或键数组。
• ns：命名空间，用于指定翻译内容所属的命名空间。
• parent：父组件，用于在 React.createElement 中创建元素时指定父组件。
• tOptions：翻译选项，用于传递给翻译函数的参数。
• values：变量值对象，用于替换翻译文本中的变量占位符。
• shouldUnescape：是否应解码转义字符。
• t：用于执行翻译的函数。

九、react-i18next组件之I18nextProvider：注入实例

import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';
import App from './App';<I18nextProvider i18n={i18n} defaultNS={'translation'}><App />
</I18nextProvider>

十、使用模板变量

1.lang.js

import i18n from "i18next";
import { initReactI18next } from "react-i18next";const resources = {zh_CN: {translation: {hello:'你好 {{text}}'},},en: {translation: {hello:'hello {{text}}'},},
};i18n.use(initReactI18next).init({resources,lng: 'zh_CN',fallbackLng: 'zh_CN',interpolation: {escapeValue: false,},
});export default i18n;

2.useTranslation 使用变量

import {useTranslation} from "react-i18next";const Home = () => {const {t,i18n} = useTranslation();let textToShow = '';if (i18n.language === 'zh_CN') {textToShow = t('hello', { text: '世界' });} else if (i18n.language === 'en') {textToShow = t('hello', { text: 'world' });}return (<>{textToShow}</>)
}export default Home;

3.withTranslation 使用变量

import {withTranslation} from "react-i18next";const Home = ({t,i18n}) => {let textToShow = '';if (i18n.language === 'zh_CN') {textToShow = t('hello', { text: '世界' });} else if (i18n.language === 'en') {textToShow = t('hello', { text: 'world' });}return (<>{textToShow}</>)
}export default withTranslation()(Home);

4.Translation 使用变量

import {Translation} from "react-i18next";const Home = () => {return (<Translation ns='translation' useSuspense={false}>{(t, {i18n}) => {let textToShow = '';if (i18n.language === 'zh_CN') {textToShow = t('hello', { text: '世界' });} else if (i18n.language === 'en') {textToShow = t('hello', { text: 'world' });}return <p>{textToShow}</p>}}</Translation>)
}export default Home;

5.Trans 使用变量

import {Trans, useTranslation} from "react-i18next";const Home = () => {const { t,i18n } = useTranslation();let textToShow = '';if (i18n.language === 'zh_CN') {textToShow = '世界';} else if (i18n.language === 'en') {textToShow = 'world';}return (<><Trans t={t} values={{ text: textToShow}}>hello</Trans></>)
}export default Home;