Internationalization/SA developer manual
- 1 How to design the software
- 2 How to use the library
- 3 How to translate / use translation files
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.
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
then pass the datastructure
and finally load the localizator with the new source and structure
You now have a working localization environment!
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.
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
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.