A system for localizing documentation strings

A system for localizing documentation strings

[Jean-Christophe Helary]

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...)
	"optional-documentation..."
	(interactive argument-passing-info)     ; optional
	body...)

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:

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

for ex:

(docfun
	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...)
	(docfun
		EN "optional-documentation in EN..."
		FR "documentation optionnelle en FR...")
	(interactive argument-passing-info)     ; optional
  	body...)



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

(defun function-name2 (arguments...)
	"このファンクションのドキュメンテーションも日本語だ..."
	(interactive argument-passing-info)     ; optional
  	body...)


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

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

Re: A system for localizing documentation strings

[Eli Zaretskii]

> From: Jean-Christophe Helary <fusion@mx6.tiki.ne.jp>
> 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...)
> 	"optional-documentation..."
> 	(interactive argument-passing-info)     ; optional
> 	body...)
> 
> 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:
> 
> (docfun
> 	source-language-1 source-language-1-documentation-string
> 	source-language-2 source-language-2-documentation-string
> 	etc ...)
> 
> for ex:
> 
> (docfun
> 	EN "optional-documentation in EN..."
> 	FR "documentation optionnelle en FR...")

This kind of suggestions and the ensuing discussion should be on
emacs-devel mailing list, not here.