path: root/fpcdocs/gettext.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<package name="fcl">

<!--
  ====================================================================
    gettext
  ====================================================================
-->

<module name="gettext">
<short>Unit implementing resource string translation using gettext files</short>
<descr>
<p>The <file>gettext</file> unit can be used to hook into the resource string mechanism
of Free Pascal to provide translations of the resource strings, based on the
GNU gettext mechanism. The unit provides a class (<link id="TMOFile"/>) to read 
the <file>.mo</file> files with localizations for various languages. It
also provides a couple of calls to translate all resource strings in an
application based on the translations in a <file>.mo</file> file.</p>
</descr>

<!-- unresolved type reference Visibility: default -->
<element name="SysUtils">
<short>Exception and string formatting support.</short>
</element>

<!-- unresolved type reference Visibility: default -->
<element name="Classes">
<short>Stream support</short>
</element>

<!-- constant Visibility: default -->
<element name="MOFileHeaderMagic">
<short>file header bytes indicating a <file>.mo</file> file.</short>
<descr>
This constant is found as the first integer in a <file>.mo</file>
</descr>
<seealso>
<link id="TMOFileHeader"/>
</seealso>
</element>

<!-- record type Visibility: default -->
<element name="TMOFileHeader">
<short>Structure found at the head of a <file>.mo</file> file.</short>
<descr>
This structure describes the structure of a <file>.mo</file> file with
string localizations.
</descr>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.magic">
<short>Magic constant, should equal <link id="#fcl.gettext.MOFileHeaderMagic">MOFileHeaderMagic</link>.</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.revision">
<short>File revision</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.nstrings">
<short>Number of string pairs in the file</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.OrigTabOffset">
<short>Offset of the original strings description table.</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.TransTabOffset">
<short>Offset of the translated strings description table.</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.HashTabSize">
<short>Size of hashing table.</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOFileHeader.HashTabOffset">
<short>Offset of hashing table.</short>
</element>

<!-- record type Visibility: default -->
<element name="TMOStringInfo">
<short>Structure describing string</short>
<descr>
This record is one element in the string tables describing the original and
translated strings. It describes the position and length of the string. The
location of these tables is stored in the <link id="TMOFileHeader"/> record
at the start of the file.
</descr>
<seealso>
<link id="TMOFileHeader"/>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TMOStringInfo.length">
<short>Length of the string</short>
</element>

<!-- variable Visibility: default -->
<element name="TMOStringInfo.offset">
<short>Offset in the file</short>
</element>

<!-- array type Visibility: default -->
<element name="TMOStringTable">
<short>Array of <link id="#fcl.gettext.TMOStringInfo">TMOStringInfo</link> records.</short>
<descr>
<var>TMOStringTable</var> is an array type containing <link id="TMOStringInfo"/> records.
It should never be used directly, as it would occupy too much memory.
</descr>
<seealso>
<link id="PMOStringTable"/>
</seealso>
</element>

<!-- pointer type Visibility: default -->
<element name="PMOStringTable">
<short>Pointer to a <link id="#fcl.gettext.TMOStringTable">TMOStringTable</link> array.</short>
</element>

<!-- array type Visibility: default -->
<element name="TLongWordArray">
<short>Array of <var>longword</var> elements.</short>
<descr>
<var>TLongWordArray</var> is an array used to define the <link id="PLongWordArray"/> pointer.
A variable of type <var>TLongWordArray</var> should never be directly
declared, as it would occupy too much memory.  The <var>PLongWordArray</var> type can be used 
to allocate a dynamic number of elements.
</descr>
<seealso>
<link id="PLongWordArray"/>
</seealso>
</element>

<!-- pointer type Visibility: default -->
<element name="PLongWordArray">
<short>Pointer to a <link id="#fcl.gettext.TLongWordArray">TLongWordArray</link> array.</short>
</element>

<!-- array type Visibility: default -->
<element name="TPCharArray">
<short>Array of <var>PChar</var> elements</short>
<descr>
<var>TLongWordArray</var> is an array used to define the <link id="PPCharArray"/> pointer.
A variable of type <var>TPCharArray</var> should never be directly declared, as it would 
occupy too much memory. The <var>PPCharArray</var> type can be used to allocate a dynamic 
number of elements.
</descr>
<seealso>
<link id="PPCharArray"/>
</seealso>
</element>

<!-- pointer type Visibility: default -->
<element name="PPCharArray">
<short>Pointer to a <link id="#fcl.gettext.TPCharArray">TPCharArray</link> array.</short>
</element>

<!--
  ********************************************************************
    #fcl.gettext.TMOFile
  ********************************************************************
-->

<!-- object Visibility: default -->
<element name="TMOFile">
<short>Class providing access to a <file>.mo</file> file.</short>
<descr>
<var>TMOFile</var> is a class providing easy access to a <file>.mo</file> file.
It can be used to translate any of the strings that reside in the
<file>.mo</file> file. The internal structure of the <file>.mo</file> is
completely hidden.
</descr>
</element>

<!-- constructor Visibility: public -->
<element name="TMOFile.Create">
<short>Create a new instance of the <var>TMOFile</var> class.</short>
<descr>
<p>
<var>Create</var> creates a new instance of the <var>MOFile</var> class. 
It opens the file <var>AFileName</var> or the stream <var>AStream</var>.
If a stream is provided, it should be seekable.
</p>
<p>
The whole contents of the file is read into memory during the
<var>Create</var> call. This means that the stream is no longer 
needed after the <var>Create</var> call. 
</p>
</descr>
<errors>
If the named file does not exist, then an exception may be raised. If the
file does not contain a valid <link id="TMOFileHeader"/> structure, then 
an <link id="EMOFileError"/> exception is raised.
</errors>
<seealso>
<link id="TMOFile.Destroy"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TMOFile.Create.AFilename">
<short>File to open.</short>
</element>

<!-- argument Visibility: default -->
<element name="TMOFile.Create.AStream">
<short>Contents of a .mo file.</short>
</element>

<!-- destructor Visibility: public -->
<element name="TMOFile.Destroy">
<short>Removes the <var>TMOFile</var> instance from memory</short>
<descr>
<var>Destroy</var> cleans the internal structures with the contents of the
<file>.mo</file>. After this the <var>TMOFile</var> instance is removed from
memory.
</descr>
<seealso>
<link id="TMOFile.Create"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TMOFile.Translate">
<short>Translate a string</short>
<descr>
<p>
<var>Translate</var> translates the string <var>AOrig</var>. 
The string should be in the .mo file as-is. The string can be given as a
plain string, as a <var>PChar</var> (with length <var>ALen</var>). If the
hash value (<var>AHash</var>) of the string is not given, it is calculated.
</p>
<p>
If the string is in the <var>.mo</var> file, the translated string is
returned. If the string is not in the file, an empty string is returned.
</p>
</descr>
<errors>
None.
</errors>
</element>

<!-- function result Visibility: default -->
<element name="TMOFile.Translate.Result">
<short>Translated string.</short>
</element>

<!-- argument Visibility: default -->
<element name="TMOFile.Translate.AOrig">
<short>String to translate.</short>
</element>

<!-- argument Visibility: default -->
<element name="TMOFile.Translate.ALen">
<short>Length of the original string.</short>
</element>

<!-- argument Visibility: default -->
<element name="TMOFile.Translate.AHash">
<short>Hash value of the original string.</short>
</element>

<!--
  ********************************************************************
    #fcl.gettext.EMOFileError
  ********************************************************************
-->

<!-- object Visibility: default -->
<element name="EMOFileError">
<short>Exception raised in case of an error.</short>
<descr>
<var>EMOFileError</var> is raised in case an <link id="TMOFile"/> instance
is created with an invalid <file>.mo</file>.
</descr>
<seealso>
<link id="TMOFile"/>
</seealso>
</element>

<!-- procedure Visibility: default -->
<element name="GetLanguageIDs">
<short>Return the current language IDs</short>
<descr>
<var>GetLanguageIDs</var> returns the current language IDs (an ISO string) as 
returned by the operating system. On windows, the <var>GetUserDefaultLCID</var> 
and <var>GetLocaleInfo</var> calls are  used. On other operating systems,
the <var>LC_ALL</var>, <var>LC_MESSAGES</var> or <var>LANG</var> environment
variables are examined.
</descr>
</element>

<!-- argument Visibility: default -->
<element name="GetLanguageIDs.Lang">
<short>Primary language</short>
</element>

<!-- argument Visibility: default -->
<element name="GetLanguageIDs.FallbackLang">
<short>Secondary language</short>
</element>

<!-- procedure Visibility: default -->
<element name="TranslateResourceStrings">
<short>Translate the resource strings of the application.</short>
<descr>
<var>TranslateResourceStrings</var> translates all the resource strings 
in the application based on the values in the <file>.mo</file> file 
<var>AFileName</var> or <var>AFile</var>. 
The procedure creates an <link id="TMOFile"/> instance to
read the <file>.mo</file> file if a filename is given.
</descr>
<errors>
If the file does not exist or is an invalid <file>.mo</file> file.
</errors>
<seealso>
<link id="TranslateUnitResourceStrings"/>
<link id="TMOFile"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TranslateResourceStrings.AFile">
<short><var>TMOfile</var> instance with translated strings.</short>
</element>

<!-- argument Visibility: default -->
<element name="TranslateResourceStrings.AFilename">
<short>Name of <file>.mo</file> file with translated strings</short>
</element>

<!-- procedure Visibility: default -->
<element name="TranslateUnitResourceStrings">
<short>Translate the resource strings of a unit.</short>
<descr>
<var>TranslateUnitResourceStrings</var> is identical in function to
<link id="TranslateResourceStrings"/>, but translates the strings of a
single unit (<var>AUnitName</var>) which was used to compile the 
application. This can be more convenient, since the resource string files
are created on a unit basis.
</descr>
<seealso>
<link id="TranslateResourceStrings"/>
<link id="TMOFile"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TranslateUnitResourceStrings.AUnitName">
<short>Name of the unit whose strings should be translated.</short>
</element>

<!-- argument Visibility: default -->
<element name="TranslateUnitResourceStrings.AFile">
<short><var>TMOFile</var> instance with translated strings.</short>
</element>

<!-- argument Visibility: default -->
<element name="TranslateUnitResourceStrings.AFilename">
<short>Name of <file>.mo</file> file with translated strings</short>
</element>

</module> <!-- gettext -->

</package>
</fpdoc-descriptions>