TRANSLATING BLISS

This document contains instructions for translating Bliss to another 
language.  If you wish to translate Bliss to another language, please 
read the contents of this document thoroughly.  If you still have 
questions regarding the translation process, feel free to contact the 
Bliss author at kdavissprint2@earthlink.net.


1. Understanding Internationalization and Localization

Internationalization (I18N) is the process of making an application 
easy to translate to another language.  Internationalization is only 
half of the total translation picture, however.  The actual translation 
of the text in an application to another language must still be 
performed and is referred to as "localization".


2. Understanding How Bliss is Internationalized

Although Bliss is completely internationalized, the author currently 
only provides a single localization for English, and it is up to those 
who are fluent in other languages to provide "language packs" that will 
translate or "localize" Bliss for other languages.  All of the text you 
see in the Bliss application is loaded from properties files.  These 
properties files are contained in the "i18n" subdirectory in the 
location where you installed Bliss.  Open one of these files in a text 
editor, such as the Windows Notepad, and you'll notice that the file is 
composed entirely of key/value pairs in the following format.

    {KeyName}={TextToDisplay}

For example, look in BlissResources.properties and you'll see this is 
one of the entries.

    OptionsDialogTitle=Options

In this example, "OptionsDialogTitle" is the key name that Bliss uses 
to look up the text to display in the title bar of the Options dialog.  
Since these are English properties files, you'll notice that the word 
"Options" is matched up with that key name.  This means the word 
"Options" will be displayed in the title bar of the Options dialog.


3. Localizing Bliss for Another Language

To tranlate Bliss to another language, it is important that you do not 
simply edit these properties files.  This is very important!  DO NOT 
EDIT THE PROPERTIES FILES THAT COME WITH BLISS!  Instead, you must 
create separate properties files that override and extend the current 
properties files.  The way you do this is by creating new properties 
files with a similar filename as the properties file you wish to 
translate, but with a special language code extension, like so.

    {ResourceFileName}_{LanguageCode}.properties

For example, to add a Spanish translation for the "BlissResources" 
properties file, you would append the Spanish language code of "es" to 
create the following new file.

    BlissResources_es.properties

The language codes are the official two-letter ISO Language Codes and 
they must be in lowercase form.  The official list of these language 
codes can be found here.

    http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

Now that you have your new BlissResources_es.properties file, try 
adding the following entry to it.

    OptionsDialogTitle=Opciones

At this point in this example, this should be the only entry in this 
file.  Now if you save this new file in the i18n subdirectory and run 
Bliss on a computer system in a Spanish locale, you'll notice that only 
the title of the Options dialog will be translated to Spanish.  
However, if you run Bliss on a computer in an English locale, the 
dialog will still show the English text "Options".

Herein lies the beauty of these properties files.  Firstly, you may 
translate only a portion of the application if you wish and leave the 
rest in the default language.  Secondly, the correct language will be 
loaded dynamically at the moment the application starts depending on 
the locale of the operating system on which Bliss runs.  Thirdly, 
anyone may maintain and deploy translations for Bliss completely 
independent from development of the Bliss emulator.


4. Creating a Language Pack

Now we're at the final point of creating the "language pack".  After 
you have made the desired translations, a language pack is simply a 
collection of all of the new properties files you have created.  A user 
should be able to download your language pack and unzip it into the 
"i18n" subdirectory.  Then when the user runs Bliss, it will 
automatically use this new translation if the user is in that locale.

Note that it is not necessary to send me your language pack for 
inclusion in the official version of Bliss.  Simply provide users with 
a zip file containing all of the new, extended properties files.  
However, if you wish to have your translation included in the official 
release or available on the official Bliss web site, feel free to send 
me your language pack for consideration in this process.  If you wish 
to have a language pack included in the official release, you must be 
willing to continue updating the language pack as the keys contained in 
the properties files are added, removed, and modified with each new 
release.

