Jeremy B edited this page Apr 26, 2018 · 16 revisions
Clone this wiki locally


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

1. Copy the files

Download GUI_Strings_en.txt and Errors_en.txt from https://github.com/NetLogo/NetLogo/tree/hexy/netlogo-gui/project/autogen/i18n, or get them from your clone of the NetLogo git repo, and copy them to GUI_Strings_ja.txt and Errors_ja.txt

Notice that en is renamed to ja. ja is the language code for Japanese. Localizers will (instead of using ja) have to use the language code for their target language, obviously. Language codes can be found here: http://www.loc.gov/standards/iso639-2/php/code_list.php

We also support adding a country code, for example: GUI_Strings_ja_JP.txt. However, the reasons for doing that are more complicated and I'm not ready to explain them just yet.

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. Convert the files to ascii.

Java's built in internationalization library won't read the files in UTF-8. First, they must be converted to ascii. To do this, use Java's native2ascii tool at the command line, like so:

native2ascii -encoding UTF-8 GUI_Strings_ja.txt > GUI_Strings_ja.properties

This creates an ascii file called GUI_Strings_ja.properties that contains the same contents of the original file, except in an encoding that Java can read it in.

Do the same thing for the Errors_ja.txt

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

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