Castle Game Engine

Unit CastleLocalizationGetText

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

Utilities for localizing CGE applications using GetText.

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class ETranslationEmptyId  
Class TCastleMOFile TMOFile descendant that allows iterating through all strings.

Functions and Procedures

function GetTextPoEntry(const Context, Id, EnglishText: String; const MsgidFromId: Boolean = true): String;
function GenerateGetTextPo(const C: TComponent; const GroupName: String): String;
function GenerateGetTextPo(const UrlMask: String): String;
function LoadGetTextMo(const Url: String): TCastleMOFile; deprecated 'use TCastleMOFile.Create';
procedure AddTranslatedCharacters(const Url: String; const Characters: TUnicodeCharList);
procedure AddTranslatedCharacters(const Mo: TCastleMOFile; const Characters: TUnicodeCharList);
procedure TranslateAllDesigns(const GetTextMoUrl: String);
procedure TranslateDesign(const C: TComponent; const GroupName: String; const GetTextMo: TCastleMOFile);
procedure CastleTranslateResourceStrings(const GetTextMoUrl: String);

Description

Functions and Procedures

function GetTextPoEntry(const Context, Id, EnglishText: String; const MsgidFromId: Boolean = true): String;

Generate text to insert to POT (PO template) to allow translating given text. Depending on MsgidFromId:

  • True (default):

    msgid is Id, msgstr is EnglishText in output. This looks non-standard, but is sometimes more comfortable:

    • EnglishText may be empty.

    • EnglishText may be repeated many times in the same output file.

    • Changing EnglishText later doesn't require updating all PO files, as EnglishText is not used as the key.

  • False:

    msgid is EnglishText, msgstr is empty, and we place special comment in the output to preserve Id. This is more standard, following typical GetText usage, and some software UI may assume that msgid is an English text.

function GenerateGetTextPo(const C: TComponent; const GroupName: String): String;

Generate GetText PO file contents that can be used as a basis for translators to localize this component. The component may be a hierarchy of user interface and transformations, just like for CastleComponentSerialize.

A typical workflow of translation is:

  1. Generate a file containing everything to translate in your components by calling something like GenerateGetTextPo('castle-data:/gui/*.castle-user-interface');.

  2. Translate the PO files and generate MO files using GetText tools.

  3. In game, after determining user language, call e.g. TranslateAllDesigns('castle-data:/translations/user_interface.ja.mo'); Where "ja" stands for Japanese.

The argument of this routine can be a TComponent hierarchy, which can be a TCastleUserInterface or TCastleTransform hierarchy designed in the CGE editor or in code.

The argument can also be an URL of a design (loaded using CastleSerializeComponent) or a mask (using wildcards * and ?) to load multiple designs. The design basename (part of URL without extension and path) is the prefix for all identifiers inside.

The file will include all translatable properties in the given component hierarchy, with their current values (by convention in English). By convention you store this file as "xxx.pot" or ""xxx.en.po" and then translate it e.g. to "xxz.ja.po" which you can use to load Japanese translations by TranslateDesigns .

function GenerateGetTextPo(const UrlMask: String): String;
 
function LoadGetTextMo(const Url: String): TCastleMOFile; deprecated 'use TCastleMOFile.Create';

Warning: this symbol is deprecated: use TCastleMOFile.Create

Load GetText MO file from and URL.

procedure AddTranslatedCharacters(const Url: String; const Characters: TUnicodeCharList);

Extract from MO file all unique characters in translated strings, add them to Characters.

procedure AddTranslatedCharacters(const Mo: TCastleMOFile; const Characters: TUnicodeCharList);
 
procedure TranslateAllDesigns(const GetTextMoUrl: String);

Translate all future designs (component hierarchies) loaded using CastleComponentSerialize using the given GetText MO file. This is the simplest way to translate user interface designed using CGE Editor.

The GetText PO file with suitable identifiers should be earlier generated using GenerateGetTextPo, translated, and processed to MO format using GetText tools.

Calling this routine again will override the effect of the previous call. That is, at a given time, only one MO file is "active" and automatically translates all the loaded designs. Pass GetTextMoUrl = '' to disable translating further UIs.

See also
TranslateDesign
Translate all possible properties in the given component hierarchy with given translation file.
procedure TranslateDesign(const C: TComponent; const GroupName: String; const GetTextMo: TCastleMOFile);

Translate all possible properties in the given component hierarchy with given translation file. Missing translations will cause a warning in the log (indicating that your translation file is outdated and doesn't reflect all UI stuff anymore).

If all your designs are loaded from files (using CastleComponentSerialize) then usually it's more comfortable to use TranslateAllDesigns instead of this routine. This routine is however more flexible, and allows to translate any component hierarchy.

See also
TranslateAllDesigns
Translate all future designs (component hierarchies) loaded using CastleComponentSerialize using the given GetText MO file.
procedure CastleTranslateResourceStrings(const GetTextMoUrl: String);

Use this instead of FPC TranslateResourceStrings. This supports URL to MO file, and works cross-platform.

Generated by PasDoc 0.16.0.