Localized Assets

Localized assets are assets that have different versions based on the locale. This is useful when you want to display a different sprite for each locale, or you want to play a different sound for each locale.

It can be a sprite, sound, or even other assets type you want to localize!

How It Works?

Let's see the example below to see the differences when you aren't using GM-I18n's localized assets and when you're using it.

Create Event
// assume you're not using GM-I18n system, 
// so you need to manually change the locale and the assets
locale = "en";
my_spr = sprSplashEn;
my_snd = sndVoiceEn;
Key Pressed - Space
// change the locale and the assets
// and of course, you need to manually change the assets for each locale (really tiresome!)
if (locale == "en") {
    locale = "id";
    my_spr = sprSplashId;
    my_snd = sndVoiceId;
} else {
    locale = "en";
    my_spr = sprSplashEn;
    my_snd = sndVoiceEn;
}
Key Pressed - Enter
// play the sound
audio_play_sound(my_snd, 1, false);
Draw Event
// draw the sprite
draw_sprite(my_spr, 0, 100, 50);
draw_sprite_ext(my_spr, 0, 100, 200, 1, 1, 0, c_white, 1);

How about when you're using GM-I18n's localized assets?

Create Event
// assume the system is initialized on global variable
// i18n_create_ref_asset(var_name, locale_asset, [i18n])
// just create the reference to the assets, like you're creating a message reference
my_spr = i18n_create_ref_asset("my_spr", {
    en: sprSplashEn,
    id: sprSplashId
});

my_snd = i18n_create_ref_asset("my_snd", {
    en: sndVoiceEn,
    id: sndVoiceId
});
Key Pressed - Space
// change the locale, and the assets will be changed automatically!
i18n_set_locale((i18n_get_locale() == "en" ? "id" : "en"));         // a simple locale switcher
Key Pressed - Enter
// play the sound
audio_play_sound(my_snd, 1, false);
Draw Event
// draw the sprite
draw_sprite(my_spr, 0, 100, 50);
draw_sprite_ext(my_spr, 0, 100, 200, 1, 1, 0, c_white, 1);

Dynamic Assets Localization

We won't discuss about static assets, because it's really simple and you don't even need to use GM-I18n for it. Just need to pass the asset ID to the function that needs it.

Let's dive into the dynamic assets localization using GM-I18n!

Functions

You can create the asset reference using the i18n_create_ref_asset() function. The function is really similar to the i18n_create_ref_message() function. Here's some difference between them:

  1. The i18n_create_ref_asset() function doesn't have the key parameter. You don't need to provide the key, because the key is the asset itself.
  2. The i18n_create_ref_asset() function has the locale_asset parameter. You need to provide the asset for each locale in the struct. The struct key is the locale code, and the value is the asset ID.

i18n_create_ref_asset

Syntax
i18n_create_ref_asset(var_name, locale_asset, [i18n]);
Description

Creates a reference to the localized asset. The reference will automatically update itself when the locale is changed by calling i18n_set_locale() function.

Parameters
NameTypeDefaultDescription
var_nameStringThe name of the variable that will store the asset reference. The var_name can be in any level of the instance variable or global variable.
locale_assetStructThe localized asset for each locale. The struct key is the locale code, and the value is the asset ID.
i18nBoolean | I18nfalseThe I18n struct reference, or leave it empty to use the global i18n struct.
Returns

Asset (in the current locale of the I18n struct)

Examples
Create Event
// assume the system is initialized on global variable

// create some asset references
// the `var_name` is the name of the variable that will store the asset reference
// for this example, we will use the `my_spr` variable to store the sprite reference
my_spr = i18n_create_ref_asset("my_spr", {
    en: sprSplashEn,
    id: sprSplashId,
    ja: sprSplashJa
});

// you can create the reference in array
// add the index of the array to the `var_name` separated by dot "."
// so, the `var_name` is "my_arr.0"
my_arr = [
    i18n_create_ref_asset("my_arr.0", {
        en: sndVoiceEn,
        id: sndVoiceId,
        ja: sndVoiceJa
    })
];

// you can also create the reference in struct
// add the member name of the struct to the `var_name` separated by dot "." 
// so, the `var_name` is "my_struct.my_spr" and "my_struct.my_snd.0"
my_struct = {
    my_spr : i18n_create_ref_asset("my_struct.my_spr", {
        en: sprTutorial1En,
        id: sprTutorial1Id,
        ja: sprTutorial1Ja
    }),
    my_snd : [
        i18n_create_ref_asset("my_struct.my_snd.0", {
            en: sndVoiceEn,
            id: sndVoiceId,
            ja: sndVoiceJa
        })
    ]
};

// in global variable, add "global." or "g." as the prefix
global.my_obj = i18n_create_ref_asset("global.my_obj", {
    en: objPlayerEn,
    id: objPlayerId,
    ja: objPlayerJa
});

// you can also create the reference in array in global variable
global.my_room = [
    i18n_create_ref_asset("g.my_room.0", {
        en: rmMainMenuEn,
        id: rmMainMenuId,
        ja: rmMainMenuJa
    })
];

// you can also create the reference in struct in global variable, and even nested struct in global struct!
global.my_font = {
    my_font_1 : i18n_create_ref_asset("g.my_font.my_font_1", {
        en: fnNotoSansEn,
        id: fnNotoSansId,
        ja: fnNotoSansJa
    }),
    ui_font : [
        i18n_create_ref_asset("global.my_font.ui_font.0", {
            en: fnNotoSansEn,
            id: fnNotoSansId,
            ja: fnNotoSansJa
        })
    ]
};
Key Pressed - Space
// change the locale, and the assets will be changed automatically!
i18n_set_locale((i18n_get_locale() == "en" ? "id" : "en"));         // a simple locale switcher
Key Pressed - Enter
// play the sound
audio_play_sound(my_arr[0], 1, false);
audio_play_sound(my_struct.my_snd[0], 1, false);
Draw Event
// draw the sprite
draw_sprite(my_spr, 0, 100, 50);
draw_sprite_ext(my_struct.my_spr, 0, 100, 200, 1, 1, 0, c_white, 1);
The var_name is not the name of the asset itself. You can name the var_name as you want, as long as it's unique in the same level of the variable.

You can see the detailed explanation in the Variable Name Handling section.
The asset you passed to the locale_asset parameter is static. So, if you change the value of the asset after creating the asset reference, it won't affect the asset in the reference.

If you don't set the asset for a specific locale, the asset in the reference will be undefined, and will take the asset in the default locale instead. So, make sure to set the asset for all locale you want to support.
  That's it, you can create localized assets without breaking any sweat!
Edit this page on GitHub
Table of Contents