mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-08-11 11:35:57 +02:00
595 lines
21 KiB
XML
595 lines
21 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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 > Project Options >
|
|
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>
|
|
|
|
<element name="TUpdateTranslator.FStackPath"/>
|
|
|
|
<element name="TUpdateTranslator.IntUpdateTranslation">
|
|
<short>
|
|
Performs action required to update string translations for persistent objects
|
|
using RTTI.
|
|
</short>
|
|
<descr></descr>
|
|
<seealso>
|
|
<link id="TUpdateTranslator.UpdateTranslation"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TUpdateTranslator.IntUpdateTranslation.AnInstance">
|
|
<short>Persistent object updated in the method.</short>
|
|
</element>
|
|
|
|
<element name="TUpdateTranslator.UpdateTranslation">
|
|
<short>Updates string translations for persistent objects.</short>
|
|
<descr>
|
|
<p>
|
|
<var>UpdateTranslation</var> 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.
|
|
</p>
|
|
</descr>
|
|
<seealso></seealso>
|
|
</element>
|
|
<element name="TUpdateTranslator.UpdateTranslation.AnInstance">
|
|
<short>Persistent object updated 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>
|
|
|
|
<element name="TDefaultTranslator.FMOFile"/>
|
|
|
|
<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></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></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></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>
|
|
|
|
<element name="TPOTranslator.FPOFile"/>
|
|
|
|
<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></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></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.<Lang>.po</file> or
|
|
<file>lclstrconsts.<Lang>.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>
|