i18n Extension for Cocos Creator: Implement multilingual internationalization of Label and Sprite components (i18n).

Note that the difference between multilingual internationalization and localization is that internationalization requires the software to include text and image data in multiple languages and to switch between them in real time based on the default language or menu selection of the user's device. Localization, on the other hand, is the customization of text and image content for a particular language version when the software is released.

This extension is a multi-language support extension and therefore does not include the ability to remove a portion of the multi-language data when building the project.

Note: When the extension is installed for the first time, you need to restart the editor

Language Configuration

First open the i18n panel from Main Menu->Extensions: I18n Settings.

Then you need to create a JSON file containing the multilingual translation data (stored in .js format for ease of use).

• In the Manage Languages section, in the New Language ID input box, enter the ID of the new language, such as zh (for Chinese), en (for English), etc.
• After entering the ID and clicking the Create button, a language will be added to the relevant language selection menu and a translation data template for the corresponding language will be created in the resources/i18n directory of the project, e.g. resources/i18n/zh.js.

Next, you can select the language for the preview in the editor from the dropdown menu in the Preview Language section of the i18n panel.

Label Text Localization

Add Localize Component

The i18n extension provides two components for displaying multilingual content with Label and Sprite respectively.

Let's start with Label, we can add the i18n/LocalizedLabel component to any node in the scene or prefab where the Label component is located. This component only needs you to enter the dataID of the translation data index and it can update the Label's string display according to the current language.

Here we describe how to configure the dataID.

Translation Data

The translation data template created by the extension looks like this:

// zh.js

if (!window.i18n) window.i18n = {};
window.i18n.zh={
// write your key value pairs here
    "label_text": {
        "hello": "你好！" ,
        "bye": "再见！"
    }
};

The global variable window.i18n.zh allows us to access this data at any time in the script, without the need for asynchronous loading.

Inside the curly brackets are the translation key-value pairs that the user needs to add. We use the Polyglot library developed by AirBnb to perform internationalized string lookups, and the translation key-value pairs support object nesting, parameter passing, and dynamic data modification, which is very powerful. Please read the documentation in the link above for more information on its usage.

If we set up our translation data as in the example above, then the following key-value pairs will be generated:

• "label_text.hello" : "你好！"
• "label_text.bye" : "再见！"

Viewing Effects

Next, just write label_text.hello in the dataID property of the LocalizedLabel component, and the Label component on its node will display the 你好！ text.

If you need to change the text rendered by the Label at runtime, also assign LocalizedLabel.dataID instead of updating Label.string directly.

When you need to preview the display in another language, open the i18n panel and switch the language in Preview Language and the Label display in the scene will be updated automatically.

Runtime Language Setting

The language can be set at runtime according to the user's OS language or menu selection. After getting the language ID to be used, you need to initialize it with the following code:

const i18n = require('LanguageData');
i18n.init('zh'); // languageID should be equal to the one we input in New Language ID input field

You can also call ``i18n.init()` when you need to dynamically switch languages later.

If you need to update the current scene immediately after switching, you can call ``i18n.updateSceneRenderer()`.

Note that you must ensure that i18n.init(language) is executed before the scene containing the LocalizedLabel component is loaded at runtime, otherwise an error will be reported because the data cannot be loaded on the component.

Getting strings using translated key-value pairs in scripts

In addition to being used in conjunction with LocalizedLabel to solve the multi-language problem for static Labels in scenes, the LanguageData module can be used alone in scripts to provide runtime translation:

const i18n = require('LanguageData');
i18n.init('en');
let myGreeting = i18n.t('label_text.hello');
cc.log(myGreeting); // Hello!

Sprite Image Localization

Add the LocalizedSprite Component

First add the i18n/LocalizedSprite component to the node in the scene or prefab where any Sprite component is located. This component requires us to manually add a set of language IDs and SpriteFrame mappings to display images in the correct language in the editor preview and at runtime.

Adding language image mappings

The property spriteFrameSet, which is responsible for carrying the language to mapping, is an array, and we can add new mappings just like any other array property.

• First set the size of the array to be equal to the language type.
• Fill in the language property of each item with the ID of the corresponding language, e.g. en or zh.
• Drag and drop the language mapping (or SpriteFrame) into the spriteFrame property.

Once you have finished setting it, click the Refresh button below to see the effect in the scene.

As with LocalizedLabel, when we change the preview language in the i18n panel, all LocalizedSprites in the current scene will be automatically refreshed to show the image corresponding to the current language.