您的位置:58脚本 > 小程序 国际化 微信小程序 工具库类·国际化

小程序 国际化 微信小程序 工具库类·国际化

2023-03-14 23:32

小程序 国际化 微信小程序 工具库类·国际化

小程序 国际化

小程序国际化是指将小程序的内容、功能和界面本地化,以适应不同语言和文化的用户。它是一种技术,可以帮助开发者将其小程序扩展到全球市场,从而获得更多的用户。

小程序国际化的主要目标是使用户能够在不同语言和文化中流畅地使用小程序。这意味着开发者必须考虑到不同语言和文化中的文字、图片、声音、功能和界面。

// 将文字本地化 
let language = 'zh-CN';  // 语言 
let text = {  // 文字 
    'zh-CN': '你好', 
    'en-US': 'Hello' 
}; 
console.log(text[language]); // 输出你好或者Hello  

为了实现小程序国际化,开发者必须对其代码进行重构:将所有文字、图片、声音和功能都放入一个单独的文件中(例如JSON文件);然后根据用户所选择的语言来加载相应的内容。上述代码片段显示了如何将文字本地化。

此外,开发者还必须考虑到不同语言之间的日期格式、数字格式和时间格式差异。例如:中国使用“年/月/日”作为日期格式;而在美国则使用“月/日/年”作为日期格式。

此外,小程序国际化还要考虑到不同语言之间的界面差异。例如:中国使用“左到右”作为书写方向;而在伊斯兰教徒国家则使用“从右到左”作为书写方向。

总之:小程序国际化是一个复杂耗时的过程;但是它也是一个重要步骤——它可以帮助开发者将其小程序扩展到其他市场并收集更多的电子商务流量。

微信小程序 工具库类·国际化

快速入门

概览

miniprogram-i18n 的用法主要分为四部分。分别是:构建脚本与i18配置、i18n文本定义、WXML中的用法及JavaScript中的用法。

安装

该方案目前需要依赖 Gulp 并且对源文件目录结构有一定的要求,需要确保小程序源文件放置在特定目录下(例如 src/ 目录)。

  1. 首先在项目根目录运行以下命令安装 gulp 及 miniprogram-i18n 的 gulp 插件。
npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml
  1. 在小程序运行环境下安装国际化运行时并在开发工具"构建npm"。
npm i -S @miniprogram-i18n/core
  1. 在项目根目录新建 gulpfile.js,并编写构建脚本,可参考 examples/gulpfile.js。
更多 Gulp 相关配置请参考 Gulp插件配置文档。

使用

i18n文本定义

miniprogram-i18n 目前采用 JSON 文件对 i18n 文本进行定义。使用之前,需要在项目源文件下新建 i18n 目录。

目录结构如下:

├── dist               // 小程序构建目录
├── gulpfile.js
├── node_modules
├── package.json
└── src                // 小程序源文件目录
|   ├── app.js
|   ├── app.json
|   ├── app.wxss
|   ├── i18n           // 国际化文本目录
|   |   ├── en-US.json
|   |   └── zh-CN.json

i18n 目录可以放置在源文件目录下的任意位置,例如可以跟 Page 或 Component 放在一起。但是需要注意的是,多个 i18n 目录下的文件在构建时会被合并打包,因此如果翻译文本有重复的 key 可能会发生覆盖。如果分开多个 i18n 目录定义需要自行确保 key 是全局唯一的。例如使用 page.index.testKey 这样的能确保唯一的名称。

下面我们定义文本:

// i18n/en-US.json
{
  "plainText": "This is a plain text",
  "withParams": "{value} is what you pass in"
}
// i18n/zh-CN.json
{
  "plainText": "这是一段纯文本",
  "withParams": "你传入的值是{value}"
}

WXML 中的用法

定义好 i18n 文本之后,就可以在 WXML 文件里使用了。首先,需要在 WXML 文件对应的 JavaScript 文件里引入国际化运行时。

// pages/index/index.js
import { I18n } from "@miniprogram-i18n/core"

Component({
  behaviors: [I18n]
})
注意:这里建议 Page 以及 Component 都采用 Component 构造器进行定义,这样可以使用 I18n 这个 Behavior。如果需要在 Page 构造上使用 I18n 则需要引入 I18nPage 代替 Page 构造器。

接着可以在 WXML 文件中获取预先定义好的 i18n 文本。

<!-- pages/index/index.wxml -->
<view>{{ t("plainText") }}</view>
<input placeholder="{{ t("withParams", {value}) }}"></input>

在 WXML 中使用 t 函数(或其他你指定的函数名)来获取文本。 t函数签名如下:

t(key: string, params: object)

它可以接受两个参数,第一个参数是 i18n 文本的 key,第二个参数是需要传入的插值对象(可以是从 AppService 传过来的值)。

JavaScript 中的用法

在 JavaScript 里可以直接引用 @miniprogram-i18n/core 这个 NPM 包来获取翻译文本。

import { getI18nInstance } from "@miniprogram-i18n/core"

const i18n = getI18nInstance()

Component({
  attached() {
    const text = i18n.t("withParams", { value: "Test" })
    console.log(text)    // Test is what you pass in
    i18n.setLocale("en-US")
  }
})

同样的,在 i18n 实例上,还暴露了其他一些接口,例如获取当前语言、动态设置当前语言等。具体接口请参考 接口文档。

如果你的 JavaScript 对应的 WXML 里已经使用了国际化文本,换言之,即 Component 构造器已经引入了 I18n Behavior,那么所有的实例方法都会被直接挂载到 this 上,你可以通过 this 调用它们。

import { I18n } from "@miniprogram-i18n/core"

Component({
  behaviors: [I18n],
  attached() {
    const text = this.t("withParams", { value: "Test" })
    console.log(text)    // Test is what you pass in
    this.setLocale("en-US")
  }
})

构建

在编写完 i18n 文本并在 WXML 或 JavaScript 中调用之后,你需要运行 gulp 命令对 .wxml 文件进行转译并对 i18n 文本进行打包合并。

特性

目前 miniprogram-i18n 仅支持纯文本及文本插值,后续会对其他 i18n 特性进行支持。

文本插值

{
  "key": "Inserted value: {value}"
}
i18n.t("key", { value: "Hello!" })  // Inserted value: Hello!

为了方便调用深层嵌套的对象,当前支持使用 . 点语法来访问对象属性。

{
   "dotted": "Nested value is: { obj.nested.value }"
}
const value = {
  obj: {
    nested: {
      value: "Catch you!"
    }
  }
}
i18n.t("dotted", value)  // Nested value is: Catch you!

select 语句

{
  "key": "{gender, select, male {His inbox} female {Her inbox} other {Their inbox}}"
}
i18n.t("key", { gender: "male" })    // His inbox
i18n.t("key", { gender: "female" })  // Her inbox
i18n.t("key")                        // Their inbox

select 语句支持子语句文本插值:

{
  "key": "{mood, select, good {{how} day!} sad {{how} day.} other {Whatever!}}"
}
i18n.t("key", { mood: "good", how: "Awesome"  })  // Awesome day!
i18n.t("key", { mood: "sad", how: "Unhappy"  })   // Unhappy day.
i18n.t("key")                                     // Whatever!
注:select 语句支持子句嵌套 select 语句

其他尚未支持的特性有:

  • Pseudo 字符串
  • 单复数处理
  • 日期、数字、货币处理
  • 定义文件的命名空间
  • 支持 WXML 与 JavaScript 独立定义

接口文档

miniprogram-i18n API 是运行时在 JavaScript 侧操作 i18n 的接口。

接口列表

  • initI18n(localesConfig: object): I18n
  • getI18nInstance(): I18n
  • t(key: string, params: object): string
  • getLocale(): string
  • setLocale(currentLocale: string): void
  • getFallbackLocale(): string
  • onLocaleChange(handler: (currentLocale: string) => void): object

初始化 I18n 运行时

initI18n(localesConfig: object): I18n

在 app.js 调用 initI18n 来加载 i18n 文本并指定默认语言。若未进行指定,i18n运行时将默认从 /i18n/locales.js 中读取文本及配置。

// src/app.js
import { initI18n } from "@miniprogram-i18n/core"
import locales from "/i18n/locales.js"

initI18n(locales)

App({})

获取 I18n 运行时

getI18nInstance(): I18n

该接口会返回 I18n 运行时实例。

import { getI18nInstance } from "@miniprogram-i18n/core"

const i18n = getI18nInstance()
i18n.t("key")

I18n 接口

以下五个接口用来获取或操作 I18n,均可在 I18n 实例或 拥有 I18n Behavior 的组件或 I18nPage 上进行调用。 通过组件直接访问成员函数:

import { I18n } from "@miniprogram-i18n/core"
Component({
  behaviors: [I18n],

  attached() {
    this.t("key")
    this.getLocale()  // en-US
    this.setLocale("zh-CN")
    this.getFallbackLocale()  // zh-CN
    this.onLocaleChange((currentLocale) => {
      console.log("Locale changed to", currentLocale)
    })
  }
})

或从 I18n 实例调用:

import { I18n } from "@miniprogram-i18n/core"

const i18n = getI18nInstance()

i18n.t("key")
i18n.getLocale()  // en-US
i18n.setLocale("zh-CN")
i18n.getFallbackLocale()  // zh-CN
i18n.onLocaleChange((currentLocale) => {
  console.log("Locale changed to", currentLocale)
})

t(key: string, params: object): string

最主要的翻译函数,通过该函数可以获得预先定义的 i18n 文本。

getLocale(): string

获取当前设置的语言。默认语言应在 gulp 构建脚本中配置,详见 Gulp插件配置文档。

setLocale(currentLocale: string): void

设置当前语言。该值应与 i18n 定义文件名相对应。

getFallbackLocale(): string

获取备选语言。该值在构建脚本中进行配置,一旦设置之后无法在运行时通过接口修改。详见 Gulp插件配置文档。

onLocaleChange(handler: (currentLocale: string) => void): object

当前语言被修改时触发的事件回调。返回值 object,可通过返回值对象取消事件监听。

const event = i18n.onLocaleChange(() => {})
event.off()

Gulp 插件配置文档

miniprogram-i18n 在构建阶段依赖两个 Gulp 插件,分别是 @miniprogram-i18n/gulp-i18n-wxml 和 @miniprogram-i18n/gulp-i18n-locales,gulp-i18n-wxml 负责转译 wxml 文件中的 i18n 自定义语法,gulp-i18n-locales 则负责合并 i18n 定义文件,并进行预处理生成运行时所需的文件。

若使用 CLI 进行构建,则可忽略 Gulp 构建的配置。

安装

因此在使用 i18n 的构建插件之前,需要先安装相关依赖。

npm i -D gulp @miniprogram-i18n/gulp-i18n-locales @miniprogram-i18n/gulp-i18n-wxml

依赖安装完成之后,需要建立 gulp 所需的配置并引入 i18n 构建插件。示例如下:

const gulpWxmlTransformer = require("@miniprogram-i18n/gulp-i18n-wxml")
const gulpLocalesLoader = require("@miniprogram-i18n/gulp-i18n-locales")

function transpileWxml() {
  return src("src*.wxml")
    .pipe(gulpWxmlTransformer())
    .pipe(dest("dist/"))
}
function mergeAndGenerateLocales() {
  return src("srci18n/*.json")
    .pipe(gulpLocalesLoader({ defaultLocale: "zh-CN", fallbackLocale: "zh-CN" }))
    .pipe(dest("dist/i18n/"))
}

更详细的配置请参考 examples。

gulp-i18n-wxml 配置

该构建函数支持如下参数:

interface Options {
  wxsPath: string,
  wxsModuleName?: string,
  i18nFunctionName?: string,
}
  • wxsPath指定 locales.wxs 所在路径,应与 gulp-i18n-locales 中的配置一致,默认为 src/i18n/locales.wxs。
  • wxsModuleName指定 wxs 模块名称,默认为 i18n。
  • i18nFunctionName指定 wxml 中的 i18n 函数名,默认为t,可修改为任意合法的函数名。

gulp-i18n-locales 配置

该构建函数支持如下参数:

interface Options {
  wxsFileName?: string
  jsFileName?: string
  defaultLocale?: string
  fallbackLocale?: string
}
  • wxsFileName指定 locales wxs 文件名,需以 .wxs 作为后缀,默认为 locales.wxs。
  • jsFileName指定 locales js 文件名,需以 .js 作为后缀,默认为locales.js。
  • defaultLocale指定默认语言,默认为 en-US。该值需与 i18n 定义文件名对应。
  • fallbackLocale指定备选语言,默认为 en-US。该值需与 i18n 定义文件名对应。在运行时无法找到对应语言下的文本时,会从备选语言中进行查找。注:该值无法在运行进行修改。


阅读全文
以上是58脚本为你收集整理的小程序 国际化 微信小程序 工具库类·国际化全部内容。
声明:本站所有文章资源内容,如无特殊说明或标注,均为采集网络资源。如若本站内容侵犯了原著者的合法权益,可联系本站删除。
相关文章
© 2024 58脚本 58jiaoben.com 版权所有 联系我们
桂ICP备12005667号-28 Powered by CMS