UMajs

国际化（i18n）

为了满足用户对于多语言应用的需求，本框架内置了国际化(I18n)支持

安装

$ npm install -S @umajs/plugin-i18n

开启服务

请参照插件使用说明开启国际化支持

// plugin.config.ts
export default {
    i18n: {
        enable: true,
        options: <i18nOptions>{
            defaultLocale: 'zh-cn',
        },
    },
}
1
2
3
4
5
6
7
8
9

具体开启方式请参考 plugin 一节中的配置方式

options

type i18nOptions = {
  defaultLocale?: string, // 默认语言             默认值：en-US
  queryField?: string, // 接收的query字段      默认值：locale
  cookieField?: string, // 存储的cookie字段     默认值：locale
  writeCookie?: boolean, // 是否写入cookie       默认值：true
  cookieMaxAge?: string, // cookie最大存储时间   默认值：1y
  cookieDomain?: string, // cookie的域名        默认值：''
  defaultDirName?: string, // 多语言文件夹名       默认值：i18n
  functionName?: string, // 自定义函数名         默认值：i18n
}
1
2
3
4
5
6
7
8
9
10

多语言文件

多语言独立配置成文件，默认放置于<root>/src/i18n/文件夹下（可配置 defaultDirName 进行更改），结构如下：

├── i18n
|   ├── zh-CN.js(ts)
|   ├── en-US.js(ts)
|   ├── ...
1
2
3
4
// en-US.js
export default function (template) {
    return {
        welcome: template`HAHA, ${0} ${'name'}!`,
        bye: template`goodbye, ${name}`,
        hi: 'nice to see you',
    };
}

// zh-CN.js
export default function (template) {
    return {
        welcome: template`哈哈, ${0} ${'name'}!`,
        bye: template`再见, ${name}`,
        hi: '很高兴见到你!',
    };
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
  • template 参数为模板处理函数，在插件初始化时会自动调用
  • 当需要使用自定义变量时，请使用 template 处理字符串模板
  • 自定义变量提供两种传递方式
    • number 占位符 --> ${0}
    • string 占位符 --> ${'name'}

获取多语言文本

统一使用context.i18n来获取多语言描述

// en-US.js
export default function (template) {
    return {
        name: template`hi, ${0} ${1}`,
        phone: template`phone: ${'phone'}`
        time: template`today is ${'week'} at ${0}`
        hi: nice to see you!
    };
}

ctx.i18n.name('Scarlett', 'Johansson')     ==> hi, Scarlett Johansson
ctx.i18n.phone({phone: 123456})            ==> phone: 123456
ctx.i18n.time('12:00am', {week: 'Sunday'}) ==> today is Sunday at 12:00am
ctx.i18n.hi                                ==> nice to see you!

// number占位符代表对应变量在调用时的参数位置（从0开始）
// 当使用string占位符时，调用时变量使用对象形式传递，置于参数的最后一位
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

BaseController 中使用

export default class Index extends BaseController {
  index() {
    const time = this.ctx.i18n.time('12:00am', { week: 'Sunday' })

    return Result.send(time)
  }
}
1
2
3
4
5
6
7

View 中使用

<!-- ejs -->
<title><%= ctx.i18n.hi %></title>
<p><%= ctx.i18n.phone({phone: 123456}) %></p>
1
2
3

切换语言

插件提供了三种方式供切换多语言，他们的优先级分别是：

query > cookie > header

  1. query: url/?i18n=zh-CN
  2. cookie: i18n=zh-CN （在一次请求后会自动将此种语言记录到 cookie）
  3. header: Accept-Language: zh-CN,zh;q=0.5

当以上三种方式在一次请求中都未设置，则 i18n 会选取默认语言（en-US）,可以通过配置进行修改，另外还提供了其他几项自定义配置，配置方法同插件使用方法

{
    defaultLocale: 'en-US', // 默认下使用的语言
    queryField: 'i18n',     // query字段名
    cookieField: 'i18n',     //    cookie字段名
    writeCookie: true,         // 是否自动写入cookie
    cookieMaxAge: '1y',         // cookie存储时间 <number>time(ms/s/m/h/d/w/y)
}
1
2
3
4
5
6
7

手动切换

某些特殊情况下如果需要手动设置语言，可调用ctx.setLocale方法

注意：手动切换仅对当前访问有效

/** query: i18n = en-US */
const en = ctx.i18n.hi // 'nice to see you!'
/** setLocale */
ctx.setLocale('zh-CN')
const zh = ctx.i18n.hi // '很高兴见到你!'
1
2
3
4
5