How to Build a Reactive Multilingual Mini Program
As the demand for Mini Programs (MP) rises, an increasingly diverse community of organizations and entrepreneurs seek to develop their own platform, with some requiring a smooth multilingual experience to serve a wide range of users.
This tutorial will teach you how to take advantage of WeChat Mini Program components and a global store to develop the foundation for a smooth multilingual MP without relying on any 3rd party development framework such as Taro or Chameleon.
Getting Started
Open WeChat Development Tools and initialize a new Mini Program project. If you have an AppID from an already registered MP account, enter it in the field, otherwise, you can click (测试号) to use a sandbox account. After choosing a project name and directory, leave project settings as default like below:
Now that we have a “fresh” Mini Program project, delete all the example code they start you out with. Remove the “logs” and “index” pages from the pages directory and app.json, and delete everything in app.js so it looks like this:
//app.jsApp({onLaunch () {},globalData: {}})
Your development tools should be throwing a bunch of errors because there’s no index page, but that’s fine because we’re going to create it again. Back in app.json, add back in the path for the index page:
"pages": ["pages/index/index"],
After saving, the index page and directory should have been regenerated.
Adding the Global Store
In order to easily inject our language settings and strings into our pages and components, we’re going to use a store to hold our language data. This will also make it so that switching the language won’t require any reloads.
Although there are a number of store packages available for MPs, I found westore to be simpler and lighter than something like a vuex or redux clone. Plus, it’s maintained by Tencent. It doesn’t have an npm package for some reason, so we’ll need to clone their Github repo and transfer a few files to our project:
git clone https://github.com/Tencent/westore.gitOpen the westore folder and navigate to utils. Copy both the create.js and diff.js files to your MPs utils directory.
Create a file called store.js in your MP root and structure it like this:
As you can see, our default language will be English and we also need to create a strings file in the i18n directory. Create that directory and then a strings.js file along with a couple of strings to demonstrate how everything works. If you want to add any of your own strings, make sure there is always a translation available in each language:
Automatically Handling Languages
Next, we’ll create a package that helps us automatically get the user’s phone language on MP start and set either that or our fallback language in the store and persist it so the next MP load will use stored language settings. In our i18n folder, create a file called language.js and paste the below in:
For the sake of not having to manually write promises all over (especially for conditional function calls), this file also uses regeneratorRuntime to enable async await, and a helper I created called wxp that wraps MP APIs with promises. Download and copy both the runtime and wxp files into your utils folder. (Note: the runtime file is a specific commit from the runtime repo. It seems their newest version doesn’t work)
Your directory should look like this:
Putting it Together
Now we are finally ready to use this language library in our Mini Program. Open app.js again and import our library. In our onLaunch() lifecycle method, call initLanguage to set our user’s language and add it to the store:
// app.js
import { initLanguage } from './i18n/language'App({
onLaunch () {
initLanguage()
}
//...})
Now let’s finally start showing strings on our home page!
Open your pages/index/index.js file and import our store library. We need to also inject the store into our page with the create file we imported earlier and initialize the keys we want store to inject into our page’s data:
// pages/index/index.js
import create from '../../utils/create'
import store from '../../store'create(store, {
data: {
language: null,
strings: null
}
// ...})
We want the store to inject the language and strings into our page, so we set them both to null. Any time the language changes anywhere in the MP, the language will be updated globally without needing to reload.
Let’s also demonstrate a multilingual loading spinner while we’re in index.js. Add this under our data object:
// pages/index/index.js
import create from '../../utils/create'
import store from '../../store'create(store, {
data: {
language: null,
strings: null
}
onLoad () {
this.store.showLoading()
setTimeout(() => wx.hideLoading(), 2000)
}})
Since we’re not loading any real data, we show the multilingual loader and hide it after 2s.
Save your file and you’ll now see our loader displaying in whatever language is set in your storage. Update the ‘language’ key to see the loader display in the other language.
Sometimes for a brand new user on iOS, the loading spinner may be in the wrong language on the landing page. This is due to the page onLoad method being called before the language is set in store. A 1ms delay before calling the loading spinner is enough to get it in the correct language. You can use setTimeout or another method to mitigate this.
Finally, to see multilingual text on the page itself, open /pages/index/index.wxml and type this:
<!-- index.wxml -->
<view>{{ strings[language].helloThere }}</view>Now you’ll see our hello text in whatever language is set in the store (Chinese for me).
And there you have it. Now you’re ready to build a reactive multilingual Mini Program. Further improvements could add a language switcher or other helpful tools to automatically display the correct language of content loaded over your API.
Learn More
If you would like to learn more information related to WeChat and Mini Program development, you can download my free presentation about Mini Programs and whether or not they’re right for you.
