Re: Fwd: A system for localizing documentation strings

[Richard Stallman]

    (defun function-name (arguments...)
            (docfun
                    EN "optional-documentation in EN..."
                    FR "documentation optionnelle en FR...")
            (interactive argument-passing-info)     ; optional
            body...)

That format is not very good, because it won't let you add a language
without editing the source of the function.  It would be much better
to add doc translations separate from the function source code.

Contrast this case with advice: advising a function is confusing
because you can't see in the function's definition what it really
does.  It's totally different for doc strings: not being able to see
the translations of the doc string won't hide what the function's code
does.

Meanwhile, we know that various independent groups will want to create
doc translations for various languages, and we want to facilitate their
releasing these translations separately.

A construct such as

(defun-doc-translations FUNCTION LANG TEXT LANG TEXT...)

is the way to do it.  It should work to have multiple
defun-doc-translations forms for the same FUNCTION.  The last
one to define any given LANG should prevail.

(Of course, we want defvar-doc-translations and a few others,
plus perhaps one general one for misc. kinds of doc strings.)

However, to make this function smoothly at the level of the entire
Emacs, we need to make it possible to autoload these out of various
files.  It would be a pain to have to load ALL the Spanish
translations for ALL the files of Emacs (including the hundreds you
never use) just to get any of them.

    The other requirement would be for a lisp file to declare where its
    translations are, and for the user to be able to add more later:

    (provide-translations 'example-feature '(ja es fr) "example-translations")

That might be a good approach--especially if this form does not have
to be IN the source file it applies to.

To make this work, we need to go from a definition to the feature
provided by its source file.  That can be done thru the load-history
information, most of the time.  But not all source files provide a
feature.  We should have some other way to figure out the feature
that belongs to a certain file.

It would be good if the file of translations could have a string
analogous to an autoload cookie to give this information.  That way,
these files could be scanned very quickly so as to produce a list that
tells Emacs which file to load whenever it does want a translation.

    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.

No, this is not maintainable.  We can't afford to put all the
translations of the doc string of `last' into the defun for `last'.
There may someday be dozens of them.

And even if Emacs does have translations dozens of languages, people
will keep supporting more languages.  We do not want them to have to
edit the code source just to install their translations.

Therefore we do not want the translations in the function definition!

    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 aim to discourage that.  The primary language of GNU implementation
is English.  All functions should be documented in English, in addition
to whatever other languages are supported.

If someone's English doc string is not well written, that's as if the
code were not well written.  Someone will suggest an improvement.

Jason had it right:

    That is the way it must be for any globally used software. Perhaps as a
    Frenchman living in Japan you feel that is unfair, but the fact is that
    English is the most widely understood language there is.