[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: Fri, 27 Jul 2007 00:27:46 +0900

On 26 juil. 07, at 23:50, Jason Rumney wrote:

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

I think I understand. But you have to consider that as soon as we provide a localization framework we offer the possibility to have something else but English as the default.

That may not be the case for the core distribution for the next few versions to come, but there are no reasons not to consider the possibility that a Brazilian developer could write files documented in Brazilian Portuguese, which would later be localized to English, or anything else.

This is why I also proposed a language identifier for non localized files:

To simplify the writing, in the case a lot of functions and documentation needs to be written (which is always a good thing) we could have a doclang function that takes one argument, the language in which the documentation has been written so that a typical .el file could look like:

Template 2:

(doclang JA) ; optional as to keep backward compatibility with the current lack of framework

(defun function-name1 (arguments...)
        (interactive argument-passing-info)     ; optional

(defun function-name2 (arguments...)
        (interactive argument-passing-info)     ; optional

Once a file is localized, the el file should be language "agnostic" and I also proposed:

In case the locale matching string is not available (not translated), a mechanism to display a prefered language, then the default language should be implemented.

Because we should not assume that the preferred default should be English (it could be Russian for some Polish users, or Japanese for some Chinese users etc)

Keeping the translations in separate files makes it easier to update
them separately from the Emacs release cycle.

I don't think that is related. The ease of updating will only depend on the tools that will be made available with this framework. The difference will be whether the tools can parse a normal .el file or not.

I think departing from the current, how do you call that, "literate programming" style would dramatically reduce the efficiency of the current workflow: not only is the function documentation available interactively but it also is _within_ the code.

I think the "updating" process fear comes from the omnipresence of the "gettext" paradigm.

I don't think this paradigm is strong or flexible enough. Let me explain.

When a translation is made at a certain point in time, it is stored as a "translation memory" (TM) file.

When a documentation update takes place, the TM file automatically matches the non modified contents (directly in the .el file) and automatically proposes the modified contents since they are not in the TM. The translator can use similar source/target pairs as reference to translate the modified string.

The process of taking a diff, translating (without context) and patching the result _is_ what makes the process cumbersome.

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.

Yes, but then, I'd argue that each localization community (and they would be created right away) would be able to maintain a "localized fork" with the same code base as the stable emacs branch while releasing builds for their l10n community. Which _is_ the point in the end :) The localized builds can merge their localized files for each major emacs stable release.

The simplest the localization process will be, the fastest we will have localized _quality_ builds: what keeps professional translators from participating to free software localization is the complexity of the processes involved, _not_ their lack of will to participate.

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.


(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

Whatever is elegant and not too geeky will sure see localizers flocking to emacs :)

Jean-Christophe Helary

reply via email to

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