[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 01:23:09 +0900

On 27 juil. 07, at 01:03, Jason Rumney wrote:

Jean-Christophe Helary wrote:
The fact that the code (.el) will only contain the English string
defeats one of the purposes of the localization.

If I read code and I need to check a separate file all the time to see
what the French says then I loose a huge amount of time.

Conversely, if I am reading the code for a short function, and cannot
see the documentation at the same time as the code because there are 15 translations in between causing the small function definition to take up
more than one screen, then I lose a huge amount of time.

If you are primarily interested in the documention, you will be using
describe-function anyway. If you are primarily interested in the code,
you don't want an excessive amount of inline documentation getting in
the way.

Very good, so why not propose a device that allows emacs to select a language based on the user's preferences for the code display too ?

If the system is properly designed, there are absolutely no reason not to be able to propose dynamic updating of the code itself based on linguistic preferences.

We need to make emacs easier to use not primarily for one language and secondarily for other languages, but for all languages in a smart emacs way.

I think (but I may be wrong) that you consider anything that is not
English as "translations" and English as a gold standard.

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.

I don't care about what is fair or unfair. I am talking about technology. Technology can't afford to have linguistic preferences. And you can't argue that "defun" is English. It is not.

Globally used software is localized. And there are no "default" English strings in the Spanish localization of Word... But that localized version serves also as a based for further documentation authoring that does _not_ use the original English.

It is important to _not_ think that way to be able to offer the most
flexible framework possible.

I think flexibility in this regard is important for translators, but not for end users. So rather than a primative system where translators look at the code, and write their translations from there, we should come up
with either a special mode to make it easy for translators to enter
translations while looking at the documentation strings in a particular
language (which need not be English), or a set of export and import
functions for interacting with existing tools for translation.

Flexibility is important for coders (who need the documentation to code) and for translators. Coders and translators have equivalent functions in the case at hand: they write documentation that the user will access. The system should put the coders and the translators on an equivalent level, hence the system should be language agnostic.
Users will indirectly benefit from that flexibility.

Translators don't have to look at the code. There can be a special mode that parses the code according to the translator's preference and handles the translated strings for final inclusion in the code.

I wrote earlier:

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

I see "transfun" (or whatever it would be called) as a real translation mode that provides translators with all the modern concepts existing in the localization/translation professional tools. Not a half-baked "read the code and type the translation" thing.

Jean-Christophe Helary

reply via email to

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