Deprecated!!!

Please replace the current module with mp-i18n which supports the cross-miniprogram platform.

中文文档

Add internationalization features to WeChat miniprogram. Before using it, npm support must be enabled in the miniprogram project. Please refer to the official documentation for details.

Installation

$ npm install --save wx-i18n

Getting started

If you want to use remote mode, you must upload resources at first. At least one index file and page resource file inneed. The program will load the index file first when the program starts. The corresponding resource file will load when the page is loaded.

//init in app.js 
const { i18nConfig } = require('wx-i18n');
App({
  onLaunch: function () {
    const baseUrl ='https://raw.githubusercontent.com/fishen/assets/master/wx-i18n';
    const version ='1.0.0';
    i18nConfig.init({
      languages: ['cn', 'en'],
      language: 'cn',
      indexUrlFormat: `${baseUrl}/${version}/index.json`,
      textUrlFormat: option => `${baseUrl}/${version}/${option.hash}.json`,
    });
  }
})

// index.js
const { i18nLoad } = require('wx-i18n');
Page({
  onLoad: function () {
    i18nLoad(this)
      .then(() => console.log({
          texts: this.data.$t,
          currentLang: this.data.$lang,
          hello: this.data.$t.hello,
          welcome: this.$text('welcome'),
          text: this.$text('welcome', {hello: 'hi', world: 'wow'}),
          template: this.$template('{hello},{world}')
      }))
      .catch(console.error);
  }
})

<!--index.wxml-->
<view class="container">
  {{$t.hello}}, {{$t.world}}!
</view>

//output:
{
    "texts": {
      "hello": "你好",
      "world": "世界",
      "welcome": "{hello}，{world}。"
    },
    "currentLang": "cn",
    "hello": "你好",
    "welcome": "{hello}，{world}。",
    "text": "hi，wow。",
    "template": "你好,世界"
}

API

i18nConfig.init(cfg : object) : void

Initialization settings.

• language(optional,string): default language,default: 'zh_CN';

• languages(optional,array): full language list, default: ['zh_CN','en'];

• indexUrlFormat(string|function): the url of index resource;

• textUrlFormat(string|function): the url of the page or component resource;

  function param:

  • path: the path to the current page or component;
  • hash: the resource hash value from index;

• cachable(optional,boolean): enable to cache text resource, default: true;

• tmplVar(optional,string): variable name used in the template, default: '$t';

• langVar(optional,string): current language variable name, default: '$lang';

• storageKeyPrefix(optional,string): resource name prefix in storage, default: 'i18n';

---

example:

const { i18nConfig } = require('wx-i18n');
App({
  onLaunch: function () {
    i18nConfig.init({
      languages:["cn","en"],
      language:"cn",
      //string
      "indexUrlFormat":"https://localhost:8089/getIndex?version=1.0",
      //function
      "textUrlFormat":opt=>`https://localhost:8089/getTexts?path=${opt.path}`;
    });
  }
})

i18nLoad(page : Page | Component, option : object) : Promise<object>

Load the resources of a page or component asynchronously. This method has already called setData({$t:texts}), please do not repeat the call. If you want to change the template variable name, please modify the configuration options tmplVar.

• page : page or component object, in most cases, you can pass this to it.

• option(optional)

  • path : the path of the page or component, used in remote or all mode;
  • texts : raw resouces which include all language texts, used in memeory or all mode;
  • mode : specify the resource loading mode;
    • memory : use memory texts;
    • remote : use remote texts by http;
    • all : merge both memory and remote texts mode;

//index.js
const { i18nLoad, I18nMode } = require('wx-i18n');
const i18nTexts = require('./i18n');
Page({
  onLoad: function () {
    //remote mode, no need to specify any parameters
    i18nLoad(this).then(texts=>console.log(texts)).catch(console.error);
    //memory(local) mode
    i18nLoad(this,{texts:i18nTexts}).then(console.log).catch(console.error);
    //all mode
    i18nLoad(this,{texts:i18nTexts,mode:I18nMode.all}).catch(console.error);
    //custom path
    i18nLoad(this,{path:'home/home'}).catch(console.error);
  }
})

---

i18nMerge(texts : object) : object

Merge raw texts resources by the current language.

• texts : raw texts include multi language resources;

const { i18nMerge, i18nConfig } = require('wx-i18n');
const rawTexts={ zh_CN: { hello: '你好' }, en: { hello: "Hello" }};
const texts = i18nMerge(rawTexts);
console.assert(texts.hello === rawTexts[i18nConfig.language].hello);

page | component.$text(key : string, param : object) : string

Get the text corresponding to the specified name. If the current text is a template, format the template with the second parameter.

• key : resource key which value is a string template.
• param : the param to format template.

example:

const { i18nLoad } = require('wx-i18n');
Page({
  onLoad: function () {
    i18nLoad(this)
      //get text
      .then(()=>console.log(this.$text('hello')))
      //get template and format
      .then(()=>this.$text('welcome',{ hello:'你好', world:'世界 }))
      .then(welcome=>console.log(welcome))
      .catch(console.error);
  }
})

page | component.$template(template : string) : string

Format the custom template use texts resource. What's difference from the $text method is that the source of the template, the $text method template comes from the texts resource, and the $template method comes from the user.

• template : the template formatted by the texts.

example:

const { i18nLoad } = require('wx-i18n');

Page({
  onLoad: function () {
    i18nLoad(this)
      .then(()=>this.$template('{hello}, {wrold}.'))
      .then(welcome=>console.log(welcome))
      .catch(console.error);
  }
})

Resource structure

Index file

The file includes all path and version(hash value) info.

{
  "page or component path":"text resource hash value",
  "pages/home/home":"84b7f497e34e10725c4dfdf389e092b8",
  "pages/log/log":"30c481699e53cfc6b490be924ce7f4b8"
}

Page/Component text file

The file include multi language text resources

{
  "lang": {
    "key" : "value"
  },
  "zh_CN": {
    "hello":"你好",
    "world":"世界",
    "welcome":"{hello}，{world}。"
  },
  "en": {
    "hello" : "Hello",
    "world" : "World",
    "welcome":"{hello}, {world}."
  }
}