turtlestitch/translating Snap.txt

*****************************
Translating BYOB4 / Snap!
by Jens Moenig
last changed: 12/10/16
*****************************

At this stage of development, Snap! can be translated to any LTR language
maintaining the current order of inputs (formal parameters in blocks).

Translating Snap! is easy:


1. Download

Download the sources and extract them into a local folder on your
computer:

    <http://snap.berkeley.edu/snapsource/snap.zip>

Use the German translation file (named 'lang-de.js') as template for your
own translations. Start with editing the original file, because that way
you will be able to immediately check the results in your browsers while
you're working on your translation (keep the local copy of snap.html open
in your web browser, and refresh it as you progress with your
translation).


2. Edit

Edit the translation file with a regular text editor, or with your
favorite JavaScript editor.

In the first non-commented line (the one right below this
note) replace "de" with the two-letter ISO 639-1 code for your language,
e.g.

    fr - French => SnapTranslator.dict.fr = {
    it - Italian => SnapTranslator.dict.it = {
    pl - Polish => SnapTranslator.dict.pl = {
    pt - Portuguese => SnapTranslator.dict.pt = {
    es - Spanish => SnapTranslator.dict.es = {
    el - Greek => => SnapTranslator.dict.el = {

etc. (see <http://en.wikipedia.org/wiki/ISO_639-1>)


3. Translate

Then work through the dictionary, replacing the German strings against
your translations. The dictionary is a straight-forward JavaScript ad-hoc
object, for review purposes it should be formatted as follows:

    {
        'English string':
            'Translation string',
        'last key':
    }       'last value'

and you only edit the indented value strings. Note that each key-value
pair needs to be delimited by a comma, but that there shouldn't be a comma
after the last pair (again, just overwrite the template file and you'll be
fine).

If something doesn't work, or if you're unsure about the formalities you
should check your file with

    <http://JSLint.com>

This will inform you about any missed commas etc.


4. Accented characters

Depending on which text editor and which file encoding you use you can
directly enter special characters (e.g. Umlaut, accented characters) on
your keyboard. However, I've noticed that some browsers may not display
special characters correctly, even if other browsers do. So it's best to
check your results in several browsers. If you want to be on the safe
side, it's even better to escape these characters using Unicode.

    see: <http://0xcc.net/jsescape/>


5. Block specs:

At this time your translation of block specs will only work
correctly, if the order of formal parameters and their types
are unchanged. Placeholders for inputs (formal parameters) are
indicated by a preceding % prefix and followed by a type
abbreviation.

For example:

    'say %s for %n secs'

can currently not be changed into

    'say %n secs long %s'

and still work as intended.

Similarly

    'point towards %dst'

cannot be changed into

    'point towards %cst'

without breaking its functionality.


6. Submit

When you're done, rename the edited file by replacing the "de" part of the
filename with the two-letter ISO 639-1 code for your language, e.g.

    fr - French => lang-fr.js
    it - Italian => lang-it.js
    pl - Polish => lang-pl.js
    pt - Portuguese => lang-pt.js
    es - Spanish => lang-es.js
    el - Greek => => lang-el.js

and send it to me for inclusion in the official Snap! distribution.
Once your translation has been included, Your name will the shown in the
"Translators" tab in the "About Snap!" dialog box, and you will be able to
directly launch a translated version of Snap! in your browser by appending

    lang:xx

to the URL, xx representing your translations two-letter code.


7. Known issues

In some browsers accents or ornaments located in typographic ascenders
above the cap height are currently (partially) cut-off.



Enjoy!
-Jens