koa-i18n-next

i18n middleware based on koa2. Support typescript project and ejs template!

Install

npm install koa-i18n-next

// or

yarn add koa-i18n-next

Options

| props | type | default | required | remark | | :-----------: | :-------------: | :-----: | :------: | ----------------------------- | | dirPath | string | | Yes | Languages folder path | |fallbackLocale | string | | Yes | To choose which language to use When the language file or language is not matched | | modes | Modes[] | | YES | How to get the current requested language, For detailed parameters, see Modes type below | | preload | string[] | | False | Language files that need to be preloaded, it is not recommended to set too many languages |

type Modes = 'query' | 'subdomain' | 'cookie' | 'header' | 'tld' | Function;

// The priority of acquiring languages is arranged according to the order of the array. If none of them are acquired, the language set by fallbackLocale will be used.
modes = [
  'query',                //  optional detect querystring - `/?locale=en-US`
  'subdomain',            //  optional detect subdomain   - `zh-CN.koajs.com`
  'cookie',               //  optional detect cookie      - `Cookie: locale=zh-TW`
  'header',               //  optional detect header      - `Accept-Language: zh-CN,zh;q=0.5`
  'tld',                  //  optional detect tld(the last domain) - `koajs.cn`
  function(ctx) {         //  optional custom function (will be bound to the koa context)
    return ctx.request.header['lang'] || 'en'
  }
]

Props

Get the language in the context

1. Router

router.get('/', async (ctx) => {
  ctx.body = {
    locale: ctx.state.$locale // ==> or ctx.$locale
  }
})

2. Ejs

<h1><%= $locale %></h1>

Methods

// @param key: The key corresponding to the text in the language file
// @param data?: What needs to be replaced dynamically, Array or object can be passed in
$t: (key: string, data?: string[] | {[props:string]: string}) => string;

// example1
// { testWords: 'This is [0] test words[1]' }
ctx.$t('testWords', ['a', '!']) // ==> This is a test words!

// example2
// { testWords: 'This is {number} test words{punctuation}' }
ctx.$t('testWords', {number: 'a', punctuation: '!'}) // ==> This is a test words!

How to use?

See the example

Use in Ejs template

html template

<h1><%= $t('test') %></h1>  

render template

router.get('/template', async (ctx) => {
  ctx.render('template')
})

Use in router

router.get('/api', async (ctx) => {
  ctx.body = {
    message: ctx.$t('test')
  }
})

use KoaI18nNext middleware

const path = require('path');
const Koa = require('koa');
const KoaRouter = require('koa-router');
const koaViews = require('koa-views');
const koaI18nNext = require('../index');

const app = new Koa();

app.use(koaI18nNext({
  dirPath: path.join(__dirname, './locales'), // 国际化文案文件夹(语言文件仅支持json格式)
  fallbackLocale: 'en', // 未匹配到语种时使用什么语言代替
  preload: ['en', 'zh'], // 第一次通过中间件时预加载的语种，不宜添加过多，添加经常使用的语种即可
  modes: [
    'query',                //  通过 url query 获取 - `/?locale=en-US`
    'subdomain',            //  通过二级域名获取   - `zh-CN.koajs.com`
    'cookie',               //  通过cookie获取      - `Cookie: locale=zh-TW`
    'header',               //  通过header头的accept-language获取      - `Accept-Language: zh-CN,zh;q=0.5`
    'tld',                  //  通过国际域名获取，此案例为cn - `koajs.cn`
    function(ctx) {         //  通过自定函数获取，返回语种 (ctx为app context)
      return ctx.request.header['lang'] || 'en'
    }
  ], // 获取语种的方式，获取语种的优先级根据数组顺序排列，取到白名单语种为止，如果均没有获取到，则使用fallbackLocale设置的语种
}))

// 模版引擎
// https://github.com/mde/ejs
app.use(
  koaViews(path.join(__dirname, './template'), {
    extension: 'ejs',
  }),
);

const router = new KoaRouter();

router.get('/api', async (ctx) => {
  ctx.body = {
    message: ctx.$t('test')
  }
})

router.get('/', async (ctx) => {
  await ctx.render('error')
})

// 初始化路由配置
// https://github.com/koajs/router
app.use(router.routes());




app.listen(3000, () => {
  console.log('serve start success!');
  console.log('http://localhost:3000?locale=zh-tw');
  console.log('http://localhost:3000/api?locale=en');
})