Re: A system for localizing documentation strings

[Jason Rumney <jasonr@gnu.org>]

Jean-Christophe Helary wrote:
> 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. That would impair understanding of the code
> too. Besides for the fact that it would be a major departure from the
> current code workflow.

It need not be a major departure. The "keys" can be the function and
variable names (where both exist with the same name, we'd need some way
to differentiate). The "default" docstring (English) could remain with
the function or variable definition, so nothing need change in the lisp
files.

Keeping the translations in separate files makes it easier to update
them separately from the Emacs release cycle. Eventually we will reach a
point where the translations don't change separately from Emacs, but for
at least a few Emacs releases there will be new translations and
corrections to translations appearing much quicker than the Emacs
release cycle, and it would be useful if users could take advantage of them.

If the translated doc string format is a lisp form, then we have a lot
of flexibility in how we arrange the files.  Small lisp extensions
distributed separately from Emacs would have the option to include their
translations in the same file as the code, and larger packages would
have the option of having a file per language.

Eg:

(define-docstring-translation '(:function example-function) 'ja "語例")



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")

where example-feature corresponds to the provide statement in the file,
and translations for Japanese, Spanish and French are in
"example-translations.el"