Difference between revisions of "Modules/localize"

From MSX Game Library

< Modules

(Translation source file)
(Translation source file)
Line 41: Line 41:
 
|-
 
|-
 
| <tt>en</tt> || <tt>eng</tt> || English || ✓
 
| <tt>en</tt> || <tt>eng</tt> || English || ✓
|rowspan="7"| Latin
+
|rowspan="8"| Latin
|rowspan="7"| <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_latin.png" />
+
|rowspan="8"| <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_latin.png" />
 
|-
 
|-
 
| <tt>fr</tt> || <tt>fra fre</tt> || French || Missing [ÀÂÈÊËÎÏÔÙÛŸŒœ]<br/>Convert: Œ→O+E, œ→o+e
 
| <tt>fr</tt> || <tt>fra fre</tt> || French || Missing [ÀÂÈÊËÎÏÔÙÛŸŒœ]<br/>Convert: Œ→O+E, œ→o+e
Line 55: Line 55:
 
|-
 
|-
 
| <tt>nl</tt> || <tt>nld dut</tt> || Dutch || ✓
 
| <tt>nl</tt> || <tt>nld dut</tt> || Dutch || ✓
 +
|-
 +
| <tt>fi</tt> || <tt>fin</tt> || Finnish || ✓ (missing rare [ŠšŽž])
 
|-
 
|-
 
| <tt>ja</tt> || <tt>jpn</tt> || Japanese || Missing [◯゙◯゚] and [ゐゑヰヱ] (archaic characters)<br/>Convert: ◯゙→◯+゛, ◯゚→◯+゜ || Kana || <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_japanese2.png" />
 
| <tt>ja</tt> || <tt>jpn</tt> || Japanese || Missing [◯゙◯゚] and [ゐゑヰヱ] (archaic characters)<br/>Convert: ◯゙→◯+゛, ◯゚→◯+゜ || Kana || <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_japanese2.png" />

Revision as of 01:59, 3 December 2023

The localize module handle translation in several language of your application. This module is very small in size and very efficient.

Usage

The translation process consists of 3 elements:

  • A source file (or several) in which the user places his translations for each supported language.
  • A header file with resulting data generated by the Build tool from the source files.
  • A module to be initialized in the code, then functions to select a language and to retrieve a given text's translation.

Translation source file

A translation source file is a text file (encoded as UTF-8) that must include:

  • A tag that defines each language section as: [language].
  • A translation list in the form: key = "text".

For example:

[en]
Start   = "Start"
Options = "Options"
Exit    = "Exit"

[fr]
Start   = "Commencer"
Options = "Options"
Exit    = "Quitter"

[ja]
Start   = "スタート"
Options = "オプション"
Exit    = "しゅうりょう"

You can use as many localization files as you like. You can, for example, group everything together in a single file, have different thematic files (menu, in-game, per mission, etc.), have a file for each language, etc. The Build Tool will gather them all together to generate the file you'll use in your code.

Language codes can be anything you like, but must contain only alphanumeric or '_' characters. We recommend using the 2-letter ISO 639-1 codes to define a language. The use of some given codes enables automatic conversion of UTF-8 characters into those compatible with MSX default fonts. The following are currently supported:

Code
ISO 639-1
Code
ISO 639-2
Language Notes Conversion Font layout
en eng English Latin
fr fra fre French Missing [ÀÂÈÊËÎÏÔÙÛŸŒœ]
Convert: Œ→O+E, œ→o+e
de deu ger German Missing [ßẞ]
es spa Spanish
da dan Danish Missing [Øø]
no nor Norwegian Missing [Øø]
nl nld dut Dutch
fi fin Finnish ✓ (missing rare [ŠšŽž])
ja jpn Japanese Missing [◯゙◯゚] and [ゐゑヰヱ] (archaic characters)
Convert: ◯゙→◯+゛, ◯゚→◯+゜
Kana
ko kor Korean To check... Hangul
ar ara Arabic To check... Arabic
uk ukr Ukrainian Missing [іїєґ] Cyrillic
ru rus Russian Missing [ё]

In translation entries, the key can only use alphanumeric or '_' characters.

Notes:

  • The MSXgl translation file format respects the format of the .ini files, so you can benefit from syntax highlighting if you use this extension. That said, this is not mandatory and you could, for example, use a .loc extension for your localization file.
  • Language code int and max are reserved and must not be used.

Generated header file

By adding source files to your project configuration (project_config.js; see bellow), the build tool will automatically group your source files into a header file for inclusion in your code.

You'll get warning messages if some of your translation keys exist in one language but not in another. The same applies if the same key is defined several times for the same language.

Use the module in your code

In your code, you only need 3 functions to use the location system:

  • Loc_Initialize to initialize the localization module.
  • Loc_SetLanguage to set the current language to use.
  • Loc_GetText to get a given text translation in the current language.

For example:

// Include the generated header file
#include "my_localization.h"

// Set the root data generated by the Build tool
Loc_Initialize(g_LocData, TEXT_MAX); 

// Select French language
Loc_SetLanguage(LANG_FR);

// Display the text corresponding to 'HELLO' key
Print_DrawTextAt(10, 10, Loc_GetText(TEXT_HELLO));

Dependencies

Dependency on other modules: None.

Settings

The localization process can be customized in your Build tool configuration file, project_config.js.

Available options:

//-- List files to be localized (array)
LocFiles = [ "file1.ini", "file2.ini" ];

//-- Localization output filename (string)
LocOutput = "localization.h";

//-- Localization structure name (string)
LocStruct = "g_LocData";

Note: If LocFiles is empty (default value), the localization process is disabled.

Appendix

  • See also: Sample program s_loc

Documentation