Difference between revisions of "Modules/localize"

From MSX Game Library

< Modules

Line 1: Line 1:
The {{MOD|localize}} module handle translation in several langage of your application. This module is very small in size and very efficient.
+
The {{MOD|localize}} module handle translation in several language of your application. This module is very small in size and very efficient.
  
 
== Usage ==
 
== Usage ==
Line 30: Line 30:
  
 
You can use as many location files as you like.
 
You can use as many location files as you like.
You can, for example, group everything together in a single file, or have thematic files (menu, in-game, etc.), or have a file for each language.
+
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 create the file you'll use in your code.
+
The Build Tool will gather them all together to generate the file you'll use in your code.
  
 
Notes:
 
Notes:
* This file format respects the format of <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.
+
* This 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.
  
 
== Dependencies ==
 
== Dependencies ==

Revision as of 19:32, 24 November 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 file (or several) in which the user places his translations for each supported language.
  • A project configuration (See bellow) to inform the Build tool of the translation files to be processed.
  • 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: [langue].
  • 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 location 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.

Notes:

  • This 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.

Dependencies

Dependency on other modules: None.

Settings

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

//-- 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