[Mma] Re: documentation: are the .txi files the ones to edit?

[Paul Kienzle]

David Bateman wrote:

>Daprès John W. Eaton <jwe at bevo.che.wisc.edu> (le 27/05/2003):
>  
>
>doesn't gettext translate word by word... Thus for the error/warning messages
>we can tune the messages (as they are short) so that reasonable translations
>are possible. But the help messages are long, can include embedded equations,
>etc and so will be difficult to get good automatic translations. So I don't
>think I'd trust gettext for this part of the task...
>
gettext works on strings.  Instead of "string" in your code
you must use _("string").  The _() function looks up the
string in a hash table for the particular language, and if it
finds it, then it substitutes it.  This can include formatting
codes such as "%s" as well.  With reasonably generic
strings, which means no tricks like:
    printf("There were %d element%s",n,n!=1?"s":"")
since many languages do not do plurals by suffixing, the
results can be okay.  Usually the translator can make something
meaningful out of the order of the formatted parameters.

C++ formatted output doesn't use format statements, so
the result is much more choppy strings which are harder to
translate.

>I think the preferred solution would be to translate the help messages by
>hand as well. The question then becomes where to store these translations
>and how to access them at runtime.
>
One per file for the convenience.  I would suggest encoding
the language in the filename so that you can write aider(disp) as
something like
  function aider(fn)
     f = file_in_loadpath([fn,".fr"]);
     if !isempty(f), format(f); else help(fn) endif
  endfunction

>>I think it would better to translate the .txi files separately from
>>the doc strings, and have them merged together to create a complete
>>translation, same as is currently done for the English version.  Then
>>with a little bit of support in the Octave sources, you could get
>>translated doc strings from the help command as well as a translated
>>manual.
>>    
>>
>
>I too think it would be better. But the original author stated clearly 
>that he didn't have the skills for this task. So in the absence of 
>someone wanting to do it the "right way", his only choice is to translate
>the manual wholesale....
>
If the fn.lang files are formatted appropriately, then
existing tools can be used to build up DOCSTRINGS
and plug DOCSTRINGS into the translated manual.
No coding necessary.

>>I would want the English help text to remain in the source files.
>>Translations would go in separate files.
>>    
>>
>
>Why make a special cae for English? Special cases, only make the job
>harder. I feel that all languages should be treated in the same way 
>just for this reason.
>
You want a default string in case no translation is available.
In the absence of a universal language, we use English.  I
suppose we could rewrite help to search first for [fn ".en"]
then the default could be in any language.  It might not work
for _() though.

>For the oct-file and inbuilt functions, its not clear to me whether
>the help should be in the source or separately.
>
Separately.  The same technique that works for m-files will work
for oct-files.  The translator will need a tool to determine which
docstrings have changed, preferably with diffs to make their
job easier, otherwise docs will soon be out of sync.  The docs
themselves should indicate whether they are up-to-date so that
the user can use "help" rather than "aider" to get the default version.

>...
>
>The language to use could then be controlled by a variable
>OCTAVE_LANG. 
>
which comes from the environment variable LANG

Paul Kienzle
pkienzle at users.sf.net