Re: A system for localizing documentation strings

[Jean-Christophe Helary]

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
>         source-language
>         target-language
>         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