Locale Switching

I've set some available locales in the game, but how do I switch between them? Let's see how to do it with different methods!

How It Works

Just call the i18n_set_locale() function with the locale code you want to switch to. It's that simple!

Functions

i18n_set_locale

Syntax
i18n_set_locale(code, [update_refs], [i18n]);
Description

Change the current locale used by the GM-I18n system.

Parameters
NameTypeDefaultDescription
codeStringThe locale code to switch to.
update_refsBooleantrueUpdate all references (message and asset) to the new locale.
i18nBoolean | I18nfalseThe I18n struct reference, or leave it empty to use the global i18n struct.
Returns

Void

Examples
Key Pressed - Space
// assume the system is initialized on global variable

i18n_set_locale("id");          // switch to "id" locale, and update all references

i18n_set_locale("en", false);   // switch to "en" locale, but don't update the references

That's it! Really simple, right?

Locale Switcher

You can use the i18n_set_locale() function to create a simple locale switcher.

Before we're jumping into the examples, let's make the message data first for this example! We will use the en, id, ja, and zh_CN locales.

en.json
{
    "locale": {
        "name": "Language",
        "en": "English",
        "id": "Indonesian",
        "ja": "Japanese"
    },
    "switch": "Switch",
    "hello": "Hello World!",
    "bye": "Bye World!",
    "welcome": "Welcome to {0}, {1}!",
    "dialog": {
        "npc_1" : {
            "greeting": "How are you today, {name}?",
            "farewell": "See you later, {0}!"
        }
    }
}
id.json
{
    "locale": {
        "name": "Bhs Indonesia",
        "en": "Inggris",
        "id": "Indonesia",
        "ja": "Jepang"
    },
    "switch": "Ganti",
    "hello": "Halo Dunia!",
    "bye": "Sampai Jumpa Dunia!",
    "welcome": "Selamat datang di {0}, {1}!",
    "dialog": {
        "npc_1" : {
            "greeting": "Apa kabar hari ini, {name}?",
            "farewell": "Jumpa lagi nanti, {0}!"
        }
    }
}
ja.json
{
    "locale": {
        "name": "言語",
        "en": "英語",
        "id": "インドネシア語",
        "ja": "日本語"
    },
    "switch": "切り替える",
    "hello": "こんにちは世界！",
    "bye": "さようなら世界！",
    "welcome": "ようこそ{0}、{1}！",
    "dialog": {
        "npc_1" : {
            "greeting": "{name}、今日はどうですか？",
            "farewell": "また後で、{0}！"
        }
    }
}
zh_CN.json
{
    "locale": {
        "name": "语言",
        "en": "英语",
        "id": "印尼语",
        "ja": "日语"
    },
    "switch": "切换",
    "hello": "你好世界！",
    "bye": "再见世界！",
    "welcome": "欢迎来到{0}，{1}！",
    "dialog": {
        "npc_1" : {
            "greeting": "{name}，你今天过得怎么样？",
            "farewell": "再见，{0}！"
        }
    }
}

Now let's create some locale switchers!

Cycling Stepper

The most basic switcher is just a simple button that changes the locale when clicked. This method is called Cycling Stepper.

Change the available locale with one way cycle, for example: en -> id -> ja -> zh_CN -> en.

objLocaleStepper

This object will be used to show the current locale name and change the locale when clicked.

Create Event
// assume the system is initialized on global variable,
// the data has been loaded, and you've created the drawing preset

// create the message reference for the locale name
ref_locale = i18n_create_ref_message("ref_locale", "locale.name");
Draw Event
// draw the button
draw_self();

// draw the current locale name (will be updated automatically when the locale is changed)
// using "button" drawing preset
i18n_draw_message(x + (sprite_width / 2), y + (sprite_height / 2), ref_locale, , "button");
Left Released Event
// change the locale when the button is clicked (left released)

switch (i18n_get_locale()) {
    case "en": i18n_set_locale("id"); break;
    case "id": i18n_set_locale("ja"); break;
    case "ja": i18n_set_locale("zh_CN"); break;
    case "zh_CN": i18n_set_locale("en"); break;
}

How simple, right? You can use the i18n_get_locale() function to get the current locale, and then use it to change the locale as you want.

Stepper

This method is similar to the Cycling Stepper, but it can cycle the locale in both ways.

Change the available locale with two way cycle, for example: en <-> id <-> ja <-> zh_CN.

objLocaleStepper

This object will be used to show the current locale name and become the locale controller.

Create Event
// assume the system is initialized on global variable,
// the data has been loaded, and you've created the drawing preset

// create the message reference for the locale name
ref_locale = i18n_create_ref_message("ref_locale", "locale.name");

// create the locale controller
locale_codes = i18n_get_locales_code();         // get all locale codes
locale_index = 0;                               // current locale index
locale_count = array_length(locale_codes);      // total locale count

// create the stepper button
step_next = instance_create_depth(x + (sprite_width / 2) + (sprite_get_width(objLocaleNext) / 2), y, depth, objLocaleNext, {
    target : id
});

step_prev = instance_create_depth(x - (sprite_width / 2) - (sprite_get_width(objLocalePrev) / 2), y, depth, objLocalePrev, {
    target : id
});
Draw Event
// draw the sprite
draw_self();

// draw the current locale name (will be updated automatically when the locale is changed)
// using "button" drawing preset
i18n_draw_message(x + (sprite_width / 2), y + (sprite_height / 2), ref_locale, , "button");

objLocalePrev

This object will be used to change the locale to the previous one.

Left Released Event
// change the locale index to the previous one
if (target.locale_index > 0) {
    target.locale_index--;
} else {
    target.locale_index = target.locale_count - 1;
}

// change the locale
i18n_set_locale(target.locale_codes[target.locale_index]);

objLocaleNext

This object will be used to change the locale to the next one.

Left Released Event
// change the locale index to the next one
if (target.locale_index < target.locale_count - 1) {
    target.locale_index++;
} else {
    target.locale_index = 0;
}

// change the locale
i18n_set_locale(target.locale_codes[target.locale_index]);

A bit complicated, but it's still simple, right?

Option Group

This method is used in GM-I18n demo. It's a bit more complicated than the previous methods, but it's more flexible.

Change the available locale with option group, for example: en, id, ja, zh_CN.

objLocaleGroup

This object will be used to show the current locale name and become the locale controller.

Create Event
// assume the system is initialized on global variable,
// the data has been loaded, and you've created the drawing preset

// create the locale options
locale_codes = i18n_get_locales_code();         // get all locale codes

for (var i = 0; i < array_length(locale_codes); i++) {
    // create the locale option in vertical line
    instance_create_depth(x, y + (i * (sprite_get_height(objLocaleOption) + 10)), depth, objLocaleOption, {
        code : locale_codes[i]
    });
}

objLocaleOption

This object will be used to change the locale when clicked.

Create Event
// assume the system is initialized on global variable,
// the data has been loaded, and you've created the drawing preset

// get a static message for this locale
name = i18n_get_messages("locale.name", , code);
Draw Event
// draw the sprite
draw_self();

// draw the locale name using "button" drawing preset in the specific locale
i18n_draw_message(x + (sprite_width / 2), y + (sprite_height / 2), name, , "button", code);
Left Released Event
// change the locale
i18n_set_locale(code);

This one is the most flexible one. You can improve this example to fit your needs. For example, you can add a highlight effect when the locale is active, or you can make a real dropdown menu for the locale options.

Custom

The example above are just some basic examples. Of course, you can create your own locale switcher! The possibilities are endless.

Use these functions to help you create your own locale switcher:

You can also use the i18n_get_messages() function to get a static message for each locale. It's useful if you want to show the locale name in the switcher.
  That's it! How about adding this locale switcher to your game, especially in your settings/options menu?
Edit this page on GitHub
Table of Contents