15.1 Internationalization of Strings Function ¶

The subroutines cdt, cdt_string or pcdt, are used for translated strings:

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

Function: $translated_string = $converter->cdt_string ($string, \%variables_hash, $translation_context) ¶

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

$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 for cdt and pcdt and a string for cdt_string. With cdt_string the substitutions may only be strings.

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

With cdt and pcdt, 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 a Texinfo tree element. With cdt_string, the string should already be converted, the arguments are substituted as strings; for example ‘{arg_name}’ is replaced by the corresponding actual argument, which should be a string.

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 tree elements.

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

An example of combining conversion with translation:

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

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

In texi2any code, cdt and cdt_string are also used to mark translated strings for tools extracting translatable strings to produce template files. pcdt is used to mark translated string with a translation context associated.