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

react国际化配置react-i18next详解

article 2025/2/13 2:45:43

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' })); //数组的第一个可以不传ns
    return (<>{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;

http://www.kler.cn/a/542889.html

相关文章：

  • vscode怎么更新github代码
  • 软件工程-软件需求分析基础
  • Unity Shader Feature
  • 使用 Nginx 搭建代理服务器（正向代理 HTTPS 网站）指南
  • Games202 Lecture11 LTC | Disney principled BRDF | NPR
  • kafka生产者之发送模式与ACK
  • 使用WebUI访问本地Deepseek（Ollama集成Open WebUI）
  • office 365 更新后打不开word问题
  • depcheck检查node.js项目中未使用和缺失依赖的工具
  • 免费在腾讯云Cloud Studio部署DeepSeek-R1大模型
  • encodeURI()，encodeURIComponent()区别
  • AF3 gdt函数解读
  • nginx安装并部署前端项目【包括Linux与Windows系统】
  • 前端性能分析常见内容
  • C语言蓝桥杯1003: [编程入门]密码破译
  • 香港中文大学 Adobe 推出 MotionCanvas：开启用户掌控的电影级图像视频创意之旅。
  • 基于Springboot（Maven项目）——分页
  • 在 debian 12 上安装 mysqlclient 报错
  • 代码随想录--977有序数组的平方
  • Java Stream 全面解析
  • 使用EVE-NG-锐捷实现三层数据通信
  • 曝苹果2026年秋季推首款折叠iPhone
  • Git 安全与权限管理
  • 深入探索现代CSS：从基础到未来趋势
  • 128，【1】buuctf [极客大挑战 2019]PHP
  • 浅谈自己对RPC的理解