8 Texinfo::Translations


8.1 Texinfo::Translations NAME

Texinfo::Translations - Translations of output documents strings for Texinfo modules


8.2 Texinfo::Translations SYNOPSIS

  @ISA = qw(Texinfo::Translations);

  Texinfo::Translations::configure('LocaleData');

  my $tree_translated
    = Texinfo::Translations::gdt('See {reference} in @cite{{book}}',
                           $converter->get_conf('documentlanguage'),
                          {'reference' => $tree_reference,
                           'book'  => {'text' => $book_name}});

8.3 Texinfo::Translations NOTES

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats. There is no promise of API stability.


8.4 Texinfo::Translations DESCRIPTION

The Texinfo::Translations module helps with translations in output documents.

Translation of error messages is not described here, some elements are in Texinfo::Common __ and __p.


8.5 Texinfo::Translations METHODS

No method is exported.

The configure method sets the translation files base directory. If not called, system defaults are used.

configure($localesdir, $strings_textdomain)

$localesdir is the directory where translation files are found. The directory structure and files format should follow the conventions expected for gettext based internationalization. The $strings_textdomain is optional, if set, it determines the translation domain.

The gdt and pgdt methods are used to translate strings to be output in converted documents, and return a Texinfo tree. The gdt_string is similar but returns a simple string, for already converted strings.

$tree = gdt($string, $lang, $replaced_substrings, $translation_context, $debug_level, $object, $translate_string_method)
$string = gdt_string($string, $lang, $replaced_substrings, $translation_context, $object, $translate_string_method)

The $string is a string to be translated. With gdt the function returns a Texinfo tree, as the string is interpreted as Texinfo code after translation. With gdt_string a string is returned.

$lang is the language used for the translation.

$replaced_substrings is an optional hash reference specifying some substitution to be done after the translation. The key of the $replaced_substrings hash reference identifies what is to be substituted. In the string to be translated word in brace matching keys of $replaced_substrings are replaced. For gdt, the value is a Texinfo tree element that is substituted in the resulting Texinfo tree. For gdt_string, the value is a string that is replaced in the resulting string.

$debug_level is an optional debugging level supplied to gdt, similar to the DEBUG customization variable. If set, the debug level minus one is passed to the Texinfo string parser called in gdt.

The $translation_context is optional. If not undef this is a translation context string for $string. It is the first argument of pgettext in the C API of Gettext.

For example, in the following call, the string See {reference} in @cite{{book}} is translated, then parsed as a Texinfo string, with {reference} substituted by $tree_reference in the resulting tree, and {book} replaced by the associated Texinfo tree text element:

  $tree = gdt('See {reference} in @cite{{book}}', "ca",
              {'reference' => $tree_reference,
               'book'  => {'text' => $book_name}});

By default, gdt and gdt_string call translate_string to use a gettext-like infrastructure to retrieve the translated strings, using the texinfo_document domain. You can change the method used to retrieve the translated strings by providing a $translate_string_method argument. If not undef it should be a reference on a function that is called instead of translate_string. The $object is passed as first argument of the $translate_string_method, the other arguments are the same as translate_string arguments.

$tree = pgdt($translation_context, $string, $lang, $replaced_substrings, $debug_level)

Same to gdt except that the $translation_context is not optional. Calls gdt. This function is useful to mark strings with a translation context for translation. This function is similar to pgettext in the Gettext C API.

By default, in gdt, gdt_string and pgdt a string is translated with translate_string.

$translated_string = translate_string($string, $lang, $translation_context)

The $string is a string to be translated. $lang is the language used for the translation. The $translation_context is optional. If not undef this is a translation context string for $string. It is the first argument of pgettext in the C API of Gettext.

translate_string uses a gettext-like infrastructure to retrieve the translated strings, using the texinfo_document domain.


8.6 Texinfo::Translations SEE ALSO

GNU gettext utilities manual.


8.7 Texinfo::Translations AUTHOR

Patrice Dumas, <pertusus@free.fr>