INTERNATIONALIZATION

Introduction

Javascore is set up to support "internationalization". Internationalization (i18n) means essentially that the program has been modified to allow it to work gracefully with users in different locations around the world who may use different formatting conventions and different whole languages.

JavaScore supports i18n in three primary ways. 

a) The formatting of dates and numbers in the various JavaScore reports will automatically adjust to the regional settings of the computer on which you are running. For example, if your PC is setup to use Swedish as the default language, then the formatting conventions commonly use in Swedish.

b) The text labels and titles (known as 'resources') within the various screens and reports of JavaScore itself can now be substituted by resources written in a different language

c) The help files can also be substituted with help files written in a different language

The "bad news" is that the author of JavaScore, Sandy Grosvenor, is an American who speaks no foreign languages, so she cannot write resources or helps for new languages. So there are few alternative localizations available ("localization" is the technical term for developing support for a new language).

The "good news" is that the process of developing a new is straightforward and can be done by anyone who has downloaded and install JavaScore. You don't even need to download or know anything about the source code to the program. Several people around the world have offered to write new localizations once JavaScore supported them.

The other piece of good news, is that formatting standards such as using 'commas' in Europe to mark decimal places is automatically supported in JavaScore now whether or not a set of localized resources and help files have been created/installed on your system.

The rest of the page will describe how to install a localization (as soon as they exist) and for those who have volunteered to develop localizations, the directions for doing so.

Installing a new Localization created by someone else

My hope and expectation is that as new localizations are developed, they will be bundled in the next master JavaScore release so support will be automatic. I also plan to "release" new localization independent of a JavaScore release so that if, for example, a Spanish localization is created, it can be made available on the JavaScore web page without having to wait for a new release of JavaScore.

This sections describes how to install a new localization once it is made available.

Each new language's localization will be distributed as 'zip' file.  All you need to do is download the Zip file, and then "unpack" it into the directory that you installed Javascore into.

THAT'S IT! Once you installed these files, if your computer's regional settings are set to French, JavaScore should automatically pull up French language labels, and help information. How you change regional settings on your computer varies with operating system and version. In Windows (2000 at least, and I think in 95 onwards), you can change these in the Control Panel (in Windows 2000, the icon is called "Regional Options')

If your system's regional setting are for one language and you'd like to run javascore with a different language.  Simply go to the File | Preferences dialog and set the "Locale".  Then exit and restart JavaScore and most dialogs should now come up in the new language.  Note that some of the "standard" dialogs like choosing files will always show in the regional settings (this is a "feature" of Java, I don't control it).

Develop new Localization

The steps for creating a new Localization are pretty simple. All you need to do is create a 'properties' file and a set of help files. The easiest way to do that is to copy the default English files to the language files you are planning to develop and then customize the new files as necessary.

Once you've finished a set of files, if you email them back to me (sandy@gromurph.org) I'll double check that they work right and post them to gromurph.org for others to download install.

Since JavaScore is an Open Source project, the program is free to end-users. I consider this whole project a give-back to a sport I love. I hope that those offering to write additional language extensions will feel the same.

I'll happily give credit in Javascore's About page to anyone contributing to language extensions, but I am not able to offer any additional compensation.

What follows are the step-by-step guidelines for creating a new language extension. In a nutshell, here are the steps:

• · Send me (sandy@gromurph.org) an email indicating what language you'd like to work on. I'll let you know if anyone else is already working on that language. If so, you can team up with them
• · Create a language specific version of JavaScore_xx.properties and the DialogProperties_xx.properties
• · Create a language specific set of help files
• · Email it all back to me, and I'll post it to the javascore web page and integrate it into the next release of JavaScore.

How to determine the right country/region codes?

An international standard for establishing abbreviations to recognize different locales has been emerging over the last decade or two. Naturally, since its "emerging" and the international standard needs to accommodate a whole variety of languages, dialects, and other regional flavors: a comprehensive description is complicated.

But it can be simplified pretty easily. Here's a table of the main languages. Several of these have multiple "sub-sets." English, for example, has 13 different sub-sets from Australia to Zimbabwe. If you are creating a localization for a whole new language, I suggest sticking to the simple 2-digit language code below. If you'd like to do a regional sub-flavor, and don't already know enough about these codes, email me with the region you'd like to work on and I'll look up the right codes. There are multiple web references but they are all hopelessly complicated and intimidating to read (check out the official ISO description if you want to see just how complicated: http://www.w3.org/International/).

Here are the main language codes. I'm especially interested in volunteers to get working on French, Spanish, German, and Swedish versions.

Languages such as Japanese that involve substantial character differences or Hebrew which involves major layout distinctions are much lower on my list and probably JavaScore's level of intenationalization is probably not yet up to supporting languages so different from the English (or should I say American) baseline.

Afrikaans	Af	English	en	Icelandic	is	Romanian	ro
Albanian	Sq	Esperanto	eo	Irish	ga	Russian	ru
Arabic	Ar	Estonian	et	Italian	it	Scottish	gd
Basque	Eu	Faroese	fo	Japanese	ja	Serbian	sr
Bulgarian	Bg	Finnish	fi	Latvian	lv	Slovak	sk
Byelorussian	Be	French	fr	Lithuanian	lt	Slovenian	sl
Catalan	Ca	Galician	gl	Macedonian	mk	Spanish	es
Croatian	Hr	German	de	Maltese	mt	Swedish	sv
Czech	Cs	Greek	el	Norwegian	no	Turkish	tr
Danish	Da	Hebrew	iw	Polish	pl	Ukrainian	uk
Dutch	Nl	Hungarian	hu	Portuguese	pt

Editing the .properties files

The .properties file contains the various labels and message used within the Javascore program itself. It a very simple format, just a list of 'key=value' pairs. Each label or message inside the program has a "key" associated with it. When the program needs a string, it does a lookup for an entry with the same "key".

This lookup is hierarchical based on the user's localization and what .properties files JavaScore finds. The highest level is 'JavaScore.properties' which contains Americanized English.

By default, the JavaScore.properties file is found in the zip-file "JavaScore.jar". You can open the JavaScore.jar file with any standard "zip" utility (I use winzip on my windows platform, its available at www.winzip.com). Extract JavaScore.properties from the .jar file and store on your local machine your install directory. Then rename the file to JavaScore_xx.properties, where 'xx' is the language you are developing.

Do the equivalent things with the GeneralProperties.properties, although it should be copied as: GeneralProperties_xx.properties where 'xx' is the language you are developing.

Then edit the files replacing the values on the right of the '=' sign in each line with the appropriate language specific text.

A couple of hints/suggestions:

a) Use a simple text editor such as Windows' Notepad or Wordpad. Several of the values contain special characters, and full word processors such as Microsoft Word, try "too hard" to interpret the file and will not save the file in a format that JavaScore can then read.

b) There is a rough naming convention for the keys in the properties file. The key names have been set to be reasonably intuitive rather than generate copious documentation.

The first piece of the key is "topical' and should related reasonably intuitively to a particular section or dialog in JavaScore. For example, all the labels for the menus begin with "Menu." The second part of the key word is usually indicative of the "type" of the text that the key applies. Often a third part of the key is indicative of which component in a dialog to which the key applies. For example, the key "DivisionLabelClassName" contains the text for the Label of the ClassName field in the Division dialog.

Some other conventions: "ColHead" are the various headers for reports, "Gen" are various general labels used in several places, "Penalty" contains keys that both define the types of Penalties and the text in the "Penalty" dialog; key containing the phrase "Message" are generally message used in various popup dialogs

c) On the value side (to the right of the "=" sign), a couple of useful things to know. In most cases, the text is copied into the program without modification. There are some special cases:

· Where you see a backslash, "\": this flags a special character. "\n" is a new line, "\\" is a real backslash.

· Some values contain a number surrounded by brackets, such as {0}. In these cases, inside JavaScore a variable is substituted at run-time for that {0}. You can usually tell what the variable is from the context of the primary English ".properties" file.

· Some values are actually segments of HTML. If you see elements such as "<br>" that's an indication of HTML subset text. Again, use your judgment and deduce from the English what makes sense for a different language.

Create new Help files

Creating a set of help files requires some knowledge of HTML and/or web page creation, since the help files are nothing but a bunch of web pages.

The help files are a linked set of files designed so that the same help files can be accessed in a couple different ways. They can be access as regular web pages with links to each other. They can also be accessed via a set of keys and links in a context-sensitive way from within the JavaScore program.

The default English help files are stored in the javascore.jar file. The best way to get started creating a translation of them is, like the properties files above, to extract them from the .jar file, renamed them to the right localization and then modify them as necessary.

What you need to know about the javahelp system

The help system is a hierarchical one. At the "top" level is a file called help/JavaScore.hs in the JavaScore.jar file. It tells the Java Help Manager how the help files fit together. The English based help files are all in the .jar file in a directory /help/en (en for English)

The JavaScore.hs is a technically an XML file, but you can edit it in any old text editor. If you look you will see that it has pointers to files in the /en directory.

One of the main files that the JavaScore.hs file references in /help/en/map.jhm. This file contains a mapping from various keys to their html file locations. The keys in the map.jhm file are referenced from within JavaScore and it performs a lookup to find the appropriate .html file to display to the user.

Creating a new language/sub-language

To get started on translating do the following:

· Extract from the javascore.jar file (use WinZip) all the files in the /help/ and /help/en subdirectory. Store this off the directory in which you have javascore installed.

· Rename the <jshome>/help/en subdirectory to /help/xx, where xx is your language code (fr for French)

· Rename <jshome>/help/JavaScore.hs file to JavaScore_xx.hs

· Edit the JavaScore_xx.hs file, change all occurrences of en/ to xx/. You should also translate the text in the "<title>" and "<label>" tags.

· Go into the /help/xx directory and translate the .html files to your target language. Be careful to keep all bookmarks in place and unchanged.

Submitting changes

For now, just email the newly translated files back to me (sandy@gromurph.org) and I'll double check them and then bundle them up and post them to the JavaScore web site.

Is it pretty likely that there are glitches and things I've overlooked in doing the internationalization. Please let me know of any bugs and other problems that you find. Thanx much