使用
引入panda npm包,需注意默认$i18n的翻译来自于的CDN资源,请在项目中先加载CDN的翻译语言包 **如需脱离语言包使用请参考下述PandaConfigProvider的使用
语言包格式
cdn url
https://assets-daily.cainiao-inc.com/upload/pack///lang.js https://cn.alicdn.com/upload/pack///lang.js
import $i18n from '@alife/panda-i18n'
支持的语种列表
zh-CN / en-US / ja-JP / ru-RU / pt-PT / fr-FR / es-ES ar-SA / as / bn-BD / bn-IN / bho / my-MM / zh-HK / zh-SG / zh-TW / cs-CZ / da-DK / nl-BE / nl-NL / en-BD / en-CA / en-CZ / en-FR / en-HU / en-ID / en-MY / en-MM / en-NP / en-PK / en-PH / en-PL / en-SG / en-ES / en-LK / en-TH / en-GB / en-VN / de-DE / gu / iw-IL / hi-IN / hu / in-ID / it-IT / kn / ko-KR / lo-LA / ms-MY / ml / mni / mr / ne-NP / or / pa / pl-PL / pt-BR / ro / sr / si-LK / sk-SK / sv-SE / tl-PH / ta / te / th-TH / tr-TR / uk-UA / ur-IN / ur-PK / vi-VN
翻译文案格式
{ 'en-US': { 'Hello': 'hello' }, 'zh-CN': { 'Hello': '你好' } ... }
ts表述
{ [lang in TLanauage]?: Record<string, string> }
$i18n
$i18n.get() 消费多语言翻译
/**
* @param {key:string | {id:string; dm:string; ns?:string}}
文案的key(id)以及默认翻译(dm) 或 文案key(key)
ns为namespace,用于创建i18n实例时,区分多实例,一般不关心
* @param {object} 可选参数,如果文案中存在变量
* @return {string} 根据语言环境渲染的文案
*/
$i18n.get("hello") // 你好
$i18n.get({"id":"hello",dm:"你好"}) // 你好
$i18n.get({
id: 'totalPage',
dm: '一共 {index} 页',
}, { index: 20}) // 一共20页
/** namespace的使用,主要用于组件内消费 */
$i18n.get({
id: 'hello',
dm: '你好',
ns: 'MyComponent'
}, { index: 20}) // 一共20页
$i18n.getLang() 获取当前语言环境
/**
* @return {string} 当前环境中的语种的值
*/
$i18n.getLang() // 'zh-CN' or 'en-US'
$i18n.setLang() 切换语言环境
/**
* @param {string} 当前需要切换的语种
* @return {void}
*/
$i18n.setLang('en-US')
withI18n
引入HOC方法,withI18n接受两个传参,第一个为需要包裹的组件,第二参数为语种翻译,HOC方法会将$18n方法挂载到组件的props参数中,组件即可在内部使用$i18n的函数 需注意该方法内置了next组件的ConfigProvider.config的实现,所以也同时直接传入ConfigProvider.config的options
import { withI18n } from '@alife/panda-i18n';
const Filter = (props) =>{
const { $18n } = props;
return (
<div>{$i18n.get({"id":"hello",dm:"你好"})}</div>
)
}
const Index = withI18n(
Filter, {
locale: {
"zh-CN":{
"hello":"你好"
},
"en-US":{
"hello":"hello"
}
}
});
export default Index;
Hooks
在withI18n包裹的组件中,将内置panda的上下文,所以可以在内部使用useI18n来使用该$i18n实例
import React from 'react';
import { useI18n } from '@alife/panda-i18n';
const MyComponent = () => {
const $i18n = useI18n();
return (<div>{$i18n.get({id: 'Hello', dm: '你好'}));
}
PandaConfigProvider
为了方便使用PandaConfigProvider内置了next组件的ConfigProvider和国际化语言,通过PandaConfigProvider内部的cn-next组件将直接可消费内置的国际化能力
import React from 'react';
import { Input } from 'cn-ui';
import { PandaConfigProvider } from '@alife/panda-i18n';
const MyComponent = () => {
return (<div><Input /></div>);
}
export default (
<PandaConfigProvider>
<MyComponent />
</PandaConfigProvider>
)
同时使用PandaConfigProvider也可以为自己内部注入$i18n实例,这样即可脱离语言包使用
import React from 'react';
import { Input } from 'cn-ui';
import { PandaConfigProvider, useI18n } from '@alife/panda-i18n';
const App = () => {
const $i18n = useI18n()
return (
<div>
{$i18n.get({id: 'Hello', dm: '你好'})}
</div>
);
}
export default
<PandaConfigProvider locale={{
"zh-CN":{
"Hello":"你好"
},
"en-US":{
"Hello":"hello"
}
}}>
<App />
</PandaConfigProvider>
)
setConfig
使用setConfig api可以配置panda的全局配置 使用setConfig 保持在应用渲染之前执行,保证panda的配置在渲染时即可生效
import { setConfig } from '@alife/panda-i18n';
setConfig({
logLevel: 0
})
...
option | default | description |
---|---|---|
logLevel | 2 | 控制台输出 0 关闭所有 1 仅error 2 error&warn ,默认2 |
cookieKey | ||
自定义cookieKey(优先级高于CDN语言包设置) | ||
langList | 设置全局生效的语种列表,如环境语种不在列表中将把第一个作为默认的语种 |
进阶使用说明
init
使用init api可创建一个$i18n的实例
option | default | description |
---|---|---|
locale | ||
文案翻译 | ||
lang | ||
自定义cookieKey(优先级高于CDN语言包设置) | ||
langList | 设置全局生效的语种列表,如环境语种不在列表中将把第一个作为默认的语种 | |
componentName |
多实例
当前$i18n的处理为多实例的方案处理,默认输出的为cdn的实例,即可获取panda平台的发布的cdn中的文案 可使用 $i18n.init 的api生成一个实例,即可使用$i18n所有的能力 当使用_PandaConfigProvider_时为在内部生成一个context作用域,内部可使用 useI18n 获取生成$i18n实例 当使用 _**withI18n _为组件进行hoc包裹时,也会生成一个基于组件配置的实例,内部可使用props中获取该实例,也可使用 useI18n **获取该实例
语种选择
panda环境语种由多个值的选择决定
- lang 初始化配置
- urlSearch URL的seach中的lang参数
- cookie 默认为x-hng的语种,或用户设置的cookieKey
- defaultLang 默认的语种
- DEFAULT_LANG 特指中文
权重:
lang > userSearch > cookie(default) > cookie(custom) > defaultLang > DEFAULT_LANG
_如果用户在 __setConfig _设置的langList(生效的语种) 当筛选出当前的语种时无法在langList找到时,会使用langList的第一个语种作为当前环境语种,保证语种一定在支持的语种列表中