More .msg files can be added to this directory for the support of additional
languages. Please contact the current mantainers if you wish to contribute
a new file. Here are generic instructions about the format used in these
localization files.
 
Enrico Segre and François Vogel

====================================================
INSTRUCTIONS FOR CONTRIBUTING SCIPAD LOCALES
====================================================

If you're considering to contribute to the localization of Scipad, here
is some background information. What we need you to do is to create a 
"message file" file XX.msg in the directory SCI/tcl/scipadsources/msg_files,
containing the translation of the text strings used by Scipad, and to submit
it to us. We'll take care of including it in the current Scilab developement 
tree, so that it becomes publicly available.

In the file name, XX stands for the i18n code of the language you're
contributing (see e.g. 
http://www.i18nguy.com/unicode/language-identifiers.html).
We estimate that the creation of such a file starting from an existing
template shouldn't take more than 2-3 hours of editing. Moreover, if you
volunteer for maintaining the file, 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 itself is written in Tcl. You're not expected to know
Tcl at all, just to respect a few conventions adopted. Among these:

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

-a # marks the rest of a line as a comment

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

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, dividing loosely the sequence in sections


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

First of all, choose one of the existing files 
SCI/tcl/scipadsources/msg_files/*.msg as a template. Such files are found 
in the CVS version of scilab and in recent unstable versions; we reccommend
starting from the very latest file available on CVS; if you have difficulties
in getting it (see 
http://scilabsoft.inria.fr/download/index_download.php?page=CVS.html)
let us know, we can forward it 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 mantaining 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 transation. 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 have used consistenltly 
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. 
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 in the
string. This is used for menu entry labels and 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 
a 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 Ctrl-char accelerator. For menues,
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. This is unfortunately not yet true for
button labels.

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 Ctrl-char equivalent to the button press is, as of now, fixed
for every locale. This means that you'll have to strive to translate
the label in a way that the required character appears, and to prepend
this character with &. If you can't find any senseful translation
which contains the required character, either just omit the &, or 
include in the label a reminder like "[Ctrl-&x]". Labels tend to
loose their readability if you add too much text; up to you to judge
what is best. Note that for technical reasons the brackets in such a
label have to be escaped by three backslashes, i.e. "\\\[Ctrl-&x\\\]".


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

After creating the *.msg file and dropping it in its place, you can 
check the result by opening scilab and typing 

 global %scipad_language; %scipad_language="XX"; scipad

where XX is the prefix of the language you have used. Unless you have 
introduced Tcl syntax errors with your editing, Scipad should open in
the 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 this 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.

Please check also that whenever space is limited (for instance in 
dialogs), your translation is reasonably short and fits within the
given space contstraints.


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>

