Messages

A message is a translated text that you will use in GM-I18n system. It's also known as text or translation in other localization system.

Here's an example locale messages we will use in this section:

en.json

{
    "hello": "Hello World!",
    "bye": "Goodbye World!",
    "long_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "button": {
        "text": "Click me!",
        "confirm": "Are you sure?",
        "cancel": "Cancel"
    },
    "menu": {
        "file": "File",
        "edit": "Edit",
        "help": {
            "about": "About",
            "quit": "Quit"
        }
    }
}

Static Messages

You can get a static message from the GM-I18n system using the i18n_get_messages() function anywhere in your game.

objI18n - Create

// assume the system is initialized on global variable
// i18n_get_messages(key, [data], [locale], [i18n])
msg = i18n_get_messages("hello", , "en");                    // "Hello World!", whether the current locale is "en" or not (static)
msg_arr = i18n_get_messages(["bye", "long_text"], , "id");   // ["Sampai jumpa Dunia!", "Lorem ipsum ..."], static

You need to pass the locale code you want to get the message from. If you want to get the static message from the current locale, you can leave the locale parameter empty.

You can also use i18n_get_messages() function without passing the i18n struct if you're creating the I18n system in the global variable.

You can pass an array of keys to the key parameter to get multiple messages at once. The function will return an array of messages.

The data parameter is used to interpolate the message. We will discuss this in the Interpolation section.

Dynamic Messages

A dynamic messages is a bit tricky for newcomer. You normally can't get the dynamic message using i18n_get_messages() function. You can, but it's strongly not recommended. Your game will have performance issue if you're using i18n_get_messages() function to get the dynamic message.

Here's how you can get the dynamic message in wrong way:

Create Event

// assume the system is initialized on global variable
// declare the variable
msg = "";

How to get the dynamic message correctly?

You need to use i18n_create_ref_message() function to create a reference to the message, and then you can use it like a normal message.

Create Event

// assume the system is initialized on global variable
// i18n_create_ref_message(var_name, key, [data], [i18n])
msg = i18n_create_ref_message("msg", "hello");          // create the message reference

That's it! Now you can use the msg variable like a normal message. The msg variable will automatically update itself when the locale is changed by calling i18n_set_locale() function.

How simple, right? But here's the problem comes, what should I pass to the var_name parameter?

Variable Name Handling

The var_name parameter is actually the name of the variable that you want to store the message reference. In the example above, we're storing the message reference in the msg variable, so the var_name is msg. Here's the detailed explanation:

objI18n - Create Event

// assume the system is initialized on global variable

// the variable name is "msg"
msg = i18n_create_ref_message("msg", "hello");      

// the variable name is "button_text"
button_text = i18n_create_ref_message("button_text", "button.text");

// message ref in array, the variable name is "my_arr"
my_arr = [
    i18n_create_ref_message("my_arr.0", "hello"),       // this reference is created in index 0
    i18n_create_ref_message("my_arr.1", "bye"),         // this one is in index 1, separate the array index with dot "."
    "",
    i18n_create_ref_message("my_arr.3", "long_text")    // not always need to be created consecutively
];

// message ref in struct, the variable name is "my_struct"
my_struct = {
    text : i18n_create_ref_message("my_struct.text", "hello"),                // the key is "hello"
    button : i18n_create_ref_message("my_struct.button", "button.text"),      // the var_name is this struct member name
    about : i18n_create_ref_message("my_struct.edit", "menu.help.about"),     // separate the struct member with dot "."
    nested : {
        bye : i18n_create_ref_message("my_struct.nested.bye", "bye")          // you can nest the struct as deep as you want
    },
    arr : [
        i18n_create_ref_message("my_struct.arr.0", "hello"),                  // you can also create the reference in array
        i18n_create_ref_message("my_struct.arr.1", "bye")
    ]
}

// message ref in global variable, the variable name is "global.hello_text"
global.hello_text = i18n_create_ref_message("global.hello_text", "hello");      // use "global" keyword like you're defining a global variable
global.button_text = i18n_create_ref_message("g.button_text", "button.text");   // you can use "g." shorthand for "global."

// message ref in global array
global.gb_arr = [
    i18n_create_ref_message("g.gb_arr.0", "hello"),         // same as you're creating the reference in instance variable,
    i18n_create_ref_message("global.gb_arr.1", "bye")       // but use "global." or "g." as the prefix
];

// message ref in global struct
global.gb_struct = {
    text : i18n_create_ref_message("global.gb_struct.text", "hello"),           // same as you're creating the reference in instance variable,
    button : i18n_create_ref_message("g.gb_struct.button", "button.text"),      // but use "global." or "g." as the prefix
    menu : {
        about : i18n_create_ref_message("g.gb_struct.menu.about", "menu.help.about")   // a nested struct in global struct
    },
    arr : [
        i18n_create_ref_message("global.gb_struct.arr.0", "hello"),            // you can also create the reference in array
        i18n_create_ref_message("g.gb_struct.arr.1", "bye")
    ]
};

The i18n_create_ref_message() and i18n_set_locale() function is the core of the dynamic message, even core of GM-I18n system. It's really optimized (and will be even more optimized in the future, stay tuned!), so you can use it as much as you want.

You can use the i18n_create_ref_message() function to create a message reference in any variable, array, or struct. The var_name parameter is the name of the variable that will store the message reference.

You can use the g. shorthand for global.. It's recommended to use global. for better readability, but it's up to you.

You can create the message reference in nested struct or array. Just make sure to pass the correct var_name to the i18n_create_ref_message() function.

Though it's a cool feature, it's not that flexible as you think. Here's some limitations you should be aware of:

You can only create the message reference in global variable or instance variable. You can't create it in the global function (in script asset), data structure (such as ds_list, ds_map, etc.), or local variable. If you try to do so, it will return a static message instead of dynamic message, even if it's recognized by the system.
Currently, the message references created in array only accept 1D array. So, you can't create it in 2D array or higher. Passing text.0.1 as the var_name in the i18n_create_ref_message() function won't be recognized.
The system only accept array index (such as text.0) in the last level of the var_name. So, struct inside an array (such as text.0.button.text) won't be recognized.

Though thei18n_create_ref_message()function is really optimized, don't ever create the message references in any event that updated every step (such asStep Event, Draw Event, etc.)! It will cause performance issue and may eventually crash your game.

If you want to create the message references in theglobalvariable, do it in theCreate Eventof any object. If you want to create it in the instance variable, do it in theCreate Eventof the object that own the variable.

You need interpolate the message with certain value? Check out the Interpolation section!

Edit this page on GitHub

Core ConceptsFallback

UsageInterpolation