I18n

// @namespace I18n
import { I18n } from 'rcfm'

Custom Types

@typedef {Object} I18nInstance
@description - 国际化实例

Exception Types

@type {ExceptionInstance}
@description - 不是合规的实例

@prop {string} type = "I18N_NOT_AN_INSTANCE_OF_I18N"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 不支持的语言配置

@prop {string} type = "I18N_UNSUPPORTED_LOCALE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

Class Properties

.global

内置的一个全局 I18n 实例。

// @example
const globalI18n = I18n.global

Class Methods

.create()

创建一个国际化实例。

// I18n.create()
// @returns {I18nInstance}

// @example
const i18n = I18n.create()

.isI18n()

判断入参是否是一个异常实例。

// I18n.isI18n(arg)
// @param {*} arg - 任意参数
// @returns {boolean} - 当入参是 I18nInstance 时返回 true，否则返回 false

// @examples
I18n.isI18n(I18n.create()) // true
I18n.isI18n({}) // false

.isntI18n()

判断入参是否不是一个异常实例。

// I18n.isntI18n(arg)
// @param {*} arg - 任意参数
// @returns {boolean} - 当入参是 I18nInstance 时返回 false，否则返回 true

// @examples
I18n.isntI18n(I18n.create()) // false
I18n.isntI18n({}) // true

.mustbeI18n()

当入参不是一个异常实例时抛出异常。

// I18n.mustbeI18n(arg, message)
// @param {*} arg - 任意参数
// @param {string} [message] - 自定义异常对象消息
// @returns {undefined}

// @examples
I18n.mustbeI18n(I18n.create())
I18n.mustbeI18n({}) // Throws an I18N_NOT_AN_INSTANCE_OF_I18N exception.

Instance Methods

#define()

定义一个或多个语言配置模板，或查看语言配置。

// i18n#define(path, template)
// @param {Object|string} [path] - 语言配置完整路径或一个包含配置路径及配置模板的对象
// @param {string} [template] - 语言配置模板，当 path 为 string 时必需
// 支持模板变量，被 {} 包裹的变量可在调用 #translate 和 #try 方法时被替换。
// @returns {undefined|Object} - 当不传如参数时，返回语言配置对象。

// @example - 定义一个语言模板
i18n.define('en.hello', 'Hello there~')

// @example - 定义一个包含变量的语言模板
i18n.define('en.hello', 'Hello { name }~')

// @example - 一次性定义多个语言模板
i18n.define({
  en: {
    hello: 'Hello { name }~',
    bye: 'Bye { name }~'
  },
  zh: {
    hello: '你好 { name }~',
    bye: '再见 { name }~'
  }
})

// @example - 查看语言配置
// returns -
// {
//   en: {
//     hello: 'Hello { name }~',
//     bye: 'Bye { name }~'
//   },
//   zh: {
//     hello: '你好 { name }~',
//     bye: '再见 { name }~'
//   }
// }
i18n.define()

#locale()

切换语言。

// i18n#locale(lang)
// @param {string} lang - 语言模板顶级路径，通常为语言标记缩写
// @returns {undefined}

// @example - 切换语言为中文
i18n.locale('zh')
i18n.t('hello', {variables: {name: 'Jerry'}}) // 你好 Jerry~

#translate()

获取语言模板并替换其中的变量。

方法别名 #t()

// i18n#translate(path, options)
// @param {string} path - 模板路径，不需要拼接语言顶级路径
// @param {Object} [options = {}]
// @prop {Object} [options.variables = {}] - 需要被替换的模板变量
// @returns {string}

// @examples
i18n.t('hello', {variables: {name: 'Jerry'}}) // Hello Jerry~
i18n.translate('hello', {variables: {name: 'Jerry'}}) // Hello Jerry~

#try()

尝试从多个路径查找语言模板，返回使用第一个查找到的模板，并替换变量。

// i18n.try(paths, options)
// @param {string} paths - 模板u经数组，不需要拼接语言顶级路径
// @param {Object} [options = {}]
// @prop {Object} [options.variables = {}] - 需要被替换的模板变量
// @returns {string}

// @examples
i18n.try(['hi', 'hello'], {variables: {name: 'Jerry'}})  // Hello Jerry~
i18n.try(['warning', 'error']) // ''