[Top][All Lists]

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

A system for localizing documentation strings

From: Jean-Christophe Helary
Subject: A system for localizing documentation strings
Date: Thu, 26 Jul 2007 10:05:36 +0900

A function is written like this (per Robert Chassell's book, I'm currently only at chapter 3, sorry if all sounds a little too obvious):

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

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

docfun would provide the data (language+string) to the display devices (help functions etc) that would need to be able to get the proper string based on the environment locale (or whatever locale data is available). 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.

In the end, the template for a defun would be:

Template 1:

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

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

Now, to offer a real framework for translating, since we _don't want to use intermediate formats (like PO etc), although those could be available for gettext fans, we'd need another function that takes a number of arguments and that could look like:

(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
The target-language declares to which language the translator is working
the reference-function-name declares which functions should be taken as reference for the current translation. the reference-file declares which files should be taken as reference (ideally, PO compendia, TMX files, CSV files etc)

transfun would be a whole different business since it would actually provide a real dynamic fuzzy matching engine between the source- language strings and the source reference strings. _NOT_ something like the "fuzzy" thing gettext provides.

In the case of Template 1 (a function that has already been translated to a number of languages), transfun would just add a line to the documentation function.

In the case of Template 2 (a function that exists in only one language), transfun would also transform Template 2 into Template 1 to add the documentation at the proper location. If the doclang function is not documented, transfun asks what argument should doclang have and proceeds.

Now, it would of course be possible to have translation tools support the defun template so that they output the target strings to the correct position.

Of course, I am only talking about functions here (remember: chapter 3 of Chassell's book) but I am gessing that most of this "framework" could be extended to support _all_ the translatable strings emacs displays.

As for the quality of the translation (and it seems it is mostly people who have never done translation work before who complain the most) I suggest you leave that to the localization groups that are used to the processes.

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.

Jean-Christophe Helary

reply via email to

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