System Flow

Before you're using the GM-I18n API, you need to know how things work in the GM-I18n system. You can skip this section if you already know how things works in GM-I18n system.

Locale Files Loading

The locale file (if you're using it) will be automatically loaded when you're using the i18n_create() function. The loading process is done asynchronously, so the messages in the file won't be loaded immediately. Therefore, you need to wait until the loading is finished before you can use the GM-I18n API.

Here's how the locale files loading works:

  1. You initialize the GM-I18n system using i18n_create() function and update the system using i18n_update_loader() function.
  2. The system check if you're trying to import any locale file using i18n_create() function.
  3. Your game run by 1 step:
    • If the time option was set in the GM-I18n system initialization, add current step to the system.
      • If the step passed the time interval, the system load your unloaded locale file sequentially.
      • If all locale files haven't loaded completely, repeat step 3 until all locale files are loaded to the system.
      • If all locale files have been loaded completely, continue to the step 4.
    • If the time option wasn't set in the GM-I18n system initialization, those files will be loaded immediately. Continue to the step 4.
  4. The system remove the loader after all locale files have been loaded.
Locale Files Loading Flowchart

Wrong way (not recommended):

Create Event
// initialize the GM-I18n system
global.i18n = i18n_create("global.i18n", "en", [
    new I18nLocaleInit("en", "English", "~/langs/en.json"),
    new I18nLocaleInit("id", "Indonesian", "~/langs/id.json")
]);

// get the message from "en" locale
msg = i18n_get_messages("en", "hello");

// print the message
show_debug_message(msg);    

// this will print an empty string (""), because the locale files aren't loaded immediately after the system is initialized. it will load the locale files after 1 step of the game.
// almost all of i18n_* functions that you use before the locale files are loaded won't work properly, whether it's on the objI18n object or other object.
Step Event
// update the GM-I18n system, need certain time to load the locale files
// the `time` is not set in the i18n_create() function, so it will load the locale files immediately after 1 step of this object
i18n_update_loader();
Draw Event
// draw a dynamic message. it will draw an empty text until the locale files are loaded (that contain the "hello" key message)
i18n_draw_message(100, 50, "@:hello", , "header");

Right way (recommended):

Create Event
// initialize the GM-I18n system
global.i18n = i18n_create("global.i18n", "en", [
    new I18nLocaleInit("en", "English", "~/langs/en.json"),
    new I18nLocaleInit("id", "Indonesian", "~/langs/id.json")
]);

// hardcode the mandatory messages
i18n_add_messages("en", "hello", "Hello World!");

// get the message from "en" locale
msg = i18n_get_messages("en", "hello");

// print the message
show_debug_message(msg);
Step Event
// update the GM-I18n system, need certain time to load the locale files
// the `time` is not set in the i18n_create() function, so it will load the locale files immediately after 1 step of this object
i18n_update_loader();
Draw Event
// draw a dynamic message. it only will draw the message after the locale files are loaded
// the i18n_is_ready() function is optional 
if (i18n_is_ready()) {
    i18n_draw_message(100, 50, "@:hello", , "header");
}
There are two ways to add a message to the system: importing the locale file through i18n_create() function, or add it manually using i18n_add_messages() function after the system is initialized.

If you aren't setting the time option when initializing the GM-I18n system, the system will load all locale files after 1 step of the game.

You're recommended to hardcode the mandatory messages (such as the UI text) so you can use it immediately after the system is initialized.

Use i18n_is_ready() to check whether the GM-I18n is ready (all locale files have been loaded) or not.

Drawing Presets

In a nutshell, the drawing presets are just a wrapper for the draw_set_* functions. It's optional to use the drawing presets, but it's recommended to use it if you want to draw the translated text consistently.

Create Event
/*
 * i18n_create() code
*/

i18n_add_drawings(["en", "id"], ["header", "body"], [
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1),             // header
    new I18nDrawings(fnNotoSans, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)      // body
]);
Draw Event
// use the dynamic drawing preset
i18n_use_drawing("header");

/* 
 * the i18n_use_drawing("header") is the same as:
 * draw_set_font(fnNotoSans);
 * draw_set_halign(fa_left);
 * draw_set_valign(fa_middle);
 * draw_set_color(#FFFFFF);
 * draw_set_alpha(1);
*/

// and then draw the message
i18n_draw_message(100, 50, "@:hello");

// you can also use a shorthand (using the drawing preset directly to the i18n_draw_message())
// i18n_draw_message(100, 50, "@:hello", , "header");
You can find the detailed instruction in the Drawing section.
You may call unecessary draw_set_* if you don't use the drawing presets, or using the drawing presets in inefficient way. For example, you use draw_set_font() before calling i18n_use_drawing(), or you use draw_set_halign() after calling i18n_use_drawing().

The GM-I18n system is not fault-tolerant for this case. It's recommended to use the drawing templates to avoid any unexpected behavior. You can see the detailed explanation in the Optimizations section.
  Have you gotten an overview of the GM-I18n system? Just ask me if you have any questions!
Edit this page on GitHub
Table of Contents