Revision as of 20:53, 25 June 2006

How to design the software

There is only a few things which can help you using our library, the most important one is dividing completely the logic of the program from the content. In other words, you should write a class which contains all the strings you use in the program; so applying out system will be very easy.

How to use the library

Here you can find instructions on how to use our library; how to initialize the system and how to make the translations actually appear in your application.

Initialization

To initialize the library you should have a class that inherits from the SHARED_I18N_LOCALIZATOR; this will bring you all the necessary infrastructure to start localizing your software.

What to do?

• create datasource
• create datastructure
• load localizator

Creating a datasource

We equip you with a simple factory to create the sources, simply create an I18N_DATASOURCE_FACTORY

datasource_factory: I18N_DATASOURCE_FACTORY
 
create datasource_factory.make

you now have the possibility to create a new source based on an mo file, as follows

datasource: I18N_DATASOURCE
 
datasource_factory.use_mo_file(mo_file_path)
if datasource_factory.last_datasource /= Void then
  datasource := datasource_factory.last_datasource
end

if something went wrong, you can alway fallback with an empty datasource

datasource_factory.use_empty_source
datasource := datasource_factory.last_datasource

The datasource is ready, you should create a datastructure for storing the strings.

Creating a datastructure

We provide you with a simple factory to create datastructures, so follow the example

datastructure_factory: I18N_DATASTRUCTURE_FACTORY
 
create datastructure_factory.make

You can now create, for example, an hash table

datastructure: I18N_DATASTRUCTURE
 
datastructure_factory.use_hash_table
if datastructure_factory.last_datastructure /= Void then
  datastructure := datastructure_factory.last_datastructure
end

and, even in this case, if something went wrong, you can create a dummy datastructure

datastructure_factory.use_dummy
datastructure := datastructure_factory.last_datastructure

Now that you have the datastructure ready, you can load the localizator.

Loading the localizator

It's important that you do this part before trying to localize any string, if not, the localizator would serve you what you pass as argument.

Pass the source to the localizator

i18n_use_datasource(datasource)

then pass the datastructure

i18n_use_datastructure(datastructure)

and finally load the localizator with the new source and structure

i18n_load

You now have a working localization environment!

Warning: If you don't assign a source AND a structure AND then call load, the system will continue to use the old ones.

Localization

Here you can find some instructions to translate the strings of you program, including substituting variables into templates.

Translating simple strings

If you have a simple string to translate, like this

simple_string: STRING
 
simple_string := "A simple string"

you only have to enclose the string by the simple i18n() function

simple_string := i18n("A simple string")

the system will then be charged of the translation in whatever language you've chosen.

Translating plurals

Sometimes you must change the translated string in relation with a variable; this piece of code

string: STRING
i: INTEGER
 
if i = 1 then
  string := "There is 1 file"
else
  string := "There are more files"
end

will be written as follows using our system

string := i18n_pl("There is 1 file", "There are more files", i)

the right form will be selected and displayed for you.

Translating with templates

Warning: We encourage you to use a stand alone template engine and not rely on our built-in functions, which will not be maintained.

You can use our library to translate something like this

string := "Number " + i.out

in this way

string := i18n_comp("Number $1", [i])

and of course you can do the same with the plural forms

if i = 1 then
  string := "There is 1 file"
else
  string := "There are " + i.out + " files

would look like this

string := i18n_comp_pl("There is 1 file", "There are $1 files", [i], i)

we've so covered all the possibilities.

How to translate / use translation files

Editing PO files

You can edit the PO files created with your preferred editor; some possible tools are listed here.

Issues with MO files

Into the header section of the PO file must be present the "Plural-Forms" header.

It looks like this line:

"Plural-Forms: nplurals=2; plural=(n!=1);"

with "nplural" being the number of plurals of the destination language and "plural" the C-like function for finding the right plural form starting with an integer.