Re: A system for localizing documentation strings

[Eli Zaretskii]

> From: Jean-Christophe Helary <address@hidden>
> Date: Thu, 26 Jul 2007 22:51:54 +0900
> 
> I see 2 types of .el files.
> 
> 1) Those that come with the emacs distribution.
> 
> 2) Those that can be installed in user space.
> 
> The distribution would come with the translated .el files and the  
> updates to the translation could be included in updates of the  
> distribution without requiring the user to build the distribution  
> when new translations come. Since the translations are in the code  
> there is little management necessary (unlike systems where the  
> localizations come in separate files).
> 
> For the .el files in user space, the author would maintain the file's  
> translation and users would be able to compile the file without any  
> specific problem.

It's not that simple, because in practice many .el files that come
with Emacs are maintained by people who also offer the last version
from some Web site.  So in practice, I think we do need to have the
translations on separate files even for bundled packages.  And since
you agree that this should be supported anyway, for the benefit of
unbundled packages, there's no reason not to use this infrastructure
for bundled ones as well.  There are only advantages to this, I don't
see any disadvantages.

> > 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.
> 
> I don't think it is a good idea because it would put a bigger load on  
> the coder who would then have to write keys in the code and then  
> values in a separate file.

No, the idea is that Emacs will automatically recognize the strings
for which it needs to look for translations.  The programmers will
need not do anything beyond what they do today: provide a single doc
string.

> > Why do we need the source language?
> 
> Because as soon as we have a system that allows for localization we  
> can expect to have "native" code written and so we'll have to  
> reference the source language that _will_ be different from English.  
> We don't want people who don't master English to produce weird  
> English in their descriptions because the system implies  
> source=English.

I don't see a problem.  Programmers who don't master English can
supply the documentation in their native language, and someone else
will provide the English equivalent to be installed in the .el file
before it is installed; after, all most maintainers who have write
access to the repository have good command of English.  The original
(non-English) documentation gets installed as one of the translated
messages.

> That would require the faulty English string to be  
> rewritten before proceeding to translation.

We do it already anyway: grep the ChangeLog files for the string "doc
fix", and you will see how many fixes like that are installed.

> Also, we can expect to find translators who would be more familiar  
> with one source language than the other. If there is a Japanese  
> equivalent to an English description. I'd rather use the Japanese as  
> source and the English as reference to translate to French for exemple.

You will be able to do that, by looking at the Japanese translation.

> > 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.
> 
> Could that part be concieved separatly ?

It will be a separate solution, but it needs to be designed and
implemented together with the one for *.el files, since it doesn't
make sense to have a localized Emacs where all the primitives are
still documented only in English.