How to localize Waterbear

how_to_localize.md

Localizing Waterbear

Background

The bottom file is the default file for /languages/javascript/sound.json. The top one, sound (localized).json, has been stripped of unimportant fields and what remains are the strings related to localizing.

NOTE: When localizing files, they should be the same name as the default file. e.g. sound.json, not sound_localized.json

The fields related to localizing are:

• id - identifies each block so the original can be overwritten.
• name - name of section and actual text that appears on block.
• help - description of section and hover information text for blocks.

Steps to localizing:

1. Create a branch of master
2. Create a new directory under languages/javascript/localizations/ with the name of the two character locale code of the language you are translating.
   • mkdir languages/javascript/localizations/es for Spanish
   • Can be found here under "Code 2" column
3. Copy files from languages/javascript/ into the new directory
4. Strip unimportant parts of JSON. To make sure it is still valid JSON, please use a validator (usually its commas that mess things up)
5. Replace any text of the fields "name" or "help" with the appropriate language
6. Add appropriate filenames to localizations variable in the build script (format shown below).
7. Pull request

node Build Script

Below is an example format of the build script localizations variable. The variable in this format states that for javascript language, there are localization files for Spanish (es) with the file names of array.json and boolean.json.

If the files are not listed in the build script, then they will not be found by the program

var localizations = {
    javascript: {
        es: ['array', 'boolean']
    }
};

Directory Structure

languages
└── javascript
    ├── localizations
    │   └── es
    │       ├── sound.json
    │       └── ...
    ├── array.css
    ├── array.js
    ├── array.json
    ├── array_runtime.js
    └── ...

sound (localized).json

{
    "sectionkey": "sound",
    "name": "Sound",
    "help": "Sound blocks can load and play sound files (wav, mp3, ogg) if those files are supported by your browser.",
    "blocks": [
        {
            "id": "59f338b4-0f2f-489a-b4bd-b458fcb48e37",
            "sockets": [
                {
                    "name": "load audio## from url"
                }
            ],
            "locals": [
                {
                    "sockets": [
                        {
                            "name": "audio ##"
                        }
                    ]
                }
            ],
            "help": "Load a sound for playback"
        },
        {
            "id": "4deb2817-6dfc-44e9-a885-7f4b350cc81f",
            "sockets": [
                {
                    "name": "play sound"
                }
            ],
            "help": "play a sound"
        },
        {
            "id": "eb715a54-c1f2-4677-819a-9427537bad72",
            "sockets": [
                {
                    "name": "pause sound"
                }
            ]
        },
        {
            "id": "79f14360-3a3b-48de-83ae-240977cf343b",
            "sockets": [
                {
                    "name": "set sound"
                },
                {
                    "name": "looping to"
                }

            ]
        }
    ]
}

sound.json

{
    "sectionkey": "sound",
    "name": "Sound",
    "help": "Sound blocks can load and play sound files (wav, mp3, ogg) if those files are supported by your browser.",
    "blocks": [
        {
            "blocktype": "step",
            "id": "59f338b4-0f2f-489a-b4bd-b458fcb48e37",
            "script": "global.preloadAudio('##', {{1}});",
            "sockets": [
                {
                    "name": "load audio## from url",
                    "type": "string"
                }
            ],
            "locals": [
                {
                    "blocktype": "asset",
                    "sockets": [
                        {
                            "name": "audio ##"
                        }
                    ],
                    "script": "global.audio[\"##\"]",
                    "type": "sound"
                }
            ],
            "help": "Load a sound for playback"
        },
        {
        	"blocktype": "step",
        	"id": "4deb2817-6dfc-44e9-a885-7f4b350cc81f",
        	"script": "{{1}}.currentTime=0;{{1}}.play();",
        	"sockets": [
        		{
        			"name": "play sound",
        			"type": "sound"
        		}
        	],
        	"help": "play a sound"
        },
        {
        	"blocktype": "step",
        	"id": "eb715a54-c1f2-4677-819a-9427537bad72",
        	"script": "{{1}}.pause();",
        	"sockets": [
        		{
        			"name": "pause sound",
        			"type": "sound"
        		}
        	]
        },
        {
        	"blocktype": "step",
        	"id": "79f14360-3a3b-48de-83ae-240977cf343b",
        	"script": "{{1}}.loop={{2}};",
        	"sockets": [
        		{
        			"name": "set sound",
        			"type": "sound"
        		},
        		{
        			"name": "looping to",
        			"type": "boolean"
        		}

        	]
        }
    ]
}

just wondering, if I add suffix field to a socket that doesn't have suffix field in English, that will still work, right?

From the implementation of overwriteAttributes, it looks like it will. Try it?

I want to see how it looks in my local server but I can't seem to get my translation show up.

I've changed my broswer's language preference, and verified that in the header:
Accept-Language:zh-TW,zh;q=0.8,en-US;q=0.6,en;q=0.4,zh-CN;q=0.2

I've updated the build script:
var localizations = { javascript: { 'zh': ['control'] } };

But the block names are still in English after rebuilding...

ok, I figured it out.
First of all, I think the locale is not extracted from header, so I just use debugger to hack the locale value in initLanguageFiles.

Also, I copied an older version of the json file, so sectionkey is not included.

And the answer to my previous question is that, it works if I add suffix to a block that doesn't have suffix in English.
HOWEVER, if I remove suffix field from a block that has suffix in English, the English suffix will show up. Not sure if this is desired. (my current workaround is set the suffix field to the empty string)