Localization

This document describes the process of localizing NetLogo. Localization is the process of translating strings in NetLogo to another language.

User Manual

All or part of the User Manual has been translated into Czech, Chinese, and Japanese. these translations are available from http://ccl.northwestern.edu/netlogo/. All of them are now somewhat out of date. Updates by volunteers would be very welcome. New translations are also very welcome.

We don't currently have any automated assistance for this. As far as we know, all of the translations made so far were done by hand and independently.

GUI localization

Please note that the names and locations of the localization files changed in NetLogo 6.3.0

1. Copy the files

Download GUI_Strings_en.properties from https://github.com/NetLogo/NetLogo/tree/hexy/netlogo-gui/resources/i18n, and Errors_en.properties and Shared_Strings_en.properties from https://github.com/NetLogo/NetLogo/tree/hexy/shared/resources/main/i18n or get them from your clone of the NetLogo git repo.

Next, find the language code for your target language. Language codes can be found here: http://www.loc.gov/standards/iso639-2/php/code_list.php.

For example the code for Yoruba is yo. To start the process for a language that currently has no translations copy the files you have downloaded to corresponding files in which en is replaced by yo, resulting in the files GUI_Strings_yo.properties, Errors_yo.properties and Shared_Strings_yo.properties. Localizers will (instead of using yo) have to use the language code for their target language, obviously.

We currently have partial translations for the following languages:

Language	code
Chinese	zh
Japanese	ja
Portuguese	pt
Russian	ru
Spanish	es

If there is a non-empty translation file for your target language the non-translated english lines must be merged with the existing translations.

2. Open the files

You must open the file in UTF-8, and save the file in UTF-8. Most text editors have support for this. Here are the instructions on how to do so in TextEdit (on Mac):

"To choose a different text encoding:

In TextEdit, choose File > Open. Choose an encoding type from the Plain Text Encoding pop-up menu. If you don’t see the encoding you want to use, choose Customize Encodings List and then select the encodings you want to include. Select the file and then click Open."

3. Translate the files

Each of the files is a series of key value pairs, separated by an equals sign like so: key = value. The content on the right hand side of the equals sign (the value) is what needs to be translated to the target language. The key must be left exactly the same. For example:

In GUI_Strings_en.txt we have: common.observer = observer

and in GUI_Strings_ja.txt we have: common.observer = オブザーバ

You should translate all of the file. However, this isn't 100% required, you can translate just some of the values, leaving the English in place for the others. Doing this will cause the application to display some strings in the target language, and some in English. This is reasonable during testing.

Once you're done translating, save the file in UTF-8. If you opened it in your text editor in UTF-8, then it will probably save in UTF-8 as well.

4. Testing

Currently, to test the localization, you must:

• Unpack NetLogo.jar
• Add the .properties files to it
• Repack NetLogo.jar
• Rerun the application

See the attached script for the commands needed to do steps 1-3.

If everything went well so far, you should be able to restart NetLogo as normal. If your OS is already set to the language you added, NetLogo should now use it. If the language you added isn't your OS's default language, then to test your changes, type __change-language into the command center. A dialog will open showing a list of the available languages. Your new language should appear in the list. Select it, and restart NetLogo again. NetLogo should open in your new language.

5. Automated support

There is a script https://github.com/NetLogo/NetLogo/blob/5.x/bin/localize.sh to handle step 4 and and the first parts of step 5 (recreating the jar file) automatically. The script works on Mac OS X or Linux. (It might work on Windows if you run it under Cygwin.) Before running this script, you'll want to back up your NetLogo.jar file first.

To run the script execute this command:

./localize.sh ja

substituting the appropriate language code for ja.

Error message localization

1. Find the string (not as easy as it sounds because you have to look at every string and determine if it is something that needs to be pulled out into the properties file). devel/all-strings.txt has all the strings. if you see something there that doesn't need i18n, move it to devel/strings-not-being-globalized.txt.
2. look at the string and the way its concatenated (if it is) and figure out what all of its arguments are and what their types are (the types part i did not show above, but you can get more information here: http://download.oracle.com/javase/1.5.0/docs/api/java/text/MessageFormat.html)
3. create the result string that is going to go into the properties file (above: can't set {1} variable {2} to non-{3} {4})
4. choose a name for the key in the properties file.
5. get an example of the string (also not as easy as it sounds because it might not be immediately obvious from the code, and might be non-trivial to reproduce)
6. put the example, key, and string into the properties file (in the dist/i18n directory)
7. put the example in the code
8. change the code to use I18N instead of the hardcoded string
9. go to google translate and get a spanish translation of the string, and put it into the spanish errors file (this is actually pretty trivial because we can do the whole file in one shot, and can probably automate it)
10. open up netlogo in english and make sure that you can see the string, and that it works properly
11. open up netlogo in spanish and make sure that you can see the string, and that it works properly
12. write a test for the english string so that we never regress and throw stack traces at the user
13. remove the string from all-strings.txt