@node Texinfo@asis{::}Translations
@chapter Texinfo::Translations

@node Texinfo@asis{::}Translations NAME
@section Texinfo::Translations NAME

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

@node Texinfo@asis{::}Translations SYNOPSIS
@section Texinfo::Translations SYNOPSIS

@verbatim
  @ISA = qw(Texinfo::Translations);

  my $tree_translated = $converter->gdt('See {reference} in @cite{{book}}',
                       {'reference' => $tree_reference,
                        'book'  => {'text' => $book_name}});
@end verbatim

@node Texinfo@asis{::}Translations NOTES
@section Texinfo::Translations NOTES

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

@node Texinfo@asis{::}Translations DESCRIPTION
@section Texinfo::Translations DESCRIPTION

The @code{Texinfo::Translations} module helps with translations
in output documents.

Translation of error messages uses another interface, which
is the classical gettext based perl interface.  It is not
described as it is described in details elsewhere, some
elements are in @ref{Texinfo@asis{::}Common $translated_string = __($msgid),, Texinfo::Common @code{__} and @code{__p}}.

@node Texinfo@asis{::}Translations METHODS
@section Texinfo::Translations METHODS

No method is exported.

The @code{gdt} and @code{pgdt} methods are used to translate strings to be output in
converted documents, and returns, in general, a Texinfo tree.

The @code{replace_convert_substrings} method is called by @code{gdt} to substitute
replaced substrings in a translated string and convert to a Texinfo tree.
It may be especially useful when overriding or reimplementing @code{gdt}.

@table @asis
@item $tree = $object->gdt($string, $replaced_substrings, $translation_context, $mode, $lang)
@anchor{Texinfo@asis{::}Translations $tree = $object->gdt($string@comma{} $replaced_substrings@comma{} $translation_context@comma{} $mode@comma{} $lang)}
@cindex @code{gdt}

The @emph{$string} is a string to be translated.  In the default case,
the function returns a Texinfo tree, as the string is interpreted
as Texinfo code after translation.  @emph{$replaced_substrings} is an
optional hash reference specifying some substitution to be done
after the translation.  The key of the @emph{$replaced_substrings} hash
reference identifies what is to be substituted, and the value is
some string, texinfo tree or array content that is substituted in
the resulting texinfo tree.  In the string to be translated word
in brace matching keys of @emph{$replaced_substrings} are replaced.

The @emph{$object} is typically a converter, but can be any object that implements
@code{get_conf}, or undefined (@code{undef}).  If not undefined, the information in the
@emph{$object} is used to determine the encoding, the documentlanguage and get some
customization information.

The @emph{$translation_context} is optional.  If not @code{undef} this is a translation
context string for @emph{$string}.  It is the first argument of @code{pgettext}
in the C API of Gettext.  @emph{$lang} is optional. If set, it overrides the
documentlanguage.

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

@verbatim
  $tree = $converter->gdt('See {reference} in @cite{{book}}',
                       {'reference' => $tree_reference,
                        'book'  => {'text' => $book_name}});
@end verbatim

@code{gdt} uses a gettext-like infrastructure to retrieve the
translated strings, using the @emph{texinfo_document} domain.

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

@table @asis
@item translated_text
@anchor{Texinfo@asis{::}Translations 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.

@end table

@item $tree = $object->pgdt($translation_context, $string, $replaced_substrings, $mode, $lang)
@anchor{Texinfo@asis{::}Translations $tree = $object->pgdt($translation_context@comma{} $string@comma{} $replaced_substrings@comma{} $mode@comma{} $lang)}
@cindex @code{pgdt}

Same to @code{gdt} except that the @emph{$translation_context} is not optional.
Calls @code{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.

@item $tree = $object->replace_convert_substrings($translated_string, $replaced_substrings, $mode)
@anchor{Texinfo@asis{::}Translations $tree = $object->replace_convert_substrings($translated_string@comma{} $replaced_substrings@comma{} $mode)}
@cindex @code{replace_convert_substrings}

@emph{$translated_string} is a string already translated.  @emph{$replaced_substrings}
is an optional hash reference specifying some substitution to be done.
@emph{$mode} is an optional string which may modify how the function behaves, and
in particular whether the translated string should be converted to a Texinfo
tree.  @emph{$object} is typically a converter, but can be any object that
implements @code{get_conf}, or undefined (@code{undef}).  If not undefined, the
information in the @emph{$object} is used to get some customization information.

The function performs the substitutions of substrings in the translated
string and converts to a Texinfo tree if needed.  It is called from @code{gdt}
after the retrieval of the translated string.

@end table

@node Texinfo@asis{::}Translations AUTHOR
@section Texinfo::Translations AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Translations COPYRIGHT AND LICENSE
@section Texinfo::Translations COPYRIGHT AND LICENSE

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.