13.1 Internationalization of Strings Function ¶

The subroutines gdt or pgdt, are used for translated strings:

Function: $translated_tree = $converter->gdt ($string, \%variables_hash, $translation_context, $mode) ¶

Function: $translated_tree = $converter->pgdt ($translation_context, $string, \%variables_hash, $mode) ¶

$string is the string to be translated, \%variables_hash is a hash reference holding the variable parts of the translated string. $translation_context is an optional translation context that limits the search of the translated string to that context (see Contexts in GNU gettext tools). The result returned is a perl Texinfo tree in the default case.

$mode is an optional string which may modify how the function behaves. The possible values are:

translated_text

In that case the string is not considered to be Texinfo, a plain string that is returned after translation and substitution. The substitutions may only be strings in that case.

If called as pgdt, $translation_context is not optional and is the first argument.

When the string is expanded as Texinfo, and converted to a Texinfo tree in perl, the arguments are substituted; for example, ‘{arg_name}’ is replaced by the corresponding actual argument, which should be Texinfo perl trees, Texinfo perl tree contents arrays or strings.

In the following example, ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are the arguments of the string. Since they are used in @uref, their order in the formatted output depends on the formatting and is not predictable. ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are substituted after the expansion, which means that they should already be Texinfo perl trees, Texinfo perl tree contents. A string is turned into a Texinfo text element without type, with the string as text.

  $converter->gdt('Generated @emph{@today{}} using '
   .'@uref{{program_homepage}, @emph{{program}}}.',
      { 'program_homepage' => $converter->get_conf('PACKAGE_URL'),
        'program' => { 'text' => $converter->get_conf('PROGRAM') }}));

In the example, the $converter->get_conf('PACKAGE_URL') string is turned into { 'text' => $converter->get_conf('PACKAGE_URL') }.

An example of combining conversion with translation:

$converter->convert_tree($converter->gdt(
       '{explained_string} ({explanation})',
       {'explained_string' => {'type' => '_converted',
                               'text' => $result},
        'explanation' => {'type' => '_converted',
                          'text' => $explanation_result}}),
                         "convert explained $cmdname");

In the default case, the gdt function from the Texinfo::Translations module is used for translated strings. It is possible to use a user-defined function instead as seen next. See (texi2any_internals)Texinfo::Translations for more on Texinfo::Translations.

In texi2any code, gdt is also used to mark translated strings for tools extracting translatable strings to produce template files. pgdt is used to mark translated string with a translation context associated.