super-project/docs/i18n.md

Base framework for Super Project.

# 多语言 (i18n)

## 配置方式

在执行构建方法时，传入 `i18n` 对象。例：

```javascript
// [构建文件] ./super.build.js

const superBuild = require('super-project/core/webpack/enter')

/*
 * 其他代码
 */

superBuild({
    /*
     * 其他配置对象
     */
    i18n: [
        ['zh-cn', './locales/zh-cn.json'],
        ['zh', './locales/zh.json'],
        ['en', './locales/en.json']
    ]
})
```

## 配置说明

`i18n` 对象有2种配置方法

### 简易配置

```javascript
const i18n = [
    ['zh-cn', './locales/zh-cn.json'],
    ['zh', './locales/zh.json'],
    ['en', './locales/en.json'],
    // [语言ID, 语言包JSON文件的相对路径]
]
```

### 高级配置

```javascript
const i18n = {
    // i18n模式，可选
    // 当前可用值：'default' || 'redux'
    // [默认值] prod环境：default | dev环境：redux
    type: 'default',
    
    // i18n方法名，可选
    // [默认值] __
    expr: '__',

    // cookie 中使用键值
    // [默认值] spLocaleId
    cookieKey: 'spLocaleId',

    // cookie 影响的域
    // [默认值] 无
    domain: '.domain.com',

    // 语言包，必填
    // 参照简易模式配置
    locales: [
        ['zh-cn', './locales/zh-cn.json'],
        ['zh', './locales/zh.json'],
        ['en', './locales/en.json'],
        // [语言ID, 语言包JSON文件的相对路径]
    ]
}
```

## 使用

在项目种，使用 `__(key[, key2, key3, ...[, { option1: value1 }])` 方法即可输出/渲染对应的多语言文本。方法名（默认为 `__`）可使用高级方式进行配置。

### 示例

```javascript
__('About')
__('timestamp_now', { time: Date.now() })
__('header.nav.home')
__('header.nav', 'home')
__('header', 'nav.home')
__('header', 'nav', 'home')
__('header', 'nav', 'home', { key: 'value' })
__('header', 'nav', currentKey)
__('header', 'nav', currentKey, { key: 'value' })
__('header', key1, key2)
```

### 选项

如果最后一个参数为 `Object` 则表示选项。语言包字符串种的 `${key}` 会使用对象内对应的元素进行替换，例：

```javascript
// 语言包
{
    "timestamp_now": "当前时间戳: ${time}"
}

// 使用
__('timestamp_now', { time: Date.now() })
```

### 多级

语言包JSON支持无限多级。在使用时，每一级之间可用 `.` 连接，或在 `__()` 方法中连续写入每一级的 key 值，例：


```javascript
// 语言包
{
    "header": {
        "nav": {
            "home": "Home",
            "About": "About Me"
        }
    }
}

// 使用
__('header.nav.home')
__('header.nav', 'home')
__('header', 'nav', 'home')
__('header', 'nav.home')
// 以上方法结果相同：Home
```

**注**：在 `default` 模式下使用多级模式时，`__()` 方法的第一个变量中尽量多的使用 `.` 连接，以得到最佳效果。如上例中推荐前2个使用方式。