Texinfo::Translations
*********************

Texinfo::Translations NAME
==========================

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

Texinfo::Translations SYNOPSIS
==============================

  @ISA = qw(Texinfo::Translations);

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

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.

Texinfo::Translations DESCRIPTION
=================================

The 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 Texinfo::Common __ and __p.

Texinfo::Translations METHODS
=============================

No method is exported.

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

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

$tree = $object->gdt($string, $replaced_substrings, $translation_context, $mode, $lang)

     The $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.  $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, 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 $replaced_substrings are replaced.

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

     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.  $lang is optional. If set, it overrides the documentlanguage.

     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 = $converter->gdt('See {reference} in @cite{{book}}',
                            {'reference' => $tree_reference,
                             'book'  => {'text' => $book_name}});

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

     $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.

$tree = $object->pgdt($translation_context, $string, $replaced_substrings, $mode, $lang)

     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.

$tree = $object->replace_convert_substrings($translated_string, $replaced_substrings, $mode)

     $translated_string is a string already translated.  $replaced_substrings is an optional hash reference specifying some substitution to be done. $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.  $object is typically a converter, but can be any object that implements get_conf, or undefined (undef).  If not undefined, the information in the $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 gdt after the retrieval of the translated string.

Texinfo::Translations AUTHOR
============================

Patrice Dumas, <pertusus@free.fr>

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.