[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: A system for localizing documentation strings

From: Jean-Christophe Helary
Subject: Re: A system for localizing documentation strings
Date: Thu, 26 Jul 2007 22:51:54 +0900

On 26 juil. 07, at 21:13, Eli Zaretskii wrote:

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


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:

        source-language-1 source-language-1-documentation-string
        source-language-2 source-language-2-documentation-string
        etc ...)

for ex:

        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 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.

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

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.

(transfun function-name
        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?

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. That would require the faulty English string to be rewritten before proceeding to translation.

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.

In the end, the translation needs to be recorded as a list of paired strings for future reference. This is usually called a "translation memory" and comes in different formats. A widely used one in the free world being PO compendia, another one, mostly used in the translation world is TMX (an XML dialect: Translation Memory eXchange). PO kind of expects English to be the source, but my understanding is that recent developments of gettext are making this a thing of the past. TMX is totaly "multilingual".

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.

Ok, sorry for my misunderstanding.

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.

That is correct. Except that we can't expect the English to be the original anymore. Hence the necessity to specify what language the strings are written in.

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 ?

I mean, we could start by having a modification in the documentation commands and then see what that gives with catalogs (either in the .el or separate, because in the end we could consider that the 2 solutions are valid depending on the scope of the .el file).

Jean-Christophe Helary

reply via email to

[Prev in Thread] Current Thread [Next in Thread]