Leo: copy/paste-moved from Internationalization/developer manual

2006-08-16T00:22:18Z

copy/paste-moved from Internationalization/developer manual

New page

[[Category:Internationalization SA project]]

= 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

<code>[eiffel,N]
datasource_factory: I18N_DATASOURCE_FACTORY

create datasource_factory.make
</code>

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

<code>[eiffel,N]
datasource: I18N_DATASOURCE

datasource_factory.use_mo_file(mo_file_path)
if datasource_factory.last_datasource /= Void then
datasource := datasource_factory.last_datasource
end
</code>

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

<code>[eiffel,N]
datasource_factory.use_empty_source
datasource := datasource_factory.last_datasource
</code>

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

<code>[eiffel,N]
datastructure_factory: I18N_DATASTRUCTURE_FACTORY

create datastructure_factory.make
</code>

You can now create, for example, an hash table

<code>[eiffel,N]
datastructure: I18N_DATASTRUCTURE

datastructure_factory.use_hash_table
if datastructure_factory.last_datastructure /= Void then
datastructure := datastructure_factory.last_datastructure
end
</code>

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

<code>[eiffel,N]
datastructure_factory.use_dummy
datastructure := datastructure_factory.last_datastructure
</code>

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

<code>[eiffel,N]
i18n_use_datasource(datasource)
</code>

then pass the datastructure

<code>[eiffel,N]
i18n_use_datastructure(datastructure)
</code>

and finally load the localizator with the new source and structure

<code>[eiffel,N]
i18n_load
</code>

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

<code>[eiffel,N]
simple_string: STRING

simple_string := "A simple string"
</code>

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

<code>[eiffel,N]
simple_string := i18n("A simple string")
</code>

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

<code>[eiffel,N]
string: STRING
i: INTEGER

if i = 1 then
string := "There is 1 file"
else
string := "There are more files"
end
</code>

will be written as follows using our system

<code>[eiffel,N]
string := i18n_pl("There is 1 file", "There are more files", i)
</code>

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

<code>[eiffel,N]
string := "Number " + i.out
</code>

in this way

<code>[eiffel,N]
string := i18n_comp("Number $1", [i])
</code>

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

<code>[eiffel,N]
if i = 1 then
string := "There is 1 file"
else
string := "There are " + i.out + " files
</code>

would look like this

<code>[eiffel,N]
string := i18n_comp_pl("There is 1 file", "There are $1 files", [i], i)
</code>

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 [[Internationalization/tool_evaluation|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.

Internationalization/SA developer manual - Revision history

Leo: copy/paste-moved from Internationalization/developer manual