Creation

1 files changed, 143 insertions, 0 deletions

diff --git a/translating Snap.txt b/translating Snap.txt
new file mode 100755
index 0000000..c63b8a6
--- /dev/null
+++ b/translating Snap.txt
@@ -0,0 +1,143 @@
+*****************************
+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