Re: Fwd: A system for localizing documentation strings

[Eli Zaretskii]

> From: Jean-Christophe Helary <address@hidden>
> Date: Thu, 26 Jul 2007 12:29:19 +0900
> 
> I was told by Eli Zaretskii that such discussions should better take  
> place here, hence my forward from address@hidden

Thanks.

> To offer a practical possibility for interactive localization we'd  
> need a function that dynamically generates output instead of the  
> "optional-documentation..." string. This function would take a number  
> of paired arguments:
> 
> (docfun
>       source-language-1 source-language-1-documentation-string
>       source-language-2 source-language-2-documentation-string
>       etc ...)
> 
> for ex:
> 
> (docfun
>       EN "optional-documentation in EN..."
>       FR "documentation optionnelle en FR...")

I don't like this implementation idea, because it would require the
user to byte-compile Lisp files whenever a translation to another
language is added.  This would be very inconvenient, especially for
*.el files that are preloaded when Emacs is built, because that would
mean one must have the sources available nearby, and must run the
build procedure and "make install".  The latter step requires sysadmin
privileges on many platforms, another inconvenience.

I think it's much better to have a separate translation file for each
.el file.  Such a translation file would be loaded on demand when
documentation for symbols defined on that file is requested by the
user.  The translation file needs include only the names of the
symbols and their doc strings for supported languages.  (We could also
have separate translation files for each language, but I think it
won't be necessary, as the number of symbols on a single .el file is
quite small.)

> (transfun function-name
>       source-language
>       target-language
>       reference-function-name ; should be a list
>       reference-file ; should be a list)
> 
> The function-name declares which function has to be translated
> The source-language declares from which language string the source  
> should be displayed

Why do we need the source language?

> What we need is provide 1) a way for coders to identify the necessary  
> strings for the translation 2) a way for translators to add  
> translated strings "the emacs way" 3) a modification of the display  
> procedures to take the new strings into account.

Your number 3) is not described correctly: it's not the display that
needs to be modified, it's the Emacs documentation commands.  The
documentation commands don't display anything, they just insert the
doc text into a buffer, whether *Help* or minibuffer or something
else.  The Emacs redisplay engine then displays that buffer; however,
if the text in the buffer to be displayed is already in French (say),
that is what you will see after it is displayed.

So what is needed is to modify the documentation commands so that they
will look up the translated text and display that text instead of the
original English doc string.

Also, we should keep in mind that Lisp primitives (those implemented in
C) have their doc strings as C comments, not as C strings.  The
infrastructure developed for Emacs l10n should provide solution for
the primitives as well, and the solution will have to be different
both from your suggestion above and from the traditional gettext-style
message catalog.