This function looks up a group in the current language by name.

If there is not a group, an empty one will be created, so the returned value is always a valid group.

This function looks up a string in a group of the current language.

If the string exists, it will replace the value argument.

group can be a group name (for one-off uses) or a reference to a group (acquired from cmn_loc_get_group).

value can be omitted if it's the same as key:

label = cmn_loc_string("Menu", "Start"); // value is "Start" here

If one or more trailing arguments are provided, value is assumed to contain placeholders ({0}, {1}, ...) like the modern-day string function has it:

var g = cmn_loc_get_group("Settings");
label = cmn_loc_string(g, "Volume", "Volume: {0}%", 65); // stores "Volume: 65%"

If you are using GameMaker Studio 2.3 or GM2022+, you can also call the get function from a group reference, like so:

var g = cmn_loc_get_group("Settings");
label = g.get("Volume", "Volume: {0}%", 65); // stores "Volume: 65%"

For further convenience, see cmn_loc_get_func.

This function works like cmn_loc_string, but accepts values to be inserted as an array instead.

count indicates the number of items in arg_array to use for replacements.

If omitted, the whole array will be used.

var vals;
vals[0] = 5;
vals[1] = 7;
var g = cmn_loc_get_group("UI");
label = cmn_loc_string_ext(g, "HP", "HP: {0}/{1}", vals); // stores "HP: 5/7"

If you are using GameMaker Studio 2.3 or GM2022+, you can also call the get_ext function from a group reference, like so:

var vals = [5, 7];
var g = cmn_loc_get_group("UI");
label = g.get_ext("HP", "HP: {0}/{1}", vals); // stores "HP: 5/7"

If you are using GameMaker Studio 2.3 or GM2022+, this convenience function looks up a group and returns its bound get function, which further reduces the amount of added code per translatable string.

var f = cmn_loc_get_func("Settings");
label = f("Volume", "Volume: {0}%", 65); // stores "Volume: 65%"
label_back = f("Back");

For purposes of comparing the formats, suppose we have a snippet of code like this:

var m = cmn_loc_get_group("Menu");
cmn_loc_string(m, "Start");
cmn_loc_string(m, "About", "A good\nvideogame"); /// @loc Shown in a corner
cmn_loc_string(m, "Exit");

var o = cmn_loc_get_group("Settings");
cmn_loc_string(o, "Volume", "Volume: {0}%", 65);
cmn_loc_string(o, "Back");

[Menu]
Start=Start
# Shown in a corner
About=A good
About=videogame
Exit=Exit

[Settings]
Volume=Volume: {0}%
Back=Back

[Menu]
Start=Start
# Shown in a corner
About="A good\nvideogame"
Exit=Exit

[Settings]
Volume=Volume: {0}%
Back=Back

{
    "Menu": {
        "Start": "Start",
        "About": "A good\nvideogame",
        "Exit": "Exit"
    },
    "Settings": {
        "Volume": "Volume: {0}%",
        "Back": "Back"
    }
}

{
    "Start": {
        "message": "Start",
        "description": ""
    },
    "About": {
        "message": "a good\nvideogame",
        "description": "Shown in a corner"
    },
    "Exit": {
        "message": "Exit",
        "description": ""
    }
}

{
    "Volume": {
        "message": "Volume: {0}%",
        "description": ""
    },
    "Back": {
        "message": "Back",
        "description": ""
    }
}

Disclosure:
There's quite a number of localization platforms!

I'm using Crowdin as an example here as it has the following qualities:

• Supports groups
  Localization looks less intimidating when it's not a single massive list of key-value pairs.
• Supports "context"/comments, including multi-line ones
• Reasonable pricing for indie games?
  (free if your localizations are public and there aren't too many words/languages)

There might be something even better that I haven't seen.

Anyway,

1. Create a project as usual
2. Generate files in "JSON (CRX)" format and add them to Crowdin.
   (on Sources tab, https://crowdin.com/project/YourProject/sources/files)
3. Add the JSON String Exporter integration to the project.
   
4. Navigate to Translations (https://crowdin.com/project/YourProject/translations)

5. Click Target File Bundles ➜ Add Bundle

   1. Set "Source files path" to *.json
   2. Set "Target file" ➜ "Format" to "JSON String Exporter"

   3. Click on the gear button next to "JSON String Exporter"

      1. Set "Configuration type" to "Object key-value"

      2. Set "Export pattern" to

         {
             "%identifier%": "%translation%"
         }
         

   4. Set "Resulting file pattern" to

      %language%/%file_name%.json
      

Once you've done some translations, you can download the bundle that you've set up earlier on the Translations page, extract the ZIP to your Included files, and load it using cmn_loc_lang_load_json_folder.

If you'd like to pack each language into a single file instead of a folder, I have added an option for that:

neko CmnLocGen.n --combine-crx crowdin-bundle.zip outputFolder

which will create a single JSON file per language in outputFolder.

If you choose an INI-based format for your files, you can translate them as usual and use version control software to help you update them (e.g. if you add/remove/change strings) later:

1. Create a new empty local Git repository.
2. Commit your original (pre-update) generated localization file into the main branch.
3. Create a secondary branch.
4. Commit the translated file into it, overwriting the original file.
   Commit changes for the file now indicate the lines that have been localized.
5. Commit the new (post-update) generated localization file into the main branch.
6. Merge the main branch into your secondary branch.
   Line additions/removals will happen automatically while merge conflicts will indicate text that has changed since being translated.

This global variable holds the current language.

Changing languages is a matter of assigning a new language reference (cmn_loc_lang) into it, which will affect subsequent calls to localization functions.

Configuration:

cmn_loc_csv_group_suffix = ".json";

Flat name: cmn_loc_lang_create

Creates a new localization language.

Unless you're going to populate key-value pairs yourself, you should look into loading functions instead.

Flat name: cmn_loc_lang_destroy

Localizations are typically loaded on game start and stick around for the duration of the game, but if you do need to swap them out, call this function to free the data structures related to this language.

Flat name: cmn_loc_lang_get_group

Returns a group with the given name; creates and stores a new one if necessary.

This is similarly handy if you're populating the key-value pairs yourself.

Flat name: cmn_loc_lang_add_group

Adds an existing group to this language.

Returns whether successful. Fails if there's already a same-named group added.

Flat name: cmn_loc_lang_set_plural_rules

Sets/changes pluralization rules for the language.

This changes the pluralization rules that are used when a string is not present in the current language and the fallback string (the value argument in localization functions) is used.

By default, these are set up for English, which is the equivalent of doing

cmn_loc_lang_set_default_plural_rules("one: # == 1");

Flat name: cmn_loc_group_create

Creates a new group.

key_value_map is a ds_map containing key-value pairs for this group.
If provided, an existing one will be referenced.
Otherwise a new map is created (and destroyed along with the group later).

Flat name: cmn_loc_group_destroy

Destroys a previously created group along with its key-value map (if owned by it)

A language will destroy its groups when it is destroys, so you shouldn't usually have to call this yourself.

Flat name: cmn_loc_group_get

This is a group-scope equivalent of cmn_loc_string.

Flat name: cmn_loc_group_get_ext

This is a group-scope equivalent of cmn_loc_string_ext.

Flat name: cmn_loc_group_set

Stores/replaces a key-value pair in this group.

The extension supports a subset of International Components for Unicode message format.

To use these, replace a simple {0} placeholder by {0, type, ...arguments}.

The following are supported:

{index, plural,
category {text}
}

menu_skip(L("EntryCount", "{0} public {0, plural,\n"
    + "one {game}\n"
    + "other {games}\n"
+ "}:", n));

{0} онлайн {0, plural,
one {гра}
few {гри}
other {ігор}
}:

menu_skip(L("EntryCount", "{0, plural,\n"
    + "one {# game}\n"
    + "other {# games}\n"
+ "}:", n));

menu_skip(L("EntryCount", "{0, plural,\n"
    + "one {# game}\n"
    + "other {# games}\n"
    + "=0 {no games}\n"
+ "}:", n));

{index, select,
value1 {text 1}
value2 {text 2}
other {catch-all}
}

Using set_plural_rules and cmn_loc_lang_set_default_plural_rules you can specify rules for pluralization categories that you will then be able to use in plural type messages.

Per-language rules can be looked up on the Unicode website.

one: # == 1

one: # == 1

one: is_int(#) and # % 10 = 1 and # % 100 != 11

few: is_int(#) and # % 10 in [2 .. 4] and # % 10 not in [12 .. 14]