Performs string translation in the Lazarus IDE and LCL.

lcltranslator.pas contains classes and routines used to perform translation for strings used in Lazarus IDE and LCL (Lazarus Component Library). It searches for .po (Portable Object) and/or .mo (Machine Object) files used to perform I18n internationalization and L10n localization. The .po/.mo files are stored in the languages or locale directories. To access translation files from an alternate location, use the LResources unit and the LRSMoFile variable directly.

To enable string translation, use this unit in your application and check the Enable i18n option in the Project > Project Options > i18n screen. You will need to call the SetDefaultLang routine in your code to activate the translation facility. If you want translation to be performed automatically, use the DefaultTranslator unit instead.

This unit also translates LCL string constants in the lclstrconsts file using files in the directory where program translation files are stored.

For more information, see the Lazarus Wiki article:

Creating Multi-Language Applications

Performs string translations for persistent objects.

TUpdateTranslator is a TAbstractTranslator descendant used to perform string translations for persistent objects. TUpdateTranslator provides the UpdateTranslation method which updates any translatable properties in Lazarus resources.

TUpdateTranslator is used as the ancestor for the TDefaultTranslator and TPOTranslator classes.

Performs action required to update string translations for persistent objects using RTTI.
Persistent object updated in the method.
Updates string translations for persistent objects.

UpdateTranslation is procedure used to translate string properties in the specified persistent object instance. UpdateTranslation uses RTTI (Run Time Type Information) to update the value for translatable properties in Lazarus resources. This requires properties to be a TPersistent descendant with RTTI enabled, and have a setter (write access) procedure. Strings, Classes, Components and the sub-Components are handled in the method.

Persistent object updated in the method.
Performs string translations using a .mo file (Machine Object).

TDefaultTranslator is a TUpdateTranslator descendant used to translate string properties using the values defined in a .mo (Machine Object) file. A .mo file is the binary format used for translation resources created for the GNU gettext program. TDefaultTranslator implements the abstract TranslateStringProperty method defined in the ancestor class.

Use TPOTranslator to translate string properties using the .po (Portable Object) file format.

Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited constructor. Create initializes and stores a TMOFile instance using the file name specified in the MOFileName parameter. Create calls UTF8ToSys to convert any UTF-8-encoded values in MOFileName to the default encoding used for the platform or OS.

.mo file used in the class instance.
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to an internal TMOFile member are freed prior to calling the inherited destructor.

Gets the translated value for the specified property.

TranslateStringProperty is a procedure used to get the translated value for the specified property from the .mo file used in the class instance.

Sender is the class instance requesting the translation action.

Instance is the TPersistent object instance affected in the method.

PropInfo contains the RTTI property information needed to update the property value.

TranslateStringProperty uses the internal TMOFile instance created in the constructor to get the translated value for the property name. The translated string value is stored in the Content argument and returned to the caller. The property value is actually updated in the caller.

No actions are performed in the method if a .mo file was not found with the required file name.

Class instance calling the method.
Persistent object with properties affected in the method.
RTTI Property information.
Value for the translated string property.
Performs string translations using a .po (Portable Object) file.

TPOTranslator is a TUpdateTranslator descendant used to translate string properties using the values defined in a .po (Portable Object) file. A .po file is the text format used for translation resources created for the GNU gettext program. TPOTranslator implements the abstract TranslateStringProperty method defined in the ancestor class.

Use TDefaultTranslator to translate string properties using the .mo (Machine Object) file format.

Constructor for the class instance.

Create is the overloaded constructor for the class instance. Both variant call the inherited constructor to initialize the class instance. The overloaded variants allow use of a file name or a TPOFile instance in the class. TPOTranslator contains an internal TPOFile member which is used to access the translated string values.

POFileName contains the file name which constains the translated values for strings. A TPOFile instance is created for the specified file name.

aPOFile is the TPPOFile class instance which contains the translated values for strings.

.po file name to use for translated string values.
.po file to use for translated string values.
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to the internal TPOFile member in the class instance are freed. Destroy calls the inherited destructor.

Gets the translated value for the specified property.

TranslateStringProperty is a procedure used to get the translated value for the specified property from the .po file used in the class instance.

Sender is the class instance requesting the translation action.

Instance is the TPersistent object instance affected in the method.

PropInfo contains the RTTI property information needed to update the property value.

TranslateStringProperty uses the internal TPOFile instance created in the constructor to get the translated value for the property. The translated string value is stored in the Content argument and returned to the caller. The property value is actually updated in the caller.

No actions are performed in the method if a .po file was not found with the required file name.

Class instance calling the method.
Persistent object with properties affected in the method.
RTTI Property information.
Value for the translated string property.
Translates resource strings in LCLStrConsts to the specified language.

TranslateLCLResourceStrings is a String function used to translate resource strings in the LCLStrConsts unit to the language identifier specified in the Lang argument.

Dir is an optional path where .PO or .MO files can be found with the translated values for string constants.

TranslateLCLResourceStrings calls FindLocaleFileName to locate the .PO or .MO file. Preference is given to the .PO variant. If it is locate in the speciifed path, the TranslateUnitResourceStrings routine is called to tranlate constants from the LCLStrConts unit.

If a .PO file is not found, FindLocaleFileName is called to locate a .MO file used for translation. When found, the TranslateResourceStrings routine is called to translate string using the .MO file in the specified path.

The return value contains the name of the .PO or .MO file used to translate string constants, or an empty string when a file is not found in the path specified in Dir.

Language identifier for the translated constants.
Path to the .MO or .PO file used for the translation.
File name used for the translation, or an empty when translation is not available.
Sets the default language used for string translations.

SetDefaultLang is a procedure used to the set the default language used for string translations.

Lang contains the Language ID to use for translated strings. Lang contains a language identifier defined in ISO 639, at: ISO 639 - Codes for the Representation of Names of Languages

The default value for the parameter is an empty string (''), and indicates that strings are not translated.

Dir contains the directory name where .po/.mo files are stored. The default value is an empty string (''), and indicates that the default directories are used for translation files.

LocaleFileName contain the localization file used for for strings. This file handles variations in grammar and spelling that occur in local dialects for a language. It contains a value like 'zh_cn' or 'pt_br'. The default value is an empty string (''), and indicates that localization is not preformed for resource strings.

ForceUpdate indicates if an immediate update to to the User Interface is performed when translations are loaded. Set ForceUpdate to False when SetDefaultLang is called from the initialization section for a unit. The default value is True.

SetDefaultLang ensures that Language ID and Locale Codes are valid, and .po/.mo exist for the specified names before they are applied. SetDefaultLang calls the FindLocaleFileName function to get the file name used for translation resources. .po files are applied when they exist. Otherwise, .mo file are used to get the translated string values. LCL resource string constants are also translated when the default language code is assigned.

When ForceUpdate contains True, string properties used in Forms, Data Modules, Controls, Components and Persistent objects are translated. This action is performed for items with RTTI (Run Time Type Information) and includes a setter (write access) procedure. TUpdateTranslator is used to perform the update to user interface elements.

Language ID to use for translated strings.
Directory name with translation files.
Locale code for the localization file.
Indicates if the UI should be updated immediately.
Default language code in use.
Deprecated.
Deprecated. Use the result from the SetDefaultLang function instead.
Deprecated in LCL version 2.1.0.
Default language code currently in use.