How To: Support multiple languages with ease

[Jishnu]

Hi,
We have a module in DevkitHelper (https://github.com/hashcube/DevkitHelper), called i18n. Which helps you to internationalize games easily. It uses JSON based localization file format.

## Setup
Add devkithelper to dependencies section of your manifest.

"dependencies": {
    "devkithelper": "https://github.com/hashcube/DevkitHelper.git#3.0.0"
}

## How to use

Create a folder `languages`, inside the resources folder. And add json files for the languages you want to support. Then in source code side, import DevkitHelper.i18n on top and call i18n('key'), where key is the key in the json file.

For eg.

// resources/languages/en.json
{
    "welcome-message": "Hello World!"
}

// resource/languages/fr.json
{
    "welcome-message": "Bonjour le monde"
}

// src/Application.js
import ui.TextView as TextView;
import DevkitHelper.i18n as i18n; // Important

exports = Class(GC.Application, function () {
    this.initUI = function () {
        var view = new TextView({
            superview: this,
            layout: 'box',
            centerX: true,
            centerY: true,
            color: 'white',
            text: i18n('welcome-message')
        });

    };
});

That's all. No need to add any special code. i18n handles the language based on user's device.

## Features

### Fallback to english
If you don't have a value in a language, the module will fall back to english.

// resources/languages/en.json
{
    "welcome-message": "Hello World!",
    "title": "Game Closure Project"
}

// resource/languages/fr.json
{
    "welcome-message": "Bonjour le monde"
}

// for a device with English language
i18n('title')
// Output: "Game Closure Project"

// for a device with French language
i18n('title')
// Output: "Game Closure Project"

### Placeholders
Messages can takes parameters. Values need to be passed in an array when you call i18n.

// resources/languages/en.json
{
    "level-title": "Level $1"
    "goal": "Solve $1 puzzles in $2 $3"
}

i18n('level-title', ['100']);
// Output: Level 100

i18n('goal', [2, 30, "Minutes"]);
// Output: Solve 2 puzzles in 30 Minutes

### Plurals
To make the syntax of sentence correct, some times plural forms are required. Based on the variable you are passing, i18n module can determine whether to show singular of a word or plural.

// resources/languages/en.json
{
    "goal": "Solve $1 {{$1 | 1: Puzzle | 2: Puzzles}}"
}

i18n('goal', [1]);
// Output: Solve 1 Puzzle

i18n('goal', [2]);
// Output: Solve 2 Puzzles

In case of English, there are only 2 plural forms, but many languages use more than 2 plural forms. For those you can add plural forms with a separation of a pipe(|).

### Force a language
You can force the module to get string from a particular language. For that pass the language code as third parameter for i18n.

// resources/languages/en.json
{
    "welcome-message": "Hello",
}

// resource/languages/fr.json
{
    "welcome-message": "Bonjour"
}

// for a device with having English language
i18n('welcome-message', [], 'fr')
// Output: "Bonjour"

// for a device with having French language
i18n('title', [], 'fr')
// Output: "Bonjour"

--
Regards,
Jishnu

http://j15h.nu

[Davide Aimone]

Great work!

I've done something similar for our game but your solution seems to be better :D