====================================================================
INSTRUCTIONS FOR TRANSLATING SCIPAD AND CONTRIBUTING SCIPAD LOCALES
====================================================================

In order to port Scipad to a new language, you need to create a 
"message file" containing the translation of the text strings used by Scipad,
and to put it in the directory SCI/tcl/scipadsources/msg_files/. Here are
detailed instructions about how. We estimate that the creation of such a 
file starting from an existing template shouldn't take more than 2-3 hours
of editing.

If you're considering to contribute to the localization of Scipad, we'd be
happy to receive your file; we can take care of including it in the current
Scilab development tree, so that it becomes publicly available.
Moreover, if you volunteer for maintaining, there will be occasional changes
and additions you'd be asked to incorporate from time to time. We expect 
that the latter will be very few, of the order of a few strings a month.


THE MESSAGE FILE CONTENT
------------------------

The message file has to be called XX.msg, where XX stands for the i18n code
of the language you're using (see e.g.
http://www.i18nguy.com/unicode/language-identifiers.html).

The file itself is written in Tcl. You're not expected to know Tcl at all,
just to respect the format adopted, easily understood from the 
existing files. Notably:

The file itself is composed of:

-a header with comments. Please feel free to include information like
 your name and the version of Scipad for which the file has been
 edited.

-a sequence of lines of the form 
  ::msgcat::mcset XX "A_STRING" "TRANSLATED_STRING"

-some interspersed comments (a # marks the rest of a line as a comment),
 dividing loosely the sequence in sections


The minimal syntax rules you have to keep in mind are:

-strings are enclosed within double quotes "" or curly brackets {}

-long lines can be continued by using a \ as last character of the line

-some characters, having special meanings in Tcl, like []{}, need to
 be escaped with a backslash (i.e. \[ ) (in some very particular cases
 with three backslashes \\\)

-\n in a string represents the newline character

-some strings use & with a special purpose -- see below.


EDITING THE MESSAGE FILE
------------------------

First of all, choose one of the existing files 
SCI/tcl/scipadsources/msg_files/*.msg as a template. The files fr.msg and
it.msg are the best candidates, as they are most frequently updated.
The file eng.msg is NOT a good starting point, because it contains only
very few strings [for most strings, the english text itself is used as 
identifier in the strings database, and doesn't need to be resolved further].
Such files are found in the trunk SVN version of scilab and in recent unstable 
versions; we recommend to start from the very latest files available on the 
scilab SVN repository (see 
http://viewvc.scilab.org/bin/cgi/viewvc.cgi/trunk/scilab/modules/scipad/tcl/msg_files/
and http://www.scilab.org/download/index_download.php?page=SVN.html)
If you have difficulties in getting them, let us know, we can forward 
by email.

Save this file under the new name XX.msg, where XX is the i18n code of the
language you're using. Change all the codes xx following ::msgcat::mcset 
into the XX you have chosen. This can be done easily by a Replace all 
operation in your favourite text editor.

In the *.msg file, "A_STRING" is usually a plain readable english text string,
only sometimes it is an abbreviation. The full english string can then 
be looked up in the file eng.msg. You're essentially asked to type in the
proper "TRANSLATED_STRING" for each case, replacing that of the original file.

Please respect the existing order in the file, as this will be very
convenient for maintaining it. For the moment, we are not equipped with
tools for cross checking the consistency of the different localization 
files, and everything has to be done at hand. Also, do not touch the
existing english version of "A_STRING": the localization procedure uses 
these exact strings as labels. If you think that the english original is
inadequate, please report it to us, an eventual change needs to be propagated
to the main code and to all of the message files. 

In most of the cases, the translation is one to one, in the sense that each
string will have its immediate translation. In a few more complex cases (e.g.
"The contents of" YYYYY "may have changed"), a sequence of strings is used to
build up a longer message, where some arguments are substituted at run time.
Such cases allow for some rearrangement, should the syntax of the local
language require a different word order. For instance, the former sequence
could be rendered as "" YYYY "contents may have changed", or as 
"It may be that contents changed for" YYYY "".
If you run into truly untranslatable messages, let us know.


ENCODING ISSUES
---------------

Localization files could require a particular encoding for displaying
correctly latin accented characters, or non-latin ones. We have seen that
ISO-8859-15 and UTF-8 work fine, and we had used consistently ISO-8559-15
for French and Italian. As a rule of thumb, everything should be fine for
Scipad if, opening it, it recognizes the encoding you used. Tcl seems to have
some ability of doing it by itself. Currently all msg files are now in UTF-8
in order to support the chinese characters displayed in the Options/locale
menu.
We also have some tools for transcoding, if needed, though our systems might
lack the proper fonts.


THE SPECIAL & CHARACTER
-----------------------

You'll remark that some strings contain a single & somewhere. This is used 
for menu entry labels and for a few dialog button labels. There, the 
character following the & will be underlined in Scipad, meaning that the
corresponding entry will be accessible also by pressing an appropriate 
keyboard sequence. In menues, this is an Alt-char-char-... sequence: for
example, in the english locale, Alt-f-n corresponds to File/New, Alt-f-o to
File/Open..., etc. In button labels, this is a Alt-char accelerator.
The choice of the underlined characters is completely free, and
the Alt-char sequence will work in the locale whichever underlined
character has been chosen.

The & can appear in the translated string in a position different than
in the original. In any event, you're asked to check that, in your 
translation, all the underlined characters in the same pulldown menu
or in a dialog box follow some logic. Within an individual menu, any 
underlined character should appear only once, and possibly be 
evocative enough. Uniqueness is mandatory (if not, only the entry
corresponding to the first occurrence of a multiply used character is
accessible via Alt-...), while it is (just) recommended to underline
whenever possible a meaningful word initial. This applies to menu 
names as well; please check that also them have unique underlined
characters.

For button labels in dialog boxes (e.g. the Find and Replace dialogs),
the Alt-char equivalent to the button press follows the exact same logic
as for menues. All what is explained above for menues do apply as well
for button labels, checkboxes, radiobuttons, etc.


CHECKING THE TRANSLATION
------------------------

After creating the *.msg file and dropping it in its place, you can 
check the result by opening Scipad and changing the locale in the Options
menu. The locale you just added should appear automatically in that menu. 
If you just changed an existing *.msg file, just reselecting Options/Locale
will do, without any need to restart Scipad. Unless you have introduced Tcl 
syntax errors with your editing, Scipad should display menues and dialogs 
in this new locale.

Should you have dropped a Tcl syntax error (the most common are to
forget a " or a \), Scipad should warn you with an error message 
detailed enough to find the offending line. If you have wish 
installed, it might be more explicative to run scipad.tcl in wish, e.g.

  unix("wish "+SCI+"/tcl/scipadsources/scipad.tcl")

from within scilab. It would be of course more convenient to us if 
you're able to solve these errors yourself, but we can provide some 
assistance otherwise.

Should you have omitted the translation of one string (or changed 
inadvertently the original, or deleted a line by mistake, etc.),
you'll see its english fallback by default.


THE msgdiff TOOL
----------------

The directory SCI/tcl/scipadsources/msg_files/ contains also a
Scilab script which can be used to check the cross-consistency of the 
existing message files. The script is called msgdiff.sci and is automatically
loaded in Scilab at startup [trunk scilab5 version -- in the BUILD_4 version 
it still has to be loaded with exec]. Files can be checked calling from Scilab

  msgdiff <firstfile.msg> <secondfile.msg>

or

  msgdiff <firstfile.msg>

In the first form, msgdiff compares the two files and reports the strings
defined in <firstfile.msg> but not in <secondfile.msg> and viceversa.
Moreover, it generates a new file called <secondfile.msg>.rev, which contains
all the strings present in <secondfile.msg>, nicely reformatted and reordered
following the same order of <firstfile.msg>, and placeholders containing "???"
for the strings not (yet) translated in <secondfile.msg>. 
In the second form, msgdiff only generates a <firstfile.msg>.rev in which
the entries are nicely reformatted (this implies losing any original 
indentation, for the moment). 
Some really minimal syntax check is done in both cases. Further comments are
written in the header of msgdiff.sci.


UPDATES
--------

Occasionally, as the code of Scipad is revised, we might decide to
change some existing message or to add new ones. Given that 
programming Scipad is a marginal activity for both of us, that 
shouldn't happen often anyway. If you volunteer for mantaining the 
translated file too, we'd include you in a (privately owned and kept, 
clearly) mailing list of translators, and notify you of requested 
changes. We'll be thankful in any case for your continuing effort.


COPYRIGHT ISSUES
----------------

Scilab Team requires that you agree to make your contribution freely
usable. This is their official statement:

  "After discussion with people from INRIA legal department, we think 
  that a very simple thing to do is to ask people to put their code in
  public domain or, if they do not want, to give it the LGPL licence. 
  To give it the LGPL license is very simple, see:

  http://www.gnu.org/copyleft/lesser.html#SEC4

  Note that I am talking about LGPL and NOT GPL."

===================================================================

We hope that these instructions are clear enough. If not, please do not
hesitate to ask us.

Enrico Segre <enrico.segre@weizmann.ac.il>
François Vogel <fvogelnew1@free.fr>

