Texinfo::Translations - Translations of output documents strings for Texinfo modules
@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}});
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.
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
.
No method is exported.
The configure
method sets the translation files base directory. If not
called, system defaults are used.
$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.
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.
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
.
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.
Copyright 2010- Free Software Foundation, Inc. See the source file for all copyright years.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.