name: rc-intl zhName: 国际化文案解析 type: biz-component

@aliwind/rc-intl

帮助你的项目快速应用国际化和本地化。让开发者中不在代码耦合某一种语种。

安装

$ yarn add @aliwind/rc-intl

在 wind 项目中使用

• 在项目入口初始化文案

import intl from '@aliwind/rc-intl'

// 通过任何方式拿到当前用户的语言文案，比如由服务端将文案注入到window.messages中
const messages = {
  'app.title': 'English title',
}

intl.set({ messages })

• 在顶层组件外部包裹一层 HOC

import { render } from 'react-dom'
import { withProvider } from '@aliwind/rc-intl'

const App = withProvider()(OriginApp)
render(<App />, document.getElementById('app'))

• 在项目模块中使用 intl 进行国际化声明

import intl from '@aliwind/rc-intl'

const Title = () => <h1>{intl('app.title')}</h1>

export default Title

注意到，前端开发者在编写代码的时候，不再耦合于某一语种，而是依赖于一个“文案 key”，而文案id=>文案内容的配置在顶层统一完成。

基本使用

MDXInstruction:importDemo:BasicDemo

API

intl.set

设定国际化的基本环境变量

intl.set(data: IntlData, options: IntlOptions): void

IntlData

IntlData = {
  messages: Object,
  locale?: String,
}

• messages: 国际化需要的字典描述对象
• locale: BCP-47 locale 字符串

IntlOptions

IntlOptions = {
  determineLocale?: DetermineLocale,
}

• determineLocale: 确定 locale 自动获取的方式

  DetermineLocale = {
    globalIdentifier?: String|Array<String>,
    cookie?: String|Array<String>,
    html?: Boolean,
    navigator?: Boolean,
    fallback?: String,
  }

  • globalIdentifier: 从全局变量中获取 locale，这个获取逻辑是优先级最高的，如果该值是一个字符串，将会将该字符串作为全局变量的声明引用进行 locale 取值；如果该值为一个字符串数组，则会依次将数组中的字符串作为全局变量的声明顺序进行 locale 的取值，直到取得有效的值。如果 globalIdentifier 设置的值可以获取有效的 locale，则不再执行 cookie，html，navigator，fallback 的相关获取逻辑
  • cookie: 从 cookie 中获取 locale，当 globalIdentifier 未获取到有效的值时，将执行和 cookie 相关的获取处理逻辑。如果该值是一个字符串，将会将该字符串作为 cookie 的 key 进行 locale 取值；如果该值为一个字符串数组，则会依次将数组中的字符串作为 cookie 的 key 顺序进行 locale 的取值，直到取得有效的值。如果 cookie 设置的值可以获取有效的 locale，则不再执行 html，navigator，fallback 的相关获取逻辑
  • html: 从 html 标签中获取语言信息(lang)，当 globalIdentifier 和 cookie 都未获取到有效的 locale 值，且 html 的值为真值(truthy value)，则尝试从 html 标签中获取 lang 属性的值，如果可以获得有效的 lang 值，则将获取到的 lang 作为 locale 的值，不再执行后续的获取逻辑
  • navigator: 从 navigator.language 获取语言信息，当前面的获取逻辑均为获取到有效的 locale 值，且 navigator 的值为真值，则尝试从浏览器对象 navigator.language 中获取语言信息，如果可以获得有效的 language 的值，并将其作为 locale 的值，不再执行后续的获取逻辑
  • fallback: 如果从上述的获取逻辑中未去到任何有效的 locale 值，则将 fallback 指定的语言信息字符串作为当前的 locale 值

intl

输出字典对应 key 的信息

intl(key: String, values?: Object, preferString?: Boolean): String|ReactElement

初始化

首先我们先准备一个字典，并使用 intl.set 导入字典声明

locales/messages.js

export default {
  'app.title': '国际化控制台',
  'app.desc': '共有{count}个控制台使用了wind国际化功能',
  'app.desc.html': '共有<strong>{count, number}</strong>个控制台使用了wind国际化功能'
}

在字典定义中，变量可以用 { } 进行声明，并且在使用时进行赋值，关于更多的语法说明，可以参考

• ICU Message Syntax

initializer.js

import intl from '@aliwind/rc-intl'
import messages from './locales/messages'

intl.set({ messages })

在入口文件处引用初始化文件

app.js

import React from 'react'
import { render } from 'react-dom'
import './initializer'
import App from './App'

render(<App />, document.getElementById('app'))

使用 intl 输出字典值

在 App 中的任意模块都可以使用 intl 方法输出字典值

Title.js

import intl from '@aliwind/rc-intl'

const Title = () => (
  <h1>{intl('app.title')}</h1>
)

export default Title

使用模板变量

Desc.js

import intl from '@aliwind/rc-intl'

const Desc = ({ count }) => (
  <mark>{intl('app.desc', { count })}</mark>
)

export default Desc

在变量中使用 React 组件

模板变量可以传入 React 组件，来完成定制化的渲染需求，让我们对 Desc.js 进行一些修改，让 count 变量接受一个组件

Desc.js

import intl from '@aliwind/rc-intl'

const Desc = ({ count }) => (
  <mark>
    {
      intl('app.desc', {
        count: <strong>{intl.number(count)}</strong>
      })
    }
  </mark>
)

export default Desc

需要注意的是，如果字典中使用了 ICU 的格式化语法，如 I have {count, number} cats ，请不要在变量中传入组件

默认使用字符串作为国际化输出结果

与之前的 wind-intl 不同，使用 intl() 的返回结果默认是一个字符串，你可以在诸如 input.placeholder 等属性中直接使用

<Input placeholder={intl('app.title')} />

在以下两种情况下，使用 intl() 会返回一个 React 组件：

• 至少有一个变量值是 React 组件
• 强制指定 preferString 参数为 false

intl.html

将带有 html 标签的字典值输出成一段 html，该方法将始终返回一个 React 组件

intl.html(key: String, value?: Object): ReactElement

输出带有 html 标签的字典值

DescHtml.js

import intl from '@aliwind/rc-intl'

const DescHtml = ({ count }) => (
  <mark>{intl.html('app.desc.html', { count })}</mark>
)

export default DescHtml

intl.date

将时间日期进行本地化输出

intl.date(date: Date, options?: DateTimePresetFormat|Intl.DateTimeFormatOptions): String

DateTimePresetFormat

DateTimePresetFormat = String(
  'date',
  'time',
  'dateTime',
  'dateTimeWithTimeZone'
)

Intl.DateTimeFormatOptions

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

输出本地化的时间格式

CurrentDateTime.js

import intl from '@aliwind/rc-intl'

const CurrentDateTime = () => (
  <span>{intl.date(new Date())}</span>
)

export default CurrentDateTime

使用预设输出本地化的时间格式

@aliwind/rc-intl 默认提供三种时间预设：

• date : 只输出日期
• time : 只输出时间
• dateTime : (default) 输出日期和时间
• dateTimeWithTimeZone : 输出日期时间以及当前的时区

你可以以字符串的形式指定 intl.date() 的第二个参数，使用对应的预设方案

CurrentDateTime.js

import intl from '@aliwind/rc-intl'

const CurrentDateTime = () => (
  <span>{intl.date(new Date(), 'date')}</span>
)

export default CurrentDateTime

intl.number

将数字进行本地化输出

intl.number(value: Number, options?: Intl.NumberFormatOptions)

Intl.NumberFormatOptions

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat

输出本地化的数字格式

Counter.js

import intl from '@aliwind/rc-intl'

const Counter = ({ count }) => (
  <span>{intl.number(count)}</span>
)

export default Counter