Aoineko at 22:32, 4 January 2024

2024-01-04T22:32:36Z

Aoineko: /* Translation source file */

2024-01-04T22:32:25Z

‎Translation source file

Aoineko: /* Use the module in your code */

2024-01-04T22:30:58Z

‎Use the module in your code

Aoineko: Created page with " 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 resul..."

2024-01-04T13:06:19Z

Created page with " 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 resul..."

New page

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: <tt>[language]</tt>.
* A translation list in the form: <tt>key = "text"</tt>.

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 '<tt>_</tt>' characters.
We recommend using the [https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes 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:

{| class="wikitable sortable"
|-
! Code ISO 639-1 !! Code ISO 639-2 !! Language !! Notes !! Conversion !! Font layout
|-
| <tt>en</tt> || <tt>eng</tt> || English || ✓
|rowspan="16"| Latin
|rowspan="16"| <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 [ÀÂÈÊËÎÏÔÙÛŸ] accents and [Œœ]) Convert: Œ→O+E, œ→o+e
|-
| <tt>de</tt> || <tt>deu ger</tt> || German || Missing [ßẞ]
|-
| <tt>es</tt> || <tt>spa</tt> || Spanish, Castilian || ✓
|-
| <tt>da</tt> || <tt>dan</tt> || Danish || Missing [Øø]
|-
| <tt>no</tt> || <tt>nor</tt> || Norwegian || Missing [Øø]
|-
| <tt>nl</tt> || <tt>nld dut</tt> || Dutch || ✓
|-
| <tt>fi</tt> || <tt>fin</tt> || Finnish || ✓ (missing rare [ŠšŽž])
|-
| <tt>is</tt> || <tt>isl ice</tt> || Icelandic || Missing [ÁÐðÍÓÚÝýÞþ]
|-
| <tt>ga</tt> || <tt>gle</tt> || Irish|| ✓
|-
| <tt>it</tt> || <tt>ita</tt> || Italian || ✓
|-
| <tt>pl</tt> || <tt>pol</tt> || Polish || Missing [ĄąĆćĘęŁłŃńÓŚśŹźŻż]
|-
| <tt>pt</tt> || <tt>por</tt> || Portuguese || ✓ (missing [ÁÍÓÚÂÊÔÀÒÈÌÙÏ] accents)
|-
| <tt>sk</tt> || <tt>slk slo</tt> || Slovak || Missing [ÁČčĎďÍĹĺĽľŇňÓÔŔŕŠšŤťÚÝýŽž]
|-
| <tt>sv</tt> || <tt>swe</tt> || Swedish || ✓
|-
| <tt>tr</tt> || <tt>tur</tt> || Turkish || Missing [ĞğıİŞş]
|-
| <tt>ja</tt> || <tt>jpn</tt> || Japanese || Missing [◯ﾞ◯ﾟ] and [ゐゑヰヱ] (archaic characters) Convert: ◯ﾞ→◯+゛, ◯ﾟ→◯+゜ || Kana || <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_japanese2.png" />
|-
| <tt>ko</tt> || <tt>kor</tt> || Korean || ''To check... seems broken'' || Hangul || <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_hangul.png" />
|-
| <tt>ar</tt> || <tt>ara</tt> || Arabic || ''To check... reverse order'' || Arabic || <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_arabic2.png" />
|-
| <tt>uk</tt> || <tt>ukr</tt> || Ukrainian || Missing [ҐґЄєІіЇїЙй]
|rowspan="2"| Cyrillic
|rowspan="2"| <img width="100%" src="https://raw.githubusercontent.com/aoineko-fr/MSXgl/main/engine/datasrc/font/BIOS/font_bios_cyrillic.png" />
|-
| <tt>ru</tt> || <tt>rus</tt> || Russian || Missing [ЁёЪ]
|}

In translation entries, the key can only use alphanumeric or '<tt>_</tt>' characters.

Notes:
* The MSXgl translation file format respects the format of the <tt>.ini</tt> 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 <tt>.loc</tt> extension for your localization file.
* Language code <tt>int</tt> and <tt>max</tt> are reserved and must not be used.

=== Generated header file ===

By adding source files to your project configuration (<tt>project_config.js</tt>; see [[Modules/localize#Settings|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:
* <tt>Loc_Initialize</tt> to initialize the localization module.
* <tt>Loc_SetLanguage</tt> to set the current language to use.
* <tt>Loc_GetText</tt> 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));

@@ Line 26: / Line 26: @@
 Options = "オプション"
 Exit    = "しゅうりょう"
-<syntaxhighlight>
+</syntaxhighlight>
 You can use as many localization files as you like.

@@ Line 11: / Line 11: @@
 For example:
- [en]
+<syntaxhighlight lang="ini">
- Start   = "Start"
+[en]
- Options = "Options"
+Start   = "Start"
- Exit    = "Exit"
+Options = "Options"
 Exit    = "Exit"
- [fr]
- Start   = "Commencer"
+[fr]
- Options = "Options"
+Start   = "Commencer"
- Exit    = "Quitter"
+Options = "Options"
 Exit    = "Quitter"
- [ja]
- Start   = "スタート"
+[ja]
- Options = "オプション"
+Start   = "スタート"
- Exit    = "しゅうりょう"
+Options = "オプション"
 You can use as many localization files as you like.

@@ Line 104: / Line 104: @@
 For example:
- // Include the generated header file
+<syntaxhighlight lang="c">
- #include "my_localization.h"
+// Include the generated header file
- // Set the root data generated by the Build tool
+// Set the root data generated by the Build tool
- Loc_Initialize(g_LocData, TEXT_MAX);
+Loc_Initialize(g_LocData, TEXT_MAX);
- // Select French language
+// Select French language
- Loc_SetLanguage(LANG_FR);
+Loc_SetLanguage(LANG_FR);
- // Display the text corresponding to 'HELLO' key
+// Display the text corresponding to 'HELLO' key
- Print_DrawTextAt(10, 10, Loc_GetText(TEXT_HELLO));
+Print_DrawTextAt(10, 10, Loc_GetText(TEXT_HELLO));

Modules/localize/Usage - Revision history

Aoineko at 22:32, 4 January 2024

Aoineko: /* Translation source file */

Aoineko: /* Use the module in your code */

Aoineko: Created page with " 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 resul..."