@cainiaofe/panda-i18n-lite

使用

引入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的第一个语种作为当前环境语种，保证语种一定在支持的语种列表中