微信小程序-國際化(miniprogram-i18n)

前情提要

　　最近維護了一個微信小程序的老項目，維護的其中一項是添加國際化。由于踩了蠻多坑，所以就有了這篇文檔?。。?/span>

miniprogram-i18n

　　對除小程序外的其他框架開發做過國際化的朋友來說i18n這幾個字母應該不陌生，i18n之所以叫i18n是因為次單詞長度為20，以i開頭以n結束，i和n之間間隔18位。

國際化全流程及踩坑

首先，在小程序項目中引入依賴。官方文檔上有依賴安裝位置及文件關系，詳情可點擊miniprogram-i18n查看，簡單理解為，在小程序根目錄下使用命令行安裝依賴

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

??這一步做了什么呢？

安裝了gulp、和miniprogram-i18n的gulp插件。

??為什么要安裝這些呢？

為了打包生成翻譯文件以及編譯`.wxml`文件。

??為什么要打包呢？

這就是一個需要了解國際化原理的問題了，我將其理解為：在打包之前，我們寫的語言翻譯配置文件與頁面還沒有真正地聯系起來，打包之后會生成一個`locales.js`和`locales.wxs`文件，配合`gulp-i18n-xml`插件將`.wxs`引入到每一個頁面中，這樣才能真正的實現頁面翻譯。

??為什么要用`gulp-i18n-xml`打包`.wxml`文件呢？

因為按照官方時使用指南，我們在頁面的使用中直接是`{{t('key')}}`這樣的方式進行文本翻譯的，然而真正實現國際化的`.xml`寫法的語句是`<wxs src="生成的locale.wxs文件路徑" module="i18n"/> <view>{{i18n.t('key', $_locale)}}</view>`這樣的。也就是說，使用此插件可以自動為`.wxml`引入`.wxs`并且將翻譯的文本轉換為實現所需要的格式，如此可以減少開發者的代碼編寫數量。

??一定要使用`gulp-i18n-xml`才能實現翻譯嗎？

不是。如上所說，此插件實際上只是減少開發者的代碼編寫數量，如果開發者手動引入文件，并在使用時以`i18n.t('key', $_locale)`這樣的形式實現文本翻譯時，即可不用此插件。

順便一說，如果要直接使用此插件生成翻譯文件，那幾乎是將現有文件完全生成一份新的到目標文件夾下，項目發布時，直接發布打包后的文件到生產。這對于從0開始的項目來說這并沒有什么影響甚至能減少開發者工作量（也許），但如果是維護老項目的話，此舉可能并不是明智的。

??如果使用`i18n.t('key', $_locale)`的形式實現，引入的文件從哪里獲得呢？

前面說過，打包之后會生成一個`locales.js`和`locales.wxs`文件，引入的就是此`locales.wxs`文件。

??完全交由gulp工具打包需要注意什么呢？

如果是維護老項目，那么目錄結構一般都是`pages、app.js、app.json、app.wxss、otherFolders/頁面文件（夾），此時打包需要注意將同級目錄每一個需要的文件都copy一份到目標文件夾下，并注意路徑。如果是新項目可以將需要打包的文件全部放置于一個src文件夾內（注意：需要的文件多半還包括package.json，也就是src文件夾內外部可能都需要一個package.json文件,可參照官方example的目錄結構搭建）。

注意：如果沒有將`node_modules`或`miniprogram_npm`打包到目標文件夾下，需要在目標文件夾下執行`npm i`和`構建npm`

根據官方文檔和example可以發現，官方打包前的文件目錄結構是app.js/json/wxs以及page、i18n、靜態資源文件夾等都由一個src文件夾包裹著，gulp配置文件中將i18n交由`gulp-i18n-locale`處理，wxml文件交由`gulp-i18n-xml`處理，src目錄下的其他文件全部copy到目標目標生成文件夾下。

上一步我們已經往安裝了依賴，現在需要在小程序中使用工具構建npm，如此才能在小程序js文件中成功引用依賴。

`工具`->`構建npm`

??構建npm出錯？

可能的原因是：未成功安裝依賴，可以先卸載依賴再安裝；當前構建npm的位置沒有package.json文件；

上一步我們已經往小程序中注入了依賴，接下來就是如何使用的問題。通過官方文檔可以直到需要在i18n文件夾內新建語言配置的json文件（比如en-US、zh-CN)

// en
{
  "hello": "Hello"
}
// zh
{
  "hello": "你好"
}

　　　然后在需要使用國際化的頁面的js中

...
import { I18n } from '@miniprogram-i18n/core';
Component({
  behaviores: [I18n]
})

　　　頁面使用

<view>{{t('hello')}}</view>
<view>{{t('day', {day: '12'})}}</view>

　　??必須要用Component嗎？

　　　　我們在小程序官方文檔發現`behaviors`是Component構造器所有的，那么如果當前是Page怎么辦呢？國際化官方文檔中建議都使用Component構造器定義，否則就需要引入I18nPage代替Page構造器。然而在實踐中發現直接在Page構造器中直接使用`behaviors`并不會報錯，i18n也能被正確引入（直到2022/01/19）。當然這只是針對維護老項目而言，也許這樣做存在系列潛在風險，出于安全考慮，在使用Component構造器或者I18nPage都方便的前提下，最好還是不要嘗試以上的方法。

　　??為什么照官方文檔做了，還是不能正常翻譯?

　　　　如果在控制臺看到這樣的報錯：

　　　　根據以上報錯，提示我們在使用I18n之前確保在app.js文件中運行了initI18n()?；仡櫸覀冎暗牟僮?，沒見過也沒有運行過這一函數。不必驚慌，導致這一錯誤并不完全是我們的問題，因為官方的快速開始文檔里確實沒有對這一步的相關描述（不過在接口文檔里有描述）。

　　按照控制臺報錯，我們在app.js中執行InitI18n()

...
import { initI18n } from '@miniprogram-i18n/core'
initI18n('en-US')
App({
  ...
})

　　再檢查頁面，此時翻譯文本就正常顯示了，并且控制臺不再有出現上面描述的錯誤

為什么官方的select，我不能成功使用？

　　截止2022/01/19，本人尚未成功使用過select。根據文檔，我想文檔中特性部分的`目前 miniprogram-i18n 僅支持純文本及文本插值，后續會對其他 i18n 特性進行支持。`這句話也許是答案。

如何在js中使用i18n?

　　先說結果：　this.t('hello') || this.t('day', {day : this.data.day}) // 文本插值語法

　　我在最初編寫這篇博文的時候，是沒有成功在自己的js中成功使用js的，盡管官方的example成功了，我幾番比對都沒有發現自己漏掉了哪一步。直到前天突然靈光一閃，會不會是js中使用i18n的機制問題。結果我將原本單獨存放locale.*文件的i18n文件夾與國際化配置文件的i18n文件夾合并，都放在根目錄下。這時在js中使用國際化成功！

什么時候build呢？

　　每當翻譯配置文件有內容修改時。如果是手動引入locales.wxs，每當翻譯配置文件有內容修改時，都需要build生成新的文件。

　　每當涉及國際化的文件有變動時。如果是自動build實現locales.wxs文件引入，每當wxml有國際化相關內容變動、翻譯配置文件有內容修改時，都需要build重新生成。

本人項目參考

前提了解：維護老項目，沒有一個用于包裹pages、utils、assets、app.*等文件（夾）的src文件夾。

安裝依賴
構建npm
新建語言配置文件

　　　在根目錄下（與app.*文件同級）新建i18n文件夾，文件夾內新建兩個json文件，分別是`en-US.json`與`zh-CN`

{
  "index": "首頁",
  "hello": "你好{name}, 歡迎！" 
  ...
}

{
  "index": "Index",
  "hello": "Hello {name}, Welcome!"
  ...
}

gulp配置

　　在根目錄下（與app.*文件同級）新建gulpfile.js文件。（從配置會在第一次build時，在i18n文件夾下生成locales.js和locales.wxs文件，之后每一次build這兩個文件都會隨著配置文件的更新而更新

 1 const { src, dest, series } = require('gulp')
 2 const gulpI18nWxml = require('@miniprogram-i18n/gulp-i18n-wxml')
 3 const gulpI18nLocales = require('@miniprogram-i18n/gulp-i18n-locales')
 4 
 5 function mergeAndGenerateLocales() {
 6   return src('i18n/*.json')
 7     .pipe(gulpI18nLocales({ defaultLocale: 'zh-CN', fallbackLocale: 'zh-CN' }))
 8     .pipe(dest('i18n/'))
 9 }
10 export.default = series(mergeAndGenerateLocales)

package.json文件"script"配置

{
  ...
  "script": {
    "build": "gulp",
    ...
  },
　...
}

i18n初始化

　　在app.js文件中

...
import { initI18n, getI18nInstance } from '@miniprogram-i18n/core'
const i18n = getI18nInstance()
initI18n("en-US")
App({
  onLaunch: function() {
    /** 獲得本地語言 */
    const lang = wx.getAppBaseInfo().language 
    /** 根據本地語言設置小程序語言 */
    i18n.setLocale(lang.toLowerCase().includes('zh') ? 'zh-CN' : 'en-US')
  }
})

在需要使用到國際化翻譯頁面的js文件引入I18n

...
const { I18n } = require('@miniproogram-i18n/core')
Component({
  behabiors: [I18n],
  ...
})
// 或者
... 
const { I18nPage } = require('@miniprogram-i18n/core')
I18nPage({
...
})

打包生成locale.*文件

　　在gulpfile.js文件所在文件夾，用命令行運行

npm run build

在需要使用到國際化翻譯頁面的wxml文件中引入并書寫翻譯文本

<wxs src="../..i18n/locales.wxs" module="i18n"></wxs>
<view class="warpper">
  <view>{{ i18n.t('index', $_locale) }}</view>
  <text>{{ i18n.t('hello', { name: 'Jone' }, $_locale) }}</text>
</view>

在需要使用到國際化翻譯的js文件中

import { I18n } from "@miniprogram-i18n/core"
Component({
    behaviors: [I18n]
    data: {name: 'Developer'}
    methods: {
        OnLoad: function () {
            console.log(this.t('index'), this.t('hello', {name: this.data.name})
        }
    }
})
//或者

import { I18nPage } from "@miniprogram-i18n/core"
I18nPage({
    data: {name: 'Lii'}
    OnLoad: function () {
        console.log(this.t('index'), this.t('hello', {name: this.data.name})
    }
})

當翻譯配置文件有變動的時候，重新build并更新i18n/文件夾下的兩個文件

官方樣本

在社區看到不少朋友有無法順利打開官方提供的example的困擾，在這里也單獨說一下。

先從glthub將example下載到本地，此時可以先不在開發者工具中打開此項目，即使打開頁面也不會正常顯示，因為根文件夾下沒有app.*文件。
在gulpfile.js所在的文件位置，命令行運行。
此時會有一個新的`dist`文件夾，進入dist文件夾。
命令行依次運行。

npm install
npm run build

在微信開發者工具中導入dist文件夾這個項目（注意是dist）。
點擊`工具`->`構建npm`
此時頁面應該已經加載在模擬器中了，如果沒有，可以點擊`預覽`（Windows系統也可以使用Ctrl+B快捷鍵）。

下載下來的example不能直接打開的可能原因一是：沒有依賴。二是：根目錄下沒有`app.*`文件。

example就是典型的將所有都交給gulp打包的案例，我們編輯的文件只是為了用于生成dist文件夾中的內容，而真正查看效果以及上傳到版本的是dist內的生成的文件。

個人遺留問題

在Page構造器中使用`behaviors`有沒有/有哪些副作用？

posted @ 2022-01-20 10:10 JoneOnenine 閱讀(3829) 評論(0) 收藏舉報

刷新頁面返回頂部

JoneOnenine