[no subject]

[Patrice Dumas]

branch: master
commit af2fe5d2b4da29aae980becba87faf9c507f1d19
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sat Oct 29 23:52:41 2022 +0200

    Add customization of translated strings
    
    * doc/texi2any_api.texi (Internationalization of Strings Function)
    (Basic Formatting Customization), tp/Texinfo/Convert/HTML.pm (gdt):
    override Texinfo::Translations gdt to call format_translate_string
    user-defined formatting reference if the formatting reference is
    defined.
    Document more arguments of gdt, as they are also used for
    format_translate_string.
---
 ChangeLog                  | 12 ++++++++
 doc/texi2any_api.texi      | 70 +++++++++++++++++++++++++++++++---------------
 tp/Texinfo/Convert/HTML.pm | 25 ++++++++++++++++-
 3 files changed, 83 insertions(+), 24 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 59edc91dbc..28d60799fc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2022-10-29  Patrice Dumas  <pertusus@free.fr>
+
+       Add customization of translated strings
+
+       * doc/texi2any_api.texi (Internationalization of Strings Function)
+       (Basic Formatting Customization), tp/Texinfo/Convert/HTML.pm (gdt):
+       override Texinfo::Translations gdt to call format_translate_string
+       user-defined formatting reference if the formatting reference is
+       defined.
+       Document more arguments of gdt, as they are also used for
+       format_translate_string.
+
 2022-10-29  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/Convert/HTML.pm (direction_string, _translate_names):
diff --git a/doc/texi2any_api.texi b/doc/texi2any_api.texi
index 4d68e4dd27..ba185f1559 100644
--- a/doc/texi2any_api.texi
+++ b/doc/texi2any_api.texi
@@ -52,8 +52,7 @@ All of this information, with the exception of command-line 
options
 and search directories associated with command line options
 (@pxref{Loading Init Files}), may become
 obsolete in a future Texinfo release.  Right now, the ``API''
-described in this chapter is immature, and incomplete (translations
-strings customization API, in particular, is lacking),
+described in this chapter is immature,
 so we must keep open the possibility of incompatible, possibly major,
 changes.  Of course we try to avoid incompatible changes, but it is
 not a promise.
@@ -511,11 +510,8 @@ texinfo_register_no_arg_command_formatting('error', undef, 
undef, undef,
                                            'error--&gt;');
 @end example
 
-@quotation Warning
-There is no possibility to provide custom translations for selected
-strings, such that the translated string case cannot actually be used
-in practice.
-@end quotation
+@xref{@code{format_translate_string}} for
+customization of translated strings.
 
 
 @node Simple Customization for Simple Commands with Braces
@@ -1036,7 +1032,7 @@ The direction strings can be customized with
 
 @defun texinfo_register_direction_string_info ($direction, @
                   $type, $converted_string, $string_to_convert)
-@var{$direction} is a direction (@pxref{Directions}), @var{type}
+@var{$direction} is a direction (@pxref{Directions}), @var{$type}
 is the type of string (@pxref{Direction Strings}).  Both
 @var{$converted_string} and @var{$string_to_convert} are optional,
 if both are unset or @code{undef}, the direction string is unset.
@@ -1310,26 +1306,28 @@ a Texinfo tree conversion.
 @node Internationalization of Strings Function
 @subsection Internationalization of Strings Function
 
-@quotation Warning
-There is no possibility to provide custom translations for selected
-strings, such that only translated strings already recorded in
-the default code can be used in practice.
-@end quotation
-
 @vindex texinfo_document @r{Gettext domain}
-The subroutines @code{gdt} or @code{pgdt}, from the
-@code{Texinfo::Translations} module is used for translated strings:
+The subroutines @code{gdt} or @code{pgdt}, are used for translated strings:
 
-@deftypefun {@var{$translated_tree} =} @var{$converter}->gdt (@var{$string}, 
@var{\%variables_hash}, @var{$message_context})
-@deftypefunx {@var{$translated_tree} =} @var{$converter}->pgdt 
(@var{$message_context}, @var{$string}, @var{\%variables_hash})
+@deftypefun {@var{$translated_tree} =} @var{$converter}->gdt (@var{$string}, 
@var{\%variables_hash}, @var{$translation_context}, @var{$mode})
+@deftypefunx {@var{$translated_tree} =} @var{$converter}->pgdt 
(@var{$translation_context}, @var{$string}, @var{\%variables_hash}, @var{$mode})
 @var{$string} is the string to be translated, @var{\%variables_hash}
 is a hash reference holding the variable parts of the translated
-string.   @var{$message_context} is an optional translation context
+string.   @var{$translation_context} is an optional translation context
 that limits the search of the translated string to that context
 (@pxref{Contexts,,,gettext,GNU gettext tools}).
-The result returned is a perl Texinfo tree.
+The result returned is a perl Texinfo tree in the default case.
 
-If called as @code{pgdt}, @var{$message_context} is not optional
+@var{$mode} is an optional string which may modify how the function behaves. 
The
+possible values are:
+@table @code
+@item 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
+
+If called as @code{pgdt}, @var{$translation_context} is not optional
 and is the first argument.  @code{pgdt} is used to mark
 that the translated string has a context for tools extracting
 translatable strings to produce template files, which is not the case for
@@ -1374,10 +1372,13 @@ $converter->convert_tree($converter->gdt(
                          "convert explained $cmdname");
 @end example
 
+In the default case, the @code{gdt} function from the 
@code{Texinfo::Translations}
+module is used for translated strings.  It is possible to use a user-user 
defined
+function instead (@pxref{@code{format_translate_string}}).
 @xref{Texinfo::Translations,,,texi2any_internals} for more
 on @code{Texinfo::Translations}.
-@xref{Internationalization of Document Strings,,, texinfo, Texinfo} for an
-overview.
+@xref{Internationalization of Document Strings,,, texinfo, Texinfo} for 
additional
+information on the default case.
 
 
 @node Error Reporting in User Defined Functions
@@ -2765,6 +2766,29 @@ add an identifier attribute to.
 
 Return an anchor with identifier @var{$id}.
 @end deftypefn
+
+@item format_translate_string
+@anchor{@code{format_translate_string}}
+This function reference is not set in the default case, in the default case
+the @code{gdt} method from the @code{Texinfo::Translations} module is
+called (@pxref{Internationalization of Strings Function}).
+
+@deftypefn {Function Reference} @var{$translated_tree} format_translate_string 
@
+  (@var{$converter}, @var{$string}, @var{$lang}, @var{\%variables_hash}, @
+  @var{$translation_context}, @var{$mode})
+@var{$string} is the string to be translated, @var{lang} is the current 
document
+language.  @var{$translation_context} is an optional translation context.
+@var{$mode} is an optional string which should modify how the function behaves.
+
+The result returned should be a perl Texinfo tree in the default case, or
+a string if @var{$mode} is set to @code{translated_text}.
+The result returned may also be @samp{undef}, in which case the translation
+is done as if the function reference had not been defined.
+
+@xref{Internationalization of Strings Function} for more information on the
+arguments that are common with @code{gdt}.
+@end deftypefn
+
 @end table
 
 
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 6cc621cd4e..c4ab4a374f 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -2076,6 +2076,28 @@ sub _translate_names($)
 }
 
 
+# redefined functions
+#
+# Texinfo::Translations redefined to call user defined function.
+sub gdt($$;$$$$)
+{
+  my ($self, $message, $replaced_substrings, $message_context, $type, $lang) = 
@_;
+  if (defined($self->{'formatting_function'}->{'format_translate_string'})) {
+    my $format_lang = $lang;
+    $format_lang = $self->get_conf('documentlanguage')
+                           if ($self and !defined($format_lang));
+    my $translated_string
+      = &{$self->{'formatting_function'}->{'format_translate_string'}}($self,
+                                 $message, $format_lang, $replaced_substrings,
+                                 $message_context, $type);
+    if (defined($translated_string)) {
+      return $translated_string;
+    }
+  }
+  return $self->SUPER::gdt($message, $replaced_substrings, $message_context, 
$type, $lang);
+}
+
+
 sub converter_defaults($$)
 {
   my $self = shift;
@@ -6633,6 +6655,7 @@ foreach my $customized_reference ('label_target_name', 
'node_file_name',
      'format_separate_anchor' => \&_default_format_separate_anchor,
      'format_titlepage' => \&_default_format_titlepage,
      'format_title_titlepage' => \&_default_format_title_titlepage,
+     'format_translate_string' => undef,
 );
 
 # not up for customization
@@ -7307,7 +7330,7 @@ sub converter_initialize($)
   # are in default_formatting_references
   foreach my $customized_formatting_reference
        (sort(keys(%{$customized_formatting_references}))) {
-    if (!$default_formatting_references{$customized_formatting_reference}) {
+    if 
(!exists($default_formatting_references{$customized_formatting_reference})) {
       $self->document_warn($self, sprintf(__("Unknown formatting function: 
%s"),
                                           $customized_formatting_reference));
     }