doc/tta_api/api_includes/Texinfo-Translations.texi

@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);

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


  my $lang_translations;

  my $language = $customization->get_conf('documentlanguage');

  if (defined($language)) {
    $lang_translations
     = Texinfo::Translations::set_translations_documentlanguage(
         $Texinfo::Translations::converters_translation_cache,
         $language, undef);
  }


  my $tree_translated
    = Texinfo::Translations::gdt('See {reference} in @cite{{book}}',
                           $lang_translations,
                          {'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 is not described here, 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{setup_output_strings} method sets the translation files base directory.
If not called, system defaults are used.

@table @asis
@item setup_output_strings($localesdir, $strings_textdomain)
@anchor{Texinfo@asis{::}Translations setup_output_strings($localesdir@comma{} $strings_textdomain)}

@emph{$localesdir} is the directory where translation files are found. The
directory structure and files format should follow the @url{https://www.gnu.org/software/gettext/manual/html_node/Locating-Catalogs.html, conventions expected
for gettext based
internationalization}.
The @emph{$strings_textdomain} is optional, if set, it determines the translation
domain.

@end table

@table @asis
@item $lang_translations = new_element_language_translation(\%translations_cache, $element)
@anchor{Texinfo@asis{::}Translations $lang_translations = new_element_language_translation(\%translations_cache@comma{} $element)}
@cindex @code{new_element_language_translation}

Return a @emph{$lang_translations} based on the language information associated
to the @emph{$element} Texinfo tree element, or @code{undef} if the language is
not found.  Language information is only set for tree elements that have
associated information in English and need to be translated into all output
formats, for example for definition commands alias names such as @emph{Instance
Variable} for @code{@@defivar}.

@emph{$lang_translations} contains information on the language and already
translated strings.  @emph{\%translations_cache} hash is used to cache the lang
translations (including for an unknown language).  In general,
@code{$Texinfo::Translations::converters_translation_cache} is used for the
@emph{\%translations_cache} argument in order to reuse the translations and languages
information in all the converters.

@end table

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

@table @asis
@item $tree = gdt($string, $lang_translations, $replaced_substrings, $translation_context, $debug_level, $object, $translate_string_method)
@anchor{Texinfo@asis{::}Translations $tree = gdt($string@comma{} $lang_translations@comma{} $replaced_substrings@comma{} $translation_context@comma{} $debug_level@comma{} $object@comma{} $translate_string_method)}

@item $string = gdt_string($string, $lang_translations, $replaced_substrings, $translation_context, $object, $translate_string_method)
@anchor{Texinfo@asis{::}Translations $string = gdt_string($string@comma{} $lang_translations@comma{} $replaced_substrings@comma{} $translation_context@comma{} $object@comma{} $translate_string_method)}

@cindex @code{gdt}
@cindex @code{gdt_string}


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

The @emph{$lang_translations} should be a reference with information on the
language and already translated strings and can be @code{undef} if there is no
information on the language @emph{TODO reference set_translations_* when documented}.

@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.
In the string to be translated word in brace matching keys of
@emph{$replaced_substrings} are replaced.
For @code{gdt}, the value is a Texinfo tree element that is substituted in the
resulting Texinfo tree. For @code{gdt_string}, the value is a string that
is replaced in the resulting string.

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

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.

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

By default, @code{gdt} and @code{gdt_string} call @code{cache_translate_string} to use a
gettext-like infrastructure to retrieve the translated strings, using the
@emph{texinfo_document} domain.  You can change the method used to retrieve the
translated strings by providing a @emph{$translate_string_method} argument.  If not
undef it should be a reference on a function that is called instead of
@code{cache_translate_string}.  The @emph{$object} is passed as first argument of the
@emph{$translate_string_method}, the other arguments are the same as
@ref{Texinfo@asis{::}Translations $translated_string_tree = cache_translate_string($string@comma{} $lang_translations@comma{} $translation_context),, @code{cache_translate_string}}
arguments.

@item $tree = pgdt($translation_context, $string, $lang_translations, $replaced_substrings, $debug_level, $object, $translate_string_method)
@anchor{Texinfo@asis{::}Translations $tree = pgdt($translation_context@comma{} $string@comma{} $lang_translations@comma{} $replaced_substrings@comma{} $debug_level@comma{} $object@comma{} $translate_string_method)}
@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.

@end table

By default, in @code{gdt}, @code{gdt_string} and @code{pgdt} a string is translated with
@code{cache_translate_string}.  @code{cache_translate_string} is not meant to be called
directly but a replacement can be passed to the translation functions.  The
description of @code{cache_translate_string} is therefore useful to understand the
interface a user-defined function should use.  It could also be possibly
relevant to call @code{cache_translate_string} in a redefined function as a
fallback.

@table @asis
@item $translated_string_tree = cache_translate_string($string, $lang_translations, $translation_context)
@anchor{Texinfo@asis{::}Translations $translated_string_tree = cache_translate_string($string@comma{} $lang_translations@comma{} $translation_context)}
@cindex @code{cache_translate_string}

The @emph{$string} is a string to be translated.  The @emph{$lang_translations}
argument should be a reference with information on the
language and already translated strings.

In the current implementation @emph{$lang_translations} is an array reference.  The
first element of the array is an hash reference containing the
language information (main language, region, script and variants).
The second element is set to a string that can be used as @code{LANGUAGE}
environment before calling a function gathering translated strings.
The third element is set to an hash reference holding translations already
done.  A user-defined replacement function could use different data structures
for @emph{$lang_translations}.

If the language is not set, the input string does not
need to be translated.  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.

@code{cache_translate_string} returns an array reference with the translated string
as first element, or undef if the input string should be used as translation.
The second element of the reference array, if present, should be the Texinfo
tree corresponding to the translated string, without the braced arguments
substituted.

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

@end table

In converters based on @code{Texinfo::Convert::Converter}, an
@ref{Texinfo@asis{::}Convert@asis{::}Converter Translations in output documents,, higher level interface}
should be used for translations that avoids explicit use of
lang translations references

@node Texinfo@asis{::}Translations SEE ALSO
@section Texinfo::Translations SEE ALSO

@url{https://www.gnu.org/software/gettext/manual/, GNU gettext utilities manual}.
@ref{Texinfo@asis{::}Convert@asis{::}Converter Translations in output documents}.

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

Patrice Dumas, <bug-texinfo@@gnu.org>

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