<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
file://../../cc-by-sa-4-0.txt

Copyright (c) 1997-2023, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
LCLTranslator
====================================================================
-->
<module name="LCLTranslator">
<short>
Performs string translation in the Lazarus IDE and LCL.
</short>
<descr>
<p>
<file>lcltranslator.pas</file> 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 <b>languages</b> or <b>locale</b> 
directories. To access translation files from an alternate location, use the 
LResources unit and the LRSMoFile variable directly.
</p>
<p>
To enable string translation, use this unit in your application and check the 
<b>Enable i18n</b> option in the <b>Project &gt; Project Options &gt; 
i18n</b> 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.
</p>
<p>
This unit also translates LCL string constants in the 
<file>lclstrconsts</file> file using files in the directory where program 
translation files are stored.
</p>
<p>
For more information, see the Lazarus Wiki article:
</p>
<p>
<url 
href="http://wiki.lazarus.freepascal.org/Step-by-step_instructions_for_creating_multi-language_applications">
Creating Multi-Language Applications
</url>
</p>
<p>
<file>lcltranslator.pas</file> is part of the Lazarus Component Library 
(<b>LCL</b>).
</p>
</descr>

<element name="Classes"/>
<element name="SysUtils"/>
<element name="TypInfo"/>
<element name="GetText"/>
<element name="LResources"/>
<element name="Forms"/>
<element name="LCLType"/>
<element name="LazLoggerBase"/>
<element name="Translations"/>
<element name="LazFileUtils"/>
<element name="LazUTF8"/>

<element name="TUpdateTranslator">
<short>
Performs string translations for persistent objects.
</short>
<descr>
<p>
<var>TUpdateTranslator</var> 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.
</p>
<p>
TUpdateTranslator is used as the ancestor for the TDefaultTranslator and 
TPOTranslator classes.
</p>
</descr>
<seealso>
<link id="LResources.TAbstractTranslator"/>
<link id="TDefaultTranslator"/>
<link id="TPOTranslator"/>
</seealso>
</element>

<!-- private -->
<element name="TUpdateTranslator.FStackPath"/>
<element name="TUpdateTranslator.IntUpdateTranslation"/>
<element name="TUpdateTranslator.IntUpdateTranslation.AnInstance"/>
<element name="TUpdateTranslator.IntUpdateTranslation.Level"/>

<!-- public -->
<element name="TUpdateTranslator.UpdateTranslation">
<short>
Updates translations for string properties in a persistent object.
</short>
<descr>
<p>
<var>UpdateTranslation</var> is method used to translate string properties 
in the specified persistent object instance. UpdateTranslation uses RTTI 
(Run-Time Type Information) to access and update the values for translatable 
properties found in the object instance.
</p>
<p>
<var>AnInstance</var> is a TPersistent descendant with the RTTI used to access 
the values for readable properties and other members in the class instance.
</p>
<p>
UpdateTranslation ensures that translation is performed for writable string 
properties defined using the TTranslateString type. Translation is not 
performed for a property if it does not have a setter routine (write access 
specifier).
</p>
<p>
UpdateTranslation recursively checks for translatable properties in members 
defined using TCollection, TPersistent, TComponent, or TCustomFrame types.
</p>
<p>
UpdateTranslation is called from the SetDefaultLang routine and occurs when 
translations are updated after setting a new default language value.
</p>
</descr>
<version>
Modified in LCL version 3.0 to ensure that read-only members are checked for 
translatable properties. Write access is checked before a property is 
translated and updated with the new value.
</version>
<seealso>
<link id="TDefaultTranslator.TranslateStringProperty"/>
<link id="TPOTranslator.TranslateStringProperty"/>
<link id="SetDefaultLang"/>
</seealso>
</element>
<element name="TUpdateTranslator.UpdateTranslation.AnInstance">
<short>
Persistent object with properties translated in the method.
</short>
</element>

<element name="TDefaultTranslator">
<short>
Performs string translations using a .mo file (Machine Object).
</short>
<descr>
<p>
<var>TDefaultTranslator</var> is a <var>TUpdateTranslator</var> descendant 
used to translate string properties using the values defined in a .mo 
(<b>Machine Object</b>) file. A .mo file is the binary format used for 
translation resources created for the <b>GNU gettext</b> program. 
TDefaultTranslator implements the abstract TranslateStringProperty method 
defined in the ancestor class.
</p>
<p>
Use TPOTranslator to translate string properties using the .po (<b>Portable 
Object</b>) file format.
</p>
</descr>
<seealso>
<link id="TUpdateTranslator"/>
<link id="TPOTranslator"/>
</seealso>
</element>

<!-- private -->
<element name="TDefaultTranslator.FMOFile"/>

<!-- public -->
<element name="TDefaultTranslator.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> 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.
</p>
</descr>
<seealso/>
</element>
<element name="TDefaultTranslator.Create.MOFileName">
<short>.mo file used in the class instance.</short>
</element>

<element name="TDefaultTranslator.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> 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.
</p>
</descr>
<seealso/>
</element>

<element name="TDefaultTranslator.TranslateStringProperty">
<short>
Gets the translated value for the specified property.
</short>
<descr>
<p>
<var>TranslateStringProperty</var> is a procedure used to get the translated 
value for the specified property from the .mo file used in the class instance.
</p>
<p>
Sender is the class instance requesting the translation action.
</p>
<p>
Instance is the TPersistent object instance affected in the method.
</p>
<p>
PropInfo contains the RTTI property information needed to update the property 
value.
</p>
<p>
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.
</p>
<p>
No actions are performed in the method if a .mo file was not found with the 
required file name.
</p>
</descr>
<seealso/>
</element>
<element name="TDefaultTranslator.TranslateStringProperty.Sender">
<short>Class instance calling the method.</short>
</element>
<element name="TDefaultTranslator.TranslateStringProperty.Instance">
<short>Persistent object with properties affected in the method.</short>
</element>
<element name="TDefaultTranslator.TranslateStringProperty.PropInfo">
<short>RTTI Property information.</short>
</element>
<element name="TDefaultTranslator.TranslateStringProperty.Content">
<short>Value for the translated string property.</short>
</element>

<element name="TPOTranslator">
<short>
Performs string translations using a .po (Portable Object) file.
</short>
<descr>
<p>
<var>TPOTranslator</var> is a <var>TUpdateTranslator</var> descendant used to 
translate string properties using the values defined in a .po (<b>Portable 
Object</b>) file. A .po file is the text format used for translation 
resources created for the <b>GNU gettext</b> program. TPOTranslator 
implements the abstract TranslateStringProperty method defined in the 
ancestor class.
</p>
<p>
Use TDefaultTranslator to translate string properties using the .mo 
(<b>Machine Object</b>) file format.
</p>
</descr>
<seealso>
<link id="TUpdateTranslator"/>
<link id="TDefaultTranslator"/>
</seealso>
</element>

<!-- private -->
<element name="TPOTranslator.FPOFile"/>

<!-- public -->
<element name="TPOTranslator.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> 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 <var>TPOFile</var> instance 
in the class. TPOTranslator contains an internal TPOFile member which is used 
to access the translated string values.
</p>
<p>
POFileName is the file name which contains the translated values for strings. 
A TPOFile instance is created for the specified file name.
</p>
<p>
aPOFile is the TPPOFile class instance which contains the translated values 
for strings.
</p>
</descr>
<seealso/>
</element>
<element name="TPOTranslator.Create.POFileName">
<short>.po file name to use for translated string values.</short>
</element>
<element name="TPOTranslator.Create.aPOFile">
<short>.po file to use for translated string values.</short>
</element>

<element name="TPOTranslator.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> 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.
</p>
</descr>
<seealso/>
</element>

<element name="TPOTranslator.TranslateStringProperty">
<short>
Gets the translated value for the specified property.
</short>
<descr>
<p>
<var>TranslateStringProperty</var> is a procedure used to get the translated 
value for the specified property from the .po file used in the class instance.
</p>
<p>
Sender is the class instance requesting the translation action.
</p>
<p>
Instance is the TPersistent object instance affected in the method.
</p>
<p>
PropInfo contains the RTTI property information needed to update the property 
value.
</p>
<p>
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.
</p>
<p>
No actions are performed in the method if a .po file was not found with the 
required file name.
</p>
</descr>
</element>
<element name="TPOTranslator.TranslateStringProperty.Sender">
<short>Class instance calling the method.</short>
</element>
<element name="TPOTranslator.TranslateStringProperty.Instance">
<short>Persistent object with properties affected in the method.</short>
</element>
<element name="TPOTranslator.TranslateStringProperty.PropInfo">
<short>RTTI Property information.</short>
</element>
<element name="TPOTranslator.TranslateStringProperty.Content">
<short>Value for the translated string property.</short>
</element>

<element name="TranslateLCLResourceStrings">
<short>
Translates resource strings in <file>LCLStrConsts.pas</file> using 
localization files for the specified language.
</short>
<descr>
<p>
<var>TranslateLCLResourceStrings</var> is a <var>String</var> function used 
to translate resource strings in the <file>LCLStrConsts.pas</file> unit to 
the language identifier specified in the <var>Lang</var> argument. Lang can 
contain a value as defined in ISO 639, at:
</p>
<p>
<url href="http://www.loc.gov/standards/iso639-2/php/code_list.php">
ISO 639 - Codes for the Representation of Names of Languages
</url>.
</p>
<p>
For example: 'de' or 'ru'. An empty string (<b>''</b>) causes the default 
language for the system to be used.
</p>
<p>
<var>Dir</var> is the optional path where .po or .mo files with the 
translated values for string constants are located. An empty string 
(<b>''</b>) causes the predefined directories, like 'languages' or 'locale', 
to be used. This is the location where the 
<file>lclstrconsts.&lt;Lang&gt;.po</file> or 
<file>lclstrconsts.&lt;Lang&gt;.mo</file> localization file for the 
<file>lclstrconsts.pas</file> unit is stored.
</p>
<p>
TranslateLCLResourceStrings calls the TranslateUnitResourceStringsEx routine 
using the specified parameter values as arguments, and 'lclstrconsts' as the 
base unit name for the translation. TranslateUnitResourceStringsEx resolves 
the path, language identifier, and file extension needed for the platform or 
operating system and applies the translated values.
</p>
<p>
The return value contains the language identifier or locale code used in the 
translation. It may contain an empty string (<b>''</b>) if a localization 
file is not found for the language or an error occurs.
</p>
</descr>
<seealso>
<link id="TranslateUnitResourceStringsEx"/>
<link id="#lazutils.translations.TranslateUnitResourceStrings">TranslateUnitResourceStrings</link>
</seealso>
</element>
<element name="TranslateLCLResourceStrings.Lang">
<short>Language identifier for the translated constants.</short>
</element>
<element name="TranslateLCLResourceStrings.Dir">
<short>Path to the .po or .mo file used for the translation.</short>
</element>
<element name="TranslateLCLResourceStrings.Result">
<short>
Language code used for the translation, or an empty string ('') when a 
translation is not available or an error has occurred.
</short>
</element>

<element name="TranslateUnitResourceStringsEx">
<short>
Translates string constants in a unit using the localization file for the 
specified language and path.
</short>
<descr>
<p>
<var>TranslateUnitResourceStringsEx</var> is a convenience routine used to 
translate string constants in a specified source file to a given language. It 
provides arguments which identify the source file, the path to localization 
files, and the language requested.
</p>
<p>
<var>Lang</var> contains the optional language identifier requested for the 
translated string constants. It contains a value like 'en', 'ru' or 'de'. An 
empty string (<b>''</b>) causes the default language identifier for the 
platform or operating system to be used.
</p>
<p>
<var>Dir</var> contains the path where the localization files (.po, .mo) are 
located. It can contain a path relative to the directory for the application 
executable, or a fully qualified path to the directory with the localization 
files. For example: 'languages' or '/usr/share/locale'. An empty string 
(<b>''</b>) indicates that the predefined directories like 'languages' or 
'locale' are used to locate the localization files.
</p>
<p>
<var>LocaleFileName</var> contains the base name for the localization file 
used to translate the values in the specified unit. It contains a value like 
'lazaruside' or 'lclstrconts'. No actions are performed in the routine when 
LocaleFileName is an empty string ('').
</p>
<p>
<var>LocaleUnitName</var> contains the base name for the source code file 
with the string constants translated in the routine. An empty string 
(<b>''</b>) causes the value in LocaleFileName to be used as the base source 
code file name.
</p>
<p>
TranslateUnitResourceStringsEx calls the FindLocaleFileName implementation 
routine to resolve the requested language identifier, and the path and file 
extension for the localization files. .po files are given preference, and .mo 
files are used when a .po equivalent is not available.
</p>
<p>
TranslateUnitResourceStringsEx calls the TranslateUnitResourceStrings routine 
in the <file>translations.pp</file> unit to translate the specified file 
using the path to the localization file.
</p>
<p>
TranslateUnitResourceStringsEx calls the TranslateResourceStrings routine in 
the FCL <file>gettext.pp</file> unit to translate using a .mo file when a 
path to .po files is not found.
</p>
<p>
The return value contains the language code or locale ID used in the 
translation. An empty string ('') in the return value indicates that a 
localization file for the specified arguments was not found, or that an error 
occurred during the translation.
</p>
</descr>
<seealso>
<link id="#lazutils.translations.TranslateUnitResourceStrings">Translations.TranslateUnitResourceStrings</link>
<link id="#lazutils.translations.TranslateResourceStrings">Translations.TranslateResourceStrings</link>
</seealso>
</element>
<element name="TranslateUnitResourceStringsEx.Result">
<short>
The language code or locale ID used in the translation, or an empty string 
when a translation is not available or an error has occurred.
</short>
</element>
<element name="TranslateUnitResourceStringsEx.Lang">
<short>Optional language identifier requested for the translation.</short>
</element>
<element name="TranslateUnitResourceStringsEx.Dir">
<short>
Optional path to the localization files used in the translation.
</short>
</element>
<element name="TranslateUnitResourceStringsEx.LocaleFileName">
<short>Base name for the localization file used in the translation.</short>
</element>
<element name="TranslateUnitResourceStringsEx.LocaleUnitName">
<short>
Optional base name of the unit with strings translated in the routine.
</short>
</element>

<element name="SetDefaultLang">
<short>
Sets the default language used for string translations.
</short>
<descr>
<p>
<var>SetDefaultLang</var> is a procedure used to the set the default language 
used for string translations.
</p>
<p>
<var>Lang</var> contains the Language identifier used to translate strings. 
Lang contains a value as defined in ISO 639, at:
</p>
<p>
<url href="http://www.loc.gov/standards/iso639-2/php/code_list.php">
ISO 639 - Codes for the Representation of Names of Languages
</url>
</p>
<p>
The default value for the parameter is an empty string (<b>''</b>), and 
indicates that the default language identifier for the system should be used. 
This value can be passed as a command line argument (like '--lang ru' or 
'--lang=es'). The value also can be overridden using the <b>LANG</b> 
environment variable. The fallback value is the language identifier for the 
platform. For Windows, this is the language code and country code from 
GetLocaleInfo in a format like 'en_US' or 'zh_CN'. For other platforms, the 
value from either the <b>LC_ALL</b> or <b>LC_MESSAGE</b> environment 
variables is used as the fallback.
</p>
<p>
<var>Dir</var> contains the name of the directory where .po or .mo 
localization files are stored, like 'mylng'. The default value is an empty 
string (<b>''</b>), and indicates that the predefined directories like 
'languages' or 'locale' are used to find the localization files for the 
translation.
</p>
<p>
<var>LocaleFileName</var> contains the base name for the localization file 
used to translate string values, like 'lazaruside' or 'debuggerstrconst'. The 
default value for the argument is an empty string (<b>''</b>) and causes the 
base name for the application executable to be used, like 'project1' for 
'project1.exe'.
</p>
<p>
When combined with the language identifier and the '.po' or '.mo' file 
extension, it forms the complete file name with the localized string values. 
For example: 'lazaruside.ru.po', 'debuggerstrconst.zh_CN.po', or 
'project1.es.po'. The value in the Dir argument is prepended to form the 
complete path to the localization file.
</p>
<p>
<var>ForceUpdate</var> indicates if an immediate update to the user interface 
is performed when translations are loaded. Set ForceUpdate to <b>False</b> 
when SetDefaultLang is called from the initialization section in a unit. The 
default value is <b>True</b>.
</p>
<p>
SetDefaultLang ensures that the language ID / locale codes are valid, and .po 
or .mo files exist with the specified values 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 using 
TranslateLCLResourceStrings when a localization file is found with the 
specified values.
</p>
<p>
When ForceUpdate contains <b>True</b>, string properties used in Forms, Data 
Modules, Controls, Components and Persistent objects are translated. This 
action is performed for members with RTTI (Run Time Type Information) which 
include a setter (write access) procedure. TUpdateTranslator is used to 
perform the update to user interface elements.
</p>
</descr>
<seealso>
<link id="TranslateLCLResourceStrings"/>
<link id="TPOTranslator"/>
<link id="TDefaultTranslator"/>
<link id="TUpdateTranslator"/>
</seealso>
</element>
<element name="SetDefaultLang.Lang">
<short>
Language ID requested for translated strings, or '' to use the system default.
</short>
</element>
<element name="SetDefaultLang.Dir">
<short>
Directory with the localization files, or '' to use the predefined 
directories.
</short>
</element>
<element name="SetDefaultLang.LocaleFileName">
<short>
Base name for the localization file, or '' to use the base name for the 
executable file.
</short>
</element>
<element name="SetDefaultLang.ForceUpdate">
<short>
Indicates if the UI should be updated immediately.
</short>
</element>
<element name="SetDefaultLang.Result">
<short>
Language code used for the translation, or an empty string when a language 
code is not available or an error occurs.
</short>
</element>

</module>
<!-- LCLTranslator -->
</package>
</fpdoc-descriptions>
