Setup

Requirements

Here's a list of the tested versions of GameMaker that works properly with GM-I18n.

It should work on other versions of GameMaker 2.3+ too. Please let me know on the tested versions page if you tested it on other versions that not listed above, whether it works properly or not. It will help me and other users who want to know which versions of GameMaker that works properly with GM-I18n.

Installation

Importing/Upgrading Package

There're 2 ways to import/upgrade the GM-I18n package to your project. You can choose one that you prefer.

Using Package Manager

1. Download the latest release from the releases page.
   
2. Import the GM-I18n v<version>.yymps file to your project by dragging it to the IDE.
   
3. Select the scI18n script from the list to import and click Add, or just click Add All. And finally, click the Import button.
   
4. If you're upgrading the package, a new window will appear. Checklist the Replace option and then click the Import button.
   

Manual Import

1. Download the latest release from the releases page.
   
2. Extract the downloaded file. You should see 5 files: GM-I18n v<version>.yymps, I18nConstants.d.ts, I18nConstructors.d.ts, I18nFunctions.d.ts, and scI18n.gml.
   
3. Open the scI18n.gml file and then copy the content of it to a new script in your project.

Offline Documentation (Optional)

There's some types definition files in the package, which is I18nConstants.d.ts, I18nConstructors.d.ts, and I18nFunctions.d.ts. These files are types definition files that you can use to help you understand better how to use the GM-I18n API.

Think of it as a cheatsheet for GM-I18n documentation. It's not as comprehensive as the web documentation, but it's better than nothing. If you want to use it, you can follow the steps below:

1. Extract the downloaded file. You should see 5 files: GM-I18n v<version>.yymps, I18nConstants.d.ts, I18nConstructors.d.ts, I18nFunctions.d.ts, and scI18n.gml.
   
2. Open the GM-I18n v<version> folder with your favorite code editor (such as Visual Studio Code, Lite XL, Atom, or other code editor you prefer).
   
3. You're done! You can use it as a "side-by-side" reference for the GM-I18n API.
   

If you're using Visual Studio Code (or other advanced code editor) as your secondary code editor for this purpose, you may get a better experience than using the GameMaker's built-in code editor. You can get the hover tooltip, type hints, jump-to-definition, and other features that make your coding experience better.

Configuration

You can create your own fonts asset normally if the language you're using is a Latin-based language. But, if you're adding language with non-Latin characters, you need to follow the steps below:

Using Font Assets

1. Create a new font asset in the IDE as you usually do.
2. Click Add to add new range to the font asset for each character range you need. Set the from and to to the first and last character of the range. For example, if you're adding Japanese, you may add Higarana (12352 to 12447), Katakana (12448 to 12543), and Kanji (13312 to 19903).
   
3. Click Add Range after you done adding all the ranges you need.
4. Repeat the steps above for each font you need.

Using Included Files

1. Prepare your font files. You can use any font you want, but make sure it's in .ttf or .otf format. You can convert any font to .ttf or .otf format using online converters.
2. Click Menu button in the Asset Browser (that one with 3 stripes icon), and then click Included Files. The Included Files window will open, and then click Open in Explorer.
   
3. A window will open and show you the datafiles folder of your project. Copy your font files there (with its license file). You can also make a folder for your font files, for example fonts.
   
4. In the Included Files window, click Refresh button. Your font files should now appear in the list.
5. Create the font asset from code. Use the font_add() function to create the font asset. For example:

// font_add(name, size, bold, italic, first, last);
global.font_ja = font_add(working_directory + "fonts/NotoSansJP-Medium.ttf", 32, false, false, 32, 127);

6. Repeat step 5 for each font you need.