Application Screens

Introduction

As the previous section mentioned, all application text in FoundationStone can be localised. The mechanism by which this happens is best illustrated by a specific example - then we'll see how to work with these resources generally.

The bare essentials!

Copy LocaleConstants.properties to a new file, lets say LocaleConstants.txt. Edit it. Send it in! Ask as many questions as you like, we'll mail back and forth to get it right!

If you're technically minded, read the following. OR - leave it to the geeks, and use the mini instructions above.

Example: German

Let's say someone installs the application in Austria, and launches it. The computer knows via the stored preferences the users language (code de) and the country (code AT), and passes this to Java.

FoundationStone looks for localisation resources inside the JavaSupport directory (Mac OSX users control click on the application to reveal package contents). First it looks for an Austrian dialect of German, which would be an ideal match - the file is called LocaleConstants_de_AT.properties. If present that file becomes the primary source for looking up the symbols needed. If not present, the next best thing is German - although not necessarily the Austrian dialect. It looks for LocaleConstants_de.properties. If it finds that, it becomes the secondary source. If it doesn't find either of these files, the application defaults to LocaleConstants.properties - which is English, the tertiary source. Note that the primary and secondary sources may not exist, but the tertiary always should.

To summarise, the application searches primary, secondary and tertiary in that order, until it finds a match for the symbol it needs. If no match is found it returns a default error message of "Bad" + "Symbol".

For example, say we have an Austrian user, a LocaleConstants_de.properties file but no LocaleConstants_de_AT.properties. Lets say the application is looking for the symbol "FoundationStoneWordStatistics".

primary:
no file
secondary:
FoundationStoneWordStatistics=Wortstatistiken
tertiary:
FoundationStoneWordStatistics=Word Statistics


It looks first in the primary source but it is absent. It then looks in the secondary, finds it and returns "Wortstatistiken". If it was still not found in the secondary, it would proceed to the tertiary source and return "Word Statistics". If it looked in all locations and didn't find the symbol, it would return "BadFoundationStoneWordStatistics" for use in the application - as a way of letting the translator know something is wrong.

From this discussion, you can see -

• How primary, secondary and tertiary override each other.
• Tertiary is never altered by the translator.
• How the primary country specific dialect (eg de_AT) can be just a few entries specific to that country, with the bulk of the translation coming from the secondary. This means there is no need for duplication of stuff already in the language file (eg de).
• How the secondary file must contain every key in the tertiary. Missing symbols would otherwise come from the default English translation.
• How this mechanism makes best use of tranlations from a previous releases. New symbols (which don't exist in a translation that needs updating) are replaced with the next best substitute.
• Having a primary country specific dialect file (eg de_AT) and no language file (de) only works for Austrian locales. The rest of the German speaking world misses out. Therefore do the (de) file first.
• Bad* style strings appearing in the application means the basic LocaleConstants_de.properties has been tampered with (or there are bugs in the shipping version).

Adding a New Translation

As discussed in the previous section, you need to choose a file name, with a language, and maybe also a country code on it. Copy LocaleConstants.properties and rename it first with the appropriate language code. When that is done, you may like to add a few of those entries in the country specific dialect file. Here is a list of codes for languages and countries.

You need then to translate each string attached to every symbol. Do not alter the symbol itself (see below in italics). Remember that some strings to translate (in bold) also contain embedded html tags - do not alter them. Also remember some lines contain spaces at the end, and some characters appearing in the middle of the line (eg "\=") are backquoted - it is important not to disturb them.

LexiconSearchTextAreaToolTip=<p>Enter a sentence or part of a sentence <b>of Hebrew</b> to search for,</p><p>by clicking the mouse on the keyboard to the right.</p><p>You can also type on the keyboard to enter Hebrew.</p>

Remember to delete your existing FoundationStonePreferences file if FoundationStone falls over when testing your file.

Additional Complications for Non Latin-1 and Two Byte Languages

Java's mechanism for handling localisation was decided upon in the early days of Unicode, when Unicode editors where rare. Unfortunately that means now that users of non Latin-1 languages (eg Russian which is typically Latin-5), or users of two byte languages (eg Japanese) much encode the non Latin-1 characters to quoted Unicode (eg \u0404). Note that the symbols (eg LexiconSearchTextAreaToolTip=) are not encoded because they are in Latin-1. Fortunately there is a Java tool to assist in this process called native2ascii (do a file search on the name to find it). This tool may be in a J2SE Software Development Kit on some platforms - see http://java.sun.com/j2se/ (requires an Internet connection) if you have trouble locating it.

encoding:
native2ascii -encoding encoding_name inputNativefile.txt LocaleConstants_xx_XX.properties
decoding:
native2ascii -encoding encoding_name -reverse LocaleConstants_xx_XX.properties outputNativefile.txt


Here is a list of encodings supported by Java 1.4.0i (international version). At the time of writing, Sun's latest documentation (subject to change) is at http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html (requires an Internet connection).