EiffelStudio: an EiffelSoftware project - User contributions [en]

Internationalization/Developer guide

2006-10-31T15:45:12Z

Leo:

[[Category:Internationalization]]
=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|500px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost class, HOST_LOCALE, is responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses an implementation of HOST_LOCALE and a DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|500px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a HOST_LOCALE_IMP.

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|500px|Section of the i18n library that retrieves translations]]

The part of the library that provides translated strings is slightly more complicated. The strings come from a so-called data source (or datasource, depending on preference). The uri given to a LOCALE_MANAGER on creation is examined by a URI_PARSER, which decides what sort of data source this uri represents. It then creates an appropriate DATASOURCE_MANAGER* with this uri and returns it to the LOCALE_MANAGER.

From this point onwards the DATASOURCE_MANAGER* is responsible for the main operations involving translations: providing a list of locales and languages for which a translation is present, and providing the translation in form of a DICTIONARY* for a given locale.
A DICTIONARY* is nothing more then a collection of translated strings, with functions to access them. There are several effective descendants, as the best way to store the strings may depend on several factors (singular/plural ration, data source itself, etc.). The LOCALE_MANAGER gets the relevant DICTIONARY* from the DATASOURCE_MANAGER* and passes it to the LOCALE on creation. The LOCALE can then retrieve translations.

If there are translations for both a locale itself and it's language, the DATASOURCE_MANAGER* will of course return a DICTIONARY* containing the translations specifically for that locale. If there is no translation for the locale but one exists for it's language, that will be used.

===File data source ===

The file datasource works in the following way:
The FILE_MANAGER, an effective DATASOURCE_MANAGER*, has a chain-of-responsibility built from FILE_HANDLER*s.
There are two operations provided by this chain of responsibility: determining the scope of a file (i.e which language or locale it corresponds to) and providing a DICTIONARY* containing the strings from this file.
By using this chain and a list of files in the current directory, the FILE_MANAGER can list available locales, list available languages and provide DICTIONARY* objects. The precise type of DICTIONARY* provided is dependant on the type of file.

Each FILE_HANDLER* works by using a FILE* object, which provides the actual parsing functionality for a given file type.
Currently the only supported file type is the .mo file format, so this is the only example I may provide.

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this) or of having a translation spanned over multiple .mo files for one locale.

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/User guide

2006-10-24T11:42:37Z

Leo:

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call default_locale.
<code>[eiffel, N]
my_locale := locale_mananger.default_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is available for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_localised_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

(The difference between a translation and a localised translation is that a localised translation is specific to a region: fr_CA or de_CH, for example. A translation is specific only to a language: fr or de, for example)

You can then retrieve the corresponding LOCALE object by calling locale_with_id, providing the desired LOCALE_ID.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translated (original: STRING_GENERAL): STRING_32
translated_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
formatted_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translated("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, which we can use in this way:
<code>[eiffel,n]
n := number_of_hovercraft
io.put_string(my_locale.translated_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := number_of_hovercraft
plural_string := my_locale.translated_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.formatted_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

=====Misuse=====

It is not a good idea, generally speaking, to do something like the following:

<code>[eiffel, N]
n := number_of_eels
io.put_string(my_locale.translated("My hovercraft has "+n.out+"eels"))
</code>

There are two reasons for this:

* What the translation function will see as an argument is runtime-dependant. It may correspond to an actual entry in the datasource, if you are careful, but in the example above it probably won't unless you have entries for every possible value of n. This is the reason for which we have the format_string feature in LOCALE - please use it!

*When you want to generate a .po file to give to translators, this sort of thing is not going to make the command that extracts it very happy. What will happen is that it will extract the first constant STRING argument and ignore the rest, so your .po file will have an "My hovercraft has " entry and unless you correct this by hand very probably at runtime the i18n library will not be able to find a translation.

====Formatting====
=====Interface=====
DATE_FORMATTER provides:
<code>[eiffel, N]
formatted_date(date:DATE):STRING_32
formatted_time(time: TIME): STRING_32
formatted_date_time(date_time:DATE_TIME):STRING_32
</code>

CURRENCY_FORMATTER provides:
<code>[eiffel, N]
formatted_currency (a_value: REAL_64): STRING_32
</code>

VALUE_FORMATTER provides:
<code>[eiffel, N]
formatted_integer_8 (a_integer_8: INTEGER_8): STRING_32
formatted_integer_16 (a_integer_16: INTEGER_16): STRING_32
formatted_integer_32 (a_integer_32: INTEGER_32): STRING_32
formatted_integer_64 (a_integer_64: INTEGER_64): STRING_32
formatted_real_32 (a_real_32: REAL_32): STRING_32
formatted_real_64 (a_real_64: REAL_64): STRING_32
</code>
=====Usage=====

The LOCALE class makes 3 formatters accessible to clients: a VALUE_FORMATTER, a DATE_FORMATTER and a CURRENCY_FORMATTER, exposed as features under the names value_formatter, date_formatter and currency_formatter respectively.
Using these formatters is fairly straightforward: you simply call the appropriate function for the type of object that you want to format.

======Date formatting======

The DATE_FORMATTER class can format EiffelTime DATE, TIME and DATE_TIME classes in a way appropriate to the locale. For example, to get a string representation of today's date in a given locale, you might write:

<code>[eiffel, n]
io.put_string(my_locale.formatted_date(create {DATE}.make_now))
</code>

Currently eras of non-gregorian calendars are not well supported.

======Value and currency formatting======

The VALUE_FORMATTER and CURRENCY_FORMATTER classes can format integers and reals according to the conventions of a given locale - number of digits after the decimal separator, the decimal separator itself, grouping of digits and so on.

Using them is just as easy as DATE_FORMATTER: just call the function appropriate to the type of object who's value you want to format.

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

If you are using the es-i18n branch, this command is in the "Tools" menu ("Generate .po"). One click and it will prompt you for a location to write the .po file to. This is basically all there is to it.
It is helpful to understand how it works (see the 'Misuse' section): it extracts the arguments of calls to the translate and translate_plural functions. Largely it will not behave satisfactorily if the string is made up of several parts glued together at run-time.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_manager.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) or the language identifier of the target language (zh or de, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/Developer guide

2006-10-24T11:38:26Z

Leo:

[[Category:Internationalization]]
=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost class, HOST_LOCALE, is responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses an implementation of HOST_LOCALE and a DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a HOST_LOCALE_IMP.

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

The part of the library that provides translated strings is slightly more complicated. The strings come from a so-called data source (or datasource, depending on preference). The uri given to a LOCALE_MANAGER on creation is examined by a URI_PARSER, which decides what sort of data source this uri represents. It then creates an appropriate DATASOURCE_MANAGER* with this uri and returns it to the LOCALE_MANAGER.

From this point onwards the DATASOURCE_MANAGER* is responsible for the main operations involving translations: providing a list of locales and languages for which a translation is present, and providing the translation in form of a DICTIONARY* for a given locale.
A DICTIONARY* is nothing more then a collection of translated strings, with functions to access them. There are several effective descendants, as the best way to store the strings may depend on several factors (singular/plural ration, data source itself, etc.). The LOCALE_MANAGER gets the relevant DICTIONARY* from the DATASOURCE_MANAGER* and passes it to the LOCALE on creation. The LOCALE can then retrieve translations.

If there are translations for both a locale itself and it's language, the DATASOURCE_MANAGER* will of course return a DICTIONARY* containing the translations specifically for that locale. If there is no translation for the locale but one exists for it's language, that will be used.

===File data source ===

The file datasource works in the following way:
The FILE_MANAGER, an effective DATASOURCE_MANAGER*, has a chain-of-responsibility built from FILE_HANDLER*s.
There are two operations provided by this chain of responsibility: determining the scope of a file (i.e which language or locale it corresponds to) and providing a DICTIONARY* containing the strings from this file.
By using this chain and a list of files in the current directory, the FILE_MANAGER can list available locales, list available languages and provide DICTIONARY* objects. The precise type of DICTIONARY* provided is dependant on the type of file.

Each FILE_HANDLER* works by using a FILE* object, which provides the actual parsing functionality for a given file type.
Currently the only supported file type is the .mo file format, so this is the only example I may provide.

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this) or of having a translation spanned over multiple .mo files for one locale.

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/Developer guide

2006-10-21T23:56:21Z

Leo:

[[Category:Internationalization]]
=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost classes, SYSTEM_LOCALES and HOST_LOCALE, are responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses an implementation of HOST_LOCALE and a DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

TODO: expand? formatters?

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a HOST_LOCALE_IMP.

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

The part of the library that provides translated strings is slightly more complicated. The strings come from a so-called data source (or datasource, depending on preference). The uri given to a LOCALE_MANAGER on creation is examined by a URI_PARSER, which decides what sort of data source this uri represents. It then creates an appropriate DATASOURCE_MANAGER* with this uri and returns it to the LOCALE_MANAGER.

From this point onwards the DATASOURCE_MANAGER* is responsible for the main operations involving translations: providing a list of locales and languages for which a translation is present, and providing the translation in form of a DICTIONARY* for a given locale.
A DICTIONARY* is nothing more then a collection of translated strings, with functions to access them. There are several effective descendants, as the best way to store the strings may depend on several factors (singular/plural ration, data source itself, etc.). The LOCALE_MANAGER gets the relevant DICTIONARY* from the DATASOURCE_MANAGER* and passes it to the LOCALE on creation. The LOCALE can then retrieve translations.

If there are translations for both a locale itself and it's language, the DATASOURCE_MANAGER* will of course return a DICTIONARY* containing the translations specifically for that locale. If there is no translation for the locale but one exists for it's language, that will be used.

===File data source ===

The file datasource works in the following way:
The FILE_MANAGER, an effective DATASOURCE_MANAGER*, has a chain-of-responsibility built from FILE_HANDLER*s.
There are two operations provided by this chain of responsibility: determining the scope of a file (i.e which language or locale it corresponds to) and providing a DICTIONARY* containing the strings from this file.
By using this chain and a list of files in the current directory, the FILE_MANAGER can list available locales, list available languages and provide DICTIONARY* objects. The precise type of DICTIONARY* provided is dependant on the type of file.

Each FILE_HANDLER* works by using a FILE* object, which provides the actual parsing functionality for a given file type.
Currently the only supported file type is the .mo file format, so this is the only example I may provide.

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this) or of having a translation spanned over multiple .mo files for one locale.

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/Developer guide

2006-10-21T23:55:31Z

Leo: modified to reflect recent changes in library (language translations)

[[Category:Internationalization]]
=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost classes, SYSTEM_LOCALES and HOST_LOCALE, are responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses an implementation of HOST_LOCALE and a DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

TODO: expand? formatters?

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a HOST_LOCALE_IMP.

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

The part of the library that provides translated strings is slightly more complicated. The strings come from a so-called data source (or datasource, depending on preference). The uri given to a LOCALE_MANAGER on creation is examined by a URI_PARSER, which decides what sort of data source this uri represents. It then creates an appropriate DATASOURCE_MANAGER* with this uri and returns it to the LOCALE_MANAGER.

From this point onwards the DATASOURCE_MANAGER* is responsible for the main operations involving translations: providing a list of locales and languages for which a translation is present, and providing the translation in form of a DICTIONARY* for a given locale.
A DICTIONARY* is nothing more then a collection of translated strings, with functions to access them. There are several effective descendants, as the best way to store the strings may depend on several factors (singular/plural ration, data source itself, etc.). The LOCALE_MANAGER gets the relevant DICTIONARY* from the DATASOURCE_MANAGER* and passes it to the LOCALE on creation. The LOCALE can then retrieve translations.

If there are translations for both a locale itself and it's language, the DATASOURCE_MANAGER* will of course return a DICTIONARY* containing the translations specifically for that locale. If there is no translation for the locale but one exists for it's language, that will be used.

===File data source ===

The file datasource works in the following way:
The FILE_MANAGER, an effective DATASOURCE_MANAGER*, has a chain-of-responsibility built from FILE_HANDLER*s.
There are two operations provided by this chain of responsibility: determining the scope of a file (i.e whoch language or locale it corresponds to) and providing a DICTIONARY* containing the strings from this file.
By using this chain and a list of files in the current directory, the FILE_MANAGER can list available locales, list available languages and provide DICTIONARY* objects. The precise type of DICTIONARY* provided is dependant on the type of file.

Each FILE_HANDLER* works by using a FILE* object, which provides the actual parsing functionality for a given file type.
Currently the only supported file type is the .mo file format, so this is the only example I may provide.

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this) or of having a translation spanned over multiple .mo files for one locale.

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Talk:Internationalization/Developer guide

2006-10-21T23:49:16Z

Leo:

TODO: update picture, as SYSTEM_LOCALES has been scrapped.

Internationalization/User guide

2006-10-21T23:48:06Z

Leo: update

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is available for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_localised_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

(The difference between a translation and a localised translation is that a localised translation is specific to a region: fr_CA or de_CH, for example. A translation is specific only to a language: fr or de, for example)

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, which we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

=====Misuse=====

It is not a good idea, generally speaking, to do something like the following:

<code>[eiffel, N]
n := get_number_of_eels
io.put_string(my_locale.translate("My hovercraft has "+n.out+"eels"))
</code>

There are two reasons for this:

* What the translation function will see as an argument is runtime-dependant. It may correspond to an actual entry in the datasource, if you are careful, but in the example above it probably won't unless you have entries for every possible value of n. This is the reason for which we have the format_string feature in LOCALE - please use it!

*When you want to generate a .po file to give to translators, this sort of thing is not going to make the command that extracts it very happy. What will happen is that it will extract the first constant STRING argument and ignore the rest, so your .po file will have an "My hovercraft has " entry and unless you correct this by hand very probably at runtime the i18n library will not be able to find a translation.

====Formatting====
=====Interface=====
DATE_FORMATTER provides:
<code>[eiffel, N]
format_date(date:DATE):STRING_32
format_time(time: TIME): STRING_32
format_date_time(date_time:DATE_TIME):STRING_32
</code>

CURRENCY_FORMATTER provides:
<code>[eiffel, N]
format_currency (a_value: REAL_64): STRING_32
</code>

VALUE_FORMATTER provides:
<code>[eiffel, N]
format_integer_8 (a_integer_8: INTEGER_8): STRING_32
format_integer_16 (a_integer_16: INTEGER_16): STRING_32
format_integer_32 (a_integer_32: INTEGER_32): STRING_32
format_integer_64 (a_integer_64: INTEGER_64): STRING_32
format_real_32 (a_real_32: REAL_32): STRING_32
format_real_64 (a_real_64: REAL_64): STRING_32
</code>
=====Usage=====

The LOCALE class makes 3 formatters accessible to clients: a VALUE_FORMATTER, a DATE_FORMATTER and a CURRENCY_FORMATTER, exposed as features under the names value_formatter, date_formatter and currency_formatter respectively.
Using these formatters is fairly straightforward: you simply call the appropriate function for the type of object that you want to format.

======Date formatting======

The DATE_FORMATTER class can format EiffelTime DATE, TIME and DATE_TIME classes in a way appropriate to the locale. For example, to get a string representation of today's date in a given locale, you might write:

<code>[eiffel, n]
io.put_string(my_locale.format_date(create {DATE}.make_now))
</code>

Currently eras of non-gregorian calendars are not well supported.

======Value and currency formatting======

The VALUE_FORMATTER and CURRENCY_FORMATTER classes can format integers and reals according to the conventions of a given locale - number of digits after the decimal separator, the decimal separator itself, grouping of digits and so on.

Using them is just as easy as DATE_FORMATTER: just call the function appropriate to the type of object who's value you want to format.

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

If you are using the es-i18n branch, this command is in the "Tools" menu ("Generate .po"). One click and it will prompt you for a location to write the .po file to. This is basically all there is to it.
It is helpful to understand how it works (see the 'Misuse' section): it extracts the arguments of calls to the translate and translate_plural functions. Largely it will not behave satisfactorily if the string is made up of several parts glued together at run-time.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_manager.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) or the language identifier of the target language (zh or de, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/obstacles

2006-10-21T23:33:11Z

Leo: added obstacle in ES

==Obstacles found during the semester project==

===Library===

No significant problems. There were some slight hiccups with UTF-16, as the gobo parser expects a BOM and so cannot parse UTF16LE or UTF-16BE. Unluckily for us, windows uses little-endian UTF-16.

===EiffelStudio===

*Formatters require a certain property to be a lowercase string and read this directly from INTERFACE_NAMES, meaning that if the i18n library supplies a translated string that is not lowercase, an exception violation happens. This would superficially be relatively easy to fix, but it is not such a good idea to do this anyway, because with STRING_32 there may not even be a lowercase version of the string (asian scripts come to mind). This behaviour may also happen elsewhere, but I am not sure.

==Problems encountered during the SA project==

===Problems we encountered during implementation===

* Unicode (UTF-8) support was not fully implemented (e.g. for gtk)
* Facilities to write and read STRING_32 to/from files were not present

===Difficulties to complete the translation of EiffelStudio:===
* Many strings are hard-coded anywhere inside EiffelStudio, making the translation difficult
* All the functions taking strings as arguments expect a STRING, where they should expect a STRING_GENERAL, and they return a STRING which may not be applicable in every case. A STRING_32 can also represent the same content of a STRING_8, thus it should be preferred.
* It seems that to_uppercase and to_lowercase procedures are not defined for STRING_32 and are used in the studio, these should have been implemented by the vision project and may be buggy.

Internationalization/obstacles

2006-10-18T02:11:34Z

Leo:

Internationalization

2006-10-18T02:07:32Z

Leo: removed old milestones, added status

[[Category:Projects]]
[[Category:Internationalization]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

===Brief history===

Orginally the internationalisation (i18n) project was started as a required project for an ETH Software Architecture course.
The result was less then perfect; pages referring to this first version have been given an 'SA' prefix.
Some members of this SA project team decided to rewrite the library as a semester project. Pages on the wiki not prefixed with 'SA' are either applicable to both or to the semester project.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=== Specific goals of the semester project ===

The new i18n library should provide translation as well as date, time, value and currency formatting.
It should run on at least windows (with and without .NET) and linux.

=Status=

As of 16 October 2006 we have all features working and almost all tested.
Some difficulty exists with the windows installation procedure. The linux version works without problems.

= Documentation =

* [[Internationalization/User_guide|User guide]]: how to use the i18n library
* [[Internationalization/Developer_guide|Developer guide]]: developer manual for the i18n library
* [[Internationalization/obstacles|Obstacles]]: setbacks we have encountered

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

== Semester project ==

* [[User:leo| Leo Fellmann]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei|Hong Zhang]]
* [[User:Trosim|Martino Trosi]]
* Supervisor: [[User:Schoelle| Bernd Schoeller]]

== Old SA project team ==
* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization

2006-10-16T15:15:07Z

Leo:

[[Category:Projects]]
[[Category:Internationalization]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

===Brief history===

Orginally the internationalisation (i18n) project was started as a required project for an ETH Software Architecture course.
The result was less then perfect; pages referring to this first version have been given an 'SA' prefix.
Some members of this SA project team decided to rewrite the library as a semester project. Pages on the wiki not prefixed with 'SA' are either applicable to both or to the semester project.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=== Specific goals of the semester project ===

''to be completed''

=Milestones=

''add milestones of semesterproject''

==Mx: ??? ==
* Write a summary of how [[Internationalization/posix_locale|POSIX locale]] information is stored
* Write a summary of how [[Internationalization/nls_locale|NLS (Windows) locale]] infomation is stored
* Write a summary of how [[Internationalization/dotnet_locale|.NET locale]] information is stored
* Write a small summary of date and time classes in EiffelBase
* Examine the .ts file format, notably plural form handling
* Examine the .xliff file format, notably plural form handling (we did some of this already)
* Enter classes & features into EiffelStudio so we have a starting point and a BON diagram
* Sit down and think about the current class names. Some of them need improving.

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Documentation =

* [[Internationalization/User_guide|User guide]]: how to use the i18n library
* [[Internationalization/Developer_guide|Developer guide]]: developer manual for the i18n library
* [[Internationalization/obstacles|Obstacles]]: setbacks we have encountered

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

== Semester project ==

* [[User:leo| Leo Fellmann]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei|Hong Zhang]]
* [[User:Trosim|Martino Trosi]]
* Supervisor: [[User:Schoelle| Bernd Schoeller]]

== Old SA project team ==
* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization

2006-10-16T15:13:26Z

Leo:

[[Category:Projects]]
[[Category:Internationalization]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

===Brief history===

Orginally the internationalisation (i18n) project was started as a required project for an ETH Software Architecture course.
The result was less then perfect; pages referring to this first version have been given an 'SA' prefix.
Some members of this SA project team decided to rewrite the library as a semester project. Pages on the wiki not prefixed with 'SA' are either applicable to both or to the semester project.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=== Specific goals of the semester project ===

''to be completed''

=Milestones=

''add milestones of semesterproject''

==Mx: ??? ==
* Write a summary of how [[Internationalization/posix_locale|POSIX locale]] information is stored
* Write a summary of how [[Internationalization/nls_locale|NLS (Windows) locale]] infomation is stored
* Write a summary of how [[Internationalization/dotnet_locale|.NET locale]] information is stored
* Write a small summary of date and time classes in EiffelBase
* Examine the .ts file format, notably plural form handling
* Examine the .xliff file format, notably plural form handling (we did some of this already)
* Enter classes & features into EiffelStudio so we have a starting point and a BON diagram
* Sit down and think about the current class names. Some of them need improving.

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Documentation =

* [[Internationalization/user_guide|User guide]]: how to use the i18n library
* [[Internationalization/developer_guide|Developer guide]]: developer manual for the i18n library
* [[Internationalization/obstacles|Obstacles]]: setbacks we have encountered

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

== Semester project ==

* [[User:leo| Leo Fellmann]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei|Hong Zhang]]
* [[User:Trosim|Martino Trosi]]
* Supervisor: [[User:Schoelle| Bernd Schoeller]]

== Old SA project team ==
* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:Mingmei |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization/Developer guide

2006-10-16T15:12:08Z

Leo: added translation section

=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost classes, SYSTEM_LOCALES and HOST_LOCALE, are responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses SYSTEM_LOCALE and DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

TODO: expand? formatters?

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a SYSTEM_LOCALES object. This class acts as a layer between LOCALE_MANAGER and the actual implementation.
''[An entirely useless layer, actually. It needs removing, as design changes have badly reduced it's utility]''

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

The part of the library that provides translated strings is slightly more complicated. The strings come from a so-called data source (or datasource, depending on preference). The uri given to a LOCALE_MANAGER on creation is examined by a URI_PARSER, which decides what sort of data source this uri represents. It then creates an appropriate DATASOURCE_MANAGER* with this uri and returns it to the LOCALE_MANAGER.

From this point onwards the DATASOURCE_MANAGER* is responsible for the main operations involving translations: providing a list of locales for which a translation is present, and providing the translation in form of a DICTIONARY* for a given locale.
A DICTIONARY* is nothing more then a collection of translated strings, with functions to access them. There are several effective descendants, as the best way to store the strings may depend on several factors (singular/plural ration, data source itself, etc.). The LOCALE_MANAGER gets the relevant DICTIONARY* from the DATASOURCE_MANAGER* and passes it to the LOCALE on creation. The LOCALE can then retrieve translations.

===File data source ===

The file datasource works in the following way:
The FILE_MANAGER, an effective DATASOURCE_MANAGER*, has a chain-of-responsibility built from FILE_HANDLER*s.
There are two operations provided by this chain of responsibility: determining the locale of a file and providing a DICTIONARY* containing the strings from this file.
By using this chain and a list of file in the current directory, the FILE_MANAGER can list available locales and provide DICTIONARY* objects. The precise type of DICTIONARY* provided is dependant on the type of file.

Each FILE_HANDLER* works by using a FILE* object, which provides the actual parsing functionality for a given file type.
Currently the only supported file type is the .mo file format, so this is the only example I may provide.

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this), of having multiple .mo files for one locale, or of having one .mo file for multiple locales (for example: a fr.mo file could cover fr_FR, fr_CH and fr_CA, although this might not be appreciated by some users ;) )

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/Developer guide

2006-10-16T13:49:57Z

Leo: added formatting info section

=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously knows how to format things and finds translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost classes, SYSTEM_LOCALES and HOST_LOCALE, are responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them resembling a web drawn by an overcaffeinated spider.

Note: the 'I18N' prefix of class names is omitted in the text for clarity.

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses SYSTEM_LOCALE and DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

TODO: expand? formatters?

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

Most major operating systems have an API that provides localisation information. Often they also allow clients to format dates, times and values directly. We decided that instead of directly using the formatting functions of the operating system, we would write our own formatters in Eiffel. Retrieving the required information, however, still has to be done in C. Depending on the operating system, this is a more-or-less simple process.

The formatting information for a given locale is stored in objects of class LOCALE_INFO. Each LOCALE_INFO is initialized on creation with (what we think are sensible) default values, as not all platforms provide all the same information.

LOCALE_MANAGER is able to retrieve the LOCALE_ID of the default locale, filled LOCALE_INFOS and a list of locales with formatting information from a SYSTEM_LOCALES object. This class acts as a layer between LOCALE_MANAGER and the actual implementation.
''[An entirely useless layer, actually. It needs removing, as design changes have badly reduced it's utility]''

The deferred class HOST_LOCALE* specifies the interface for operating system-specific implementations, and the right effective class, HOST_LOCALE_IMP, is included in the system through a conditional statement in the .ecf platform. This class normally makes use of C externals to actually access the formatting information, although the .NET implementation is an exception. The main jobs that it has are: assembling a list of supported locales, creating, filling and returning a LOCALE_INFO for a given locale, and identifying the locale set as default in the operating system preferences.
Currently there are HOST_LOCALE_IMP classes for .NET, Windows, and what should be more or less POSIX - only, for now, tested under linux.

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective descendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Data sources==

===New data sources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible data source, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a data source that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this), of having multiple .mo files for one locale, or of having one .mo file for multiple locales (for example: a fr.mo file could cover fr_FR, fr_CH and fr_CA, although this might not be appreciated by some users ;) )

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new data source.

==New dictionaries==

New dictionaries might be required by new data sources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/Developer guide

2006-10-14T17:10:26Z

Leo: still need to add 2 sections, but initial draft largely finished

=General architecture of the i18n library=

==Where does the information come from?==

The i18n library must obviously know how to format things and find translations for many different locales. Translations are application-dependant and thus we only have to deal with them on an infrastructural basis - the actual information is supplied by the user.
However formatting information is not. Instead, we can fetch this from the operating system.

This leads us to divide the library into three main parts:
#A part which organises and provides translations from a user-supplied data source.
#A part which retrieves formatting information from the host operating system
#A part which provides an interface to the information

[[Image:i18n_overview.png|thumb|right|400px|General structure of the i18n library]]

An overview of the structure is provided to the right: the two central classes, LOCALE and LOCALE_MANAGER are the main interface classes. The rightmost classes, SYSTEM_LOCALES and HOST_LOCALE, are responsible for fetching the formatting information, and the leftmost class, DATASOURCE_MANAGER, must deal with finding the translation of strings.

In addition there are several classes that are used to encapsulate information, not shown on diagrams to avoid them ressembling a web drawn by an over-caffeinated spider.

Note: the 'I18N' prefix of class names is omitted here for clarity

==Interface==

The main two classes of the interface are, as has been previously stated, LOCALE and LOCALE_MANAGER.
LOCALE represents all operations associated with a given locale: formatting and translation.
This is the class that clients use to actually localise things, but all it does is provide wrapper functions: the translations are retrieved from a DICTIONARY (more on this later) provided to it on creation, and the formatting is done by specialised formatting classes (DATE_FORMATTER, VALUE_FORMATTER, STRING_FORMATTER and CURRENCY_FORMATTER) which are also operated with information passed in a LOCALE_INFO object to the LOCALE on creation.

Obviously it should not be the user's job to do all this initialisation. This is why there must be a class that is in charge of presenting the user with a choice of locales and giving the user a correctly initialised LOCALE for the locale ultimately chosen.
This class is LOCALE_MANAGER. A LOCALE_MANAGER uses SYSTEM_LOCALE and DATASOURCE_MANAGER to find out for which locales formatting information and/or translations are available and can provide the client with a list of supported locales.
A locale is identified by a LOCALE_ID object; this is not only used internally but also by the client when requesting a LOCALE object.

TODO: expand? formatters?

==Formatting information==

[[Image:i18n_locale_information.png|thumb|right|400px|Section of the i18n library that retrieves locale information]]

==Translations==

[[Image:i18n_translation.png|thumb|right|400px|Section of the i18n library that retrieves translations]]

=Possible expansion points=

We hope our library is reasonably extensible. In particular, we foresee the following areas of expansion:

==New file formats==

Currently we only support the .po/.mo file format. This is because we have limited time and resources and we also feel that the .mo file format is the best current choice, as it it provides plural form handling.
However, there are other file formats. Trolltech has their own format, there is a Solaris message catalog format, presumably some Windows formats, and OS X also has a native format.

In order to add support for one of these formats - or your own! - it's necessary to write both FILE* and FILE_HANDLER* implementations. Then the new effective decendant of FILE_HANDLER* must be added to the chain-of-responsibility (called ''chain'') in the ''make'' feature of FILE_MANAGER.

==Datasources==

===New datasources===

Currently we only have one implementation of DATASOURCE_MANAGER*. But maybe a file is not suited to everything.
A possible datasource, however far-fetched, might be a database: all strings could be fetched via queries.
Or maybe all strings could be fetched via SOAP or RPC from a remote machine, to ensure up-to-date translations.
More realistically one could certainly imagine a datasource that checks the locally-stored translations and fetches the latest version remotely if there has been changes.
The easiest way to do such things is of course to write a new effective descendant of DATASTRUCTURE*.
This may or may not require a new implementation of DICTIONARY* - for a system that fetches strings on.demand rather then loading them all at initialisation, a new DICTIONARY* would certainly be advisable!

To make the library know about a new DATASOURCE_MANAGER*, URI_PARSER must be told how to recognise an uri that requires it. It is advisable to choose a nice prefix.

===FILE_MANAGER===
Currently FILE_MANAGER has the simplistic policy of only examining files in the current directory and trusting their name. It is very well possible that there is a project policy of placing each locale in it's own directory (KDE does this), of having multiple .mo files for one locale, or of having one .mo file for multiple locales (for example: a fr.mo file could cover fr_FR, fr_CH and fr_CA, although this might not be appreciated by some users ;) )

A good place to implement such a project-dependant policy is a descendant of FILE_MANAGER, or an entirely new datasource.

==New dictionaries==

New dictionaries might be required by new datasources. Or maybe the translations used by your project can be stored in a more efficient way then the general case - one could imagine a dictionary that takes advantage of singular/plural distribution, or that is keyed to the way translations are stored in a particular file format.
To add a new dictionary, it's sufficient to write an implementation of DICTIONARY* and to make sure it's used.

Internationalization/User guide

2006-10-14T15:31:07Z

Leo:

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, which we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

====Formatting====
=====Interface=====
DATE_FORMATTER provides:
<code>[eiffel, N]
format_date(date:DATE):STRING_32
format_time(time: TIME): STRING_32
format_date_time(date_time:DATE_TIME):STRING_32
</code>

CURRENCY_FORMATTER provides:
<code>[eiffel, N]
format_currency (a_value: REAL_64): STRING_32
</code>

VALUE_FORMATTER provides:
<code>[eiffel, N]
format_integer_8 (a_integer_8: INTEGER_8): STRING_32
format_integer_16 (a_integer_16: INTEGER_16): STRING_32
format_integer_32 (a_integer_32: INTEGER_32): STRING_32
format_integer_64 (a_integer_64: INTEGER_64): STRING_32
format_real_32 (a_real_32: REAL_32): STRING_32
format_real_64 (a_real_64: REAL_64): STRING_32
</code>
=====Usage=====

The LOCALE class makes 3 formatters accessible to clients: a VALUE_FORMATTER, a DATE_FORMATTER and a CURRENCY_FORMATTER, exposed as features under the names value_formatter, date_formatter and currency_formatter respectively.
Using these formatters is fairly straightforward: you simply call the appropriate function for the type of object that you want to format.

======Date formatting======

The DATE_FORMATTER class can format EiffelTime DATE, TIME and DATE_TIME classes in a way appropriate to the locale. For example, to get a string representation of today's date in a given locale, you might write:

<code>[eiffel, n]
io.put_string(my_locale.format_date(create {DATE}.make_now))
</code>

Currently eras of non-gregorian calendars are not well supported.

======Value and currency formatting======

The VALUE_FORMATTER and CURRENCY_FORMATTER classes can format integers and reals according to the conventions of a given locale - number of digits after the decimal separator, the decimal separator itself, grouping of digits and so on.

Using them is just as easy as DATE_FORMATTER: just call the function appropriate to the type of object who's value you want to format.

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

TODO: add more details about clicky thing.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_manager.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/User guide

2006-10-14T15:29:29Z

Leo: added formatting

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, which we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

====Formatting====
=====Interface=====
DATE_FORMATTER provides:
<code>[eiffel, N]
format_date(date:DATE):STRING_32
format_time(time: TIME): STRING_32
format_date_time(date_time:DATE_TIME):STRING_32
</code>

CURRENCY_FORMATTER provides:
<code>[eiffel, N]
format_currency (a_value: REAL_64): STRING_32
</code>

VALUE_FORMATTER provides:
<code>[eiffel, N]
format_integer_8 (a_integer_8: INTEGER_8): STRING_32
format_integer_16 (a_integer_16: INTEGER_16): STRING_32
format_integer_32 (a_integer_32: INTEGER_32): STRING_32
format_integer_64 (a_integer_64: INTEGER_64): STRING_32
format_real_32 (a_real_32: REAL_32): STRING_32
format_real_64 (a_real_64: REAL_64): STRING_32
</code>
=====Usage=====

The LOCALE class makes 3 formatters accessible to clients: a VALUE_FORMATTER, a DATE_FORMATTER and a CURRENCY_FORMATTER, exposed as features under the names value_formatter, date_formatter and currency_formatter respectively.
Using these formatters is fairly straightforward: you simply call the appropriate function for the type of object that you want to format.

======Date formatting======

The DATE_FORMATTER class can format EiffelTime DATE, TIME and DATE_TIME classes in a way appropriate to the locale. For example, to get a string representation of today's date in a given locale, you might write:

<code>[eiffel, n]
io.put_string(my_locale.format_date(create {DATE}.make_now))
</code>

Currently eras of non-gregorian calendars are not well supported.

======Value and currency formatting======

The VALUE_FORMATTER and CURRENCY_FORMATTER classes can format integers and reals according to the conventions of a given locale - number of digits after the decimal separator, the decimal separator itself, grouping of digits and so on.

Using them is just as easy as DATE_FORMATTER: just call the function appropriate to the type of object who's value you want to format.

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

TODO: add more details about clicky thing.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_manager.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

File:I18n translation.png

2006-10-12T22:39:15Z

Leo: Structure of the part of the i18n that loads translations

Structure of the part of the i18n that loads translations

File:I18n locale information.png

2006-10-12T22:38:30Z

Leo: Structure of the part of the i28n library that deals with retrieving information from the OS

Structure of the part of the i28n library that deals with retrieving information from the OS

File:I18n overview.png

2006-10-12T22:37:37Z

Leo: overview of i18n library architecture

overview of i18n library architecture

Internationalization/Developer guide

2006-10-12T22:22:54Z

Leo: outline

=General architecture of the library=
=Possible expansion points=
==FILE_MANAGER==
==New file formats==
==New datasources==
==New datastructures==

Internationalization/User guide

2006-10-12T22:17:04Z

Leo:

Internationalization/User guide

2006-10-12T22:16:54Z

Leo:

User documentation for the i18n library

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

====Formatting====
=====Interface=====
TODO!
=====Usage=====
TODO!

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

TODO: add more details about clicky thing.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/User guide

2006-10-12T22:16:16Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

====Formatting====
=====Interface=====
TODO!
=====Usage=====
TODO!

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

TODO: add more details about clicky thing.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER looks somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/User guide

2006-10-12T22:15:50Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.

===Using your locale===

Now you've got a LOCALE. After the initial burst of euphoria has faded away, what can you do with it?

====String translation====
=====Interface=====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
=====Usage=====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

====Formatting====
=====Interface=====
TODO!
=====Usage=====
TODO!

==String extraction==

Somebody has to translate all these strings. Mostly, this isn't a programmer, so somehow you have to be able to give this translator a list of strings that you want translated.

We can extract these strings from your application fairly easily by simply looking at the arguments for each call to translate or translate_plural. By clicking on a handy button in EiffelStudio, these strings will be extracted and placed in a [http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#SEC9 .po file].

TODO: add more details about clicky thing.

A .po file is a reasonably widespread format for storing strings to be translated. There are several tools to aid translation of these files, such as [http://www.poedit.org/ poEdit] for Windows and [http://kbabel.kde.org/ KBabel] or [http://gtranslator.sourceforge.net/ gtranslator] for KDE and Gnome.
There are also many tools to convert .po files to other formats, such as the xml [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff xliff format].

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER look somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

How do you get these .mo files? Once your translator has finished translating a .po file, you can convert it into a .mo file by using the ''msgfmt'' tool, which is obtainable as part of the gettext package under unix and distributed with poEdit under Windows.
The resulting mo file should be named with the locale identifier of the locale it is intended for (zh_CN.mo or de_CH.mo, for example) and placed in the appropriate directory - this is to say, the one that you give to LOCALE_MANAGER as an uri.

The .mo file should then be seen and used by the i18n library.

Internationalization/User guide

2006-10-12T21:54:35Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you. With this LOCALE object you can do the really interesting things, like formatting dates and translating strings.

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.
===String translation===
====Interface====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
====Usage====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

===Formatting===

TODO!

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER look somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

Internationalization/User guide

2006-10-12T21:52:43Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you.

Here is how you can use LOCALE objects for internationalisation:

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, and normally this has two components: language code and country code.
For example, the US english locale has language code "en" and country code "US".
If you've found a locale id that you like in the list returned by available_locales, you can check exactly what is vailable for it by using
<code>[eiffel, N]
has_translations (a_locale_id: I18N_LOCALE_ID): BOOLEAN
has_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
</code>

You can then retrieve the corresponding LOCALE object by calling get_locale.
===String translation===
====Interface====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
====Usage====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

===Formatting===

TODO!

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER look somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

Internationalization/User guide

2006-10-12T21:45:03Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

''localisation'' is the process of adapting a piece of software to a specific place - the ''locale'', often expressed as a combination of language and country codes.

This normally means not only displaying strings in the appropriate language, but also adapting number formatting, date and time formatting etc. to use local conventions.
The i18n library provides formatting facilities for numbers, currency values and dates, and the ability to identify and load translated strings at run-time.

==Interface==

The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
LOCALE objects can't be created directly: one must go though the LOCALE_MANAGER class. A LOCALE_MANAGER finds out what information for which locales is available, and offers a list to chose from. It will then load the information for the chosen locale into a LOCALE object and give it to you.

Here is how you can use LOCALE objects for internationalisation:

===Choosing a locale===

First you must have a LOCALE_MANAGER. For details on creating them, please see the '''Datasources''' section.
If you just want to use whatever locale is the default on the user's machine, as in most cases, then it's easy to get a LOCALE object: just call get_system_locale.
<code>[eiffel, N]
my_locale := locale_mananger.get_system_locale
</code>

If you want a specific locale, it's going to be a bit more complicated.
A LOCALE_MANAGER knows what locales are available and exactly what information is available for a specific locale.
You can get a list of all locales that are available to some degree by calling the available_locales feature.
A locale is identified by a LOCALE_ID object, so

===String translation===
====Interface====
<code>[eiffel, N]
translate (original: STRING_GENERAL): STRING_32
translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
</code>
====Usage====
In naïvely written software, you can often spot things like
<code>[eiffel, N]
io.put_string("My hovercraft is full of eels")
</code>
We'll use this example to illustrate the use of the string translation features of the i18n library.

If, as above, there is just one constant string to translate, the solution is very easy: simply use the translate function.
The resulting code would look like this
<code>[eiffel, N]
io.put_string(my_locale.translate("My hovercraft is full of eels"))
</code>
If the translate function can't find a translation for this string it will simply return the original string - better then nothing!

But life is, of course, not always that simple. What if we have to deal with plurals? The "traditional" way of doing this is something like:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My hovercraft are full of eels")
end
</code>

This is not so easy to translate as the above. Why can't we just translate both strings?

Depending on the language, there may be up to 4 different types of plural forms, used in strange and exotic ways. Clearly, it is important to know exactly _how_ many hovercraft there are so that we can choose the right plural form. This can be done by the translate_plural function, whoch we can use in this way:
<code>[eiffel,n]
n := get_number_of_hovercraft
io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
</code>
This function will choose and return a translation in the correct plural form. If it can't find one, it will behave like translate and return either the original singular string or the original plural string, following English grammatical rules.

Often even the above is not enough. What if you want to tell the world exactly how many hovercraft you have? You might write something like this:
<code>[eiffel, N]
n := get_number_of_hovercraft
if n = 1 then
io.put_string("My hovercraft is full of eels")
else
io.put_string("My "+n.out+" hovercraft are full of eels")
end
</code>
How can translate_plural handle this? It needs some reinforcements: the solution is to also use ''string templates''.
This means that we can embed codes like "$1" in a string and replace them in the translation by the actual values.
Let's see how this works:
<code>[eiffel,n]
n := get_number_of_hovercraft
plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
io.put_string(my_locale.format_string(plural_string, [n]))
</code>
To replace the ''escape codes'', such as $1, $2, we use the function format_string. This replaces all the escape codes it finds by the values in a tuple that you give to it a an argument.

===Formatting===

TODO!

==Datasources==

The library has to load the translated strings from somewhere - sadly we can't do on the fly translation but if you can, please tell us!
Instead we load the strings from a datasource. This is appropriately generic: it could be anything, from a database to a system that queries a server via RPC or SOAP, but currently we only have one implementation: files. And in fact, we only support one type of file: the .mo file format.
The library can't guess the type of datasource you want to use, so you have to tell it when you create a LOCALE_MANAGER.
This is done via an ''uri''. Currently all uris are interpreted as directories where string catalog files may be found, and any .mo files in this directory will be used by the i18n library. This means that creating a LOCALE_MANAGER look somewhat like this:
<code>[eiffel, N]
create my_locale_mananger.make("/path/to/my/files")
</code>

===Mo files===

The mo file format is defined by the GNU [http://www.gnu.org/software/gettext/ gettext] library, a widely-used C library that allows localisation of text strings. We support UTF-8 encoded mo files.

Internationalization/User guide

2006-10-12T21:27:28Z

Leo:

Internationalization/User guide

2006-10-12T21:24:55Z

Leo:

Internationalization/User guide

2006-10-12T21:24:48Z

Leo:

Internationalization/User guide

2006-10-12T21:23:31Z

Leo:

Internationalization/User guide

2006-10-09T15:47:01Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

We divide this task into two parts:
# Loading translated strings from a message catalog - or in our terminology, from a 'datasource' (One can imagine various datasources, but currently the only supported one is a file).
# Formatting numbers, currency values and dates: this information can be fetched directly from the operating system.

==Interface==

===Locale===

===Locale Manager===

===Locale ID ===

===Putting it all together===

==Datasources==

===File===

====File format====

====File Manager====

Internationalization/User guide

2006-10-09T15:46:25Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

We divide this task into two parts:
# Loading translated strings from a message catalog - or in our terminology, from a 'datasource' (One can imagine various datasources, but currently the only supported one is a file). # Formatting numbers, currency values and dates: this information can be fetched directly from the operating system.

==Interface==

===Locale===

===Locale Manager===

===Locale ID ===

===Putting it all together===

==Datasources==

===File===

====File format====

====File Manager====

Internationalization/User guide

2006-10-09T15:45:25Z

Leo:

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

We divide this task into two parts:
# Loading translated strings from a message catalog - or in our terminology, from a 'datasource' (One can imagine various datasources, but currently the only supported one is a file).
## Formatting numbers, currency values and dates: this information can be fetched directly from the operating system.

==Interface==

===Locale===

===Locale Manager===

===Locale ID ===

===Putting it all together===

==Datasources==

===File===

====File format====

====File Manager====

Internationalization/User guide

2006-10-09T02:15:06Z

Leo: outline

=User documentation for the i18n library=

==Overview==

The [[i18n]] library is intended to enable localisation of Eiffel programs.

We divide this task into two parts:
# Loading translated strings from a message catalog - or in our terminology, from a 'datasource'.
One can imagine various datasources, but currently the only supported one is a file.
## Formatting numbers, currency values and dates.
This information can be fetched directly from the operating system.

==Interface==

===Locale===

===Locale Manager===

===Locale ID ===

===Putting it all together===

==Datasources==

===File===

====File format====

====File Manager====

Internationalization/User guide

2006-10-09T01:47:27Z

Leo:

Internationalization/file format

2006-09-04T08:15:10Z

Leo:

[[Category:Internationalization]]

==Summary==

A bref description of the most important file formats used for the translation of programs.

==PO Files==

===Format of PO files===

A PO file has an entry for each string that has to be translated. There are two kind of them, a "normal" one and one that involves plural forms.

====Normal entry====

Here is the general structure of a "normal" entry:

white-space
# translator-comments
#. extracted-comments
#: references...
#, flag...
msgid untranslated-string
msgstr translated-string

Where the ''translator-comments'' are created and maintained exclusively by the translator, this comments have some white space immediately following the #. The other comments are created by the program that created the PO file.
''References'' are space separated lists of locations (sourcefile:linenumber) specifying where the translation unit is found in a source file.
After the special comment "#," there can be some ''flags'', as ''fuzzy'' shows that the msgstr string might not be a correct translation, i.e. the translator is not sure of his work.
The 'untranslated-string' is the untranslated string as it appears in the original program source. The ''translated-string'' is (as the name suggests) the translated string, if there is no translation it is an empty string.

====Plural form entry====

white-space
# translator-comments
#. automatic-comments
#: reference...
#, flag...
msgid untranslated-string-singular
msgid_plural untranslated-string-plural
msgstr[0] translated-string-case-0
...
msgstr[N] translated-string-case-n

===Supported character encodings===

character encodings that can be used are limited to those supported by both GNU libc and GNU libiconv. These are: ASCII, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-13, ISO-8859-15, KOI8-R, KOI8-U, CP850, CP866, CP874, CP932, CP949, CP950, CP1250, CP1251, CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, GB2312, EUC-JP, EUC-KR, EUC-TW, BIG5, BIG5-HKSCS, GBK, GB18030, SHIFT_JIS, JOHAB, TIS-620, VISCII, UTF-8.

===Po Editors===

* poEdit
* KBabel
* Gtranslator
* LocFactoryEditor (XLIFF and PO editor for Mac OSX)

===Positive aspects===

* Powerful plural handling
* Format created for translation purpose
* Easy for humans to read
* Used by gettext, kbabel, rosetta and many other programs
* Support and elaboration tools for almost all plattforms

===Negative aspects===

* The PO file format does not provide a way of identifying the source and target language within a file. By GNU standards, GNU software is written in American English (en-US), and this is reflected in Gettext by only having support for Germanic plural forms in the source language. It is therefore recommended to set the source-language attribute to en-US by default.

==ts Files==

===Format of ts files===

The .ts file format is used Trolltech for the QT applications. They are XML conforming files. Here an example of a .ts file, generated by lupdate (a tool made by Trolltech that extracts translatable text from the C++ source code of the Qt application, see [[Internationalization/tool evaluation|here]] for further information):

<!DOCTYPE TS><TS>
<context>
<name>MyExample</name>
<message>
<source>i18n=Internationalization</source>
<translation type="unfinished"></translation>
</message>
</context>
</TS>

And after the translation (for example with Qt Linguist) it would look like this:

<!DOCTYPE TS><TS>
<context>
<name>MyExample</name>
<message>
<source>i18n=Internationalization</source>
<translation>i20e=Internazionalizzazione</translation>
</message>
</context>
</TS>

The .ts file is than converted to the .qm file format, a compact binary format that provides extremely fast lookups for translations, with a tool named lrelease.

The creation of .qm files can also be done with the GNU gettext tools: with "xgettext --qt" as string extractor for producing the .pot file. And then convert the translated file (.po) with the "msgfmt --qt" command for creating the .qm files.

=== ts Editors ===

*QT Linguistic

===Positive aspects===

* "full" support for unicode character encodings
* In trolltech's opinion it's a human readable text

===Negative aspects===

* QT's translation framework does not support plurals
* Qt message catalog format supports Unicode only in the translated strings, not in the untranslated strings

== xliff Files ==

===Format of XLIFF files===

XLIFF is the XML Localization Interchange File Format. It is intended to give any software provider a single interchange file format that can be understood by any localization provider.

You can find a XLIFF Tree Structure [http://www.oasis-open.org/committees/xliff/documents/xliff-specification.htm#AppTree here]

=== ts Editors ===

*[http://www.heartsome.net/EN/xlfedit.html heartsome]
*[https://open-language-tools.dev.java.net/editor/about-xliff-editor.html XLIFF Translation Editor]

===Positive aspects===

* OASIS standard

===Negative aspects===

* complicated plural form handling

==References==

* [http://www.gnu.org/software/gettext/manual/html_mono/gettext.html Gettext manual (for PO files)]
* [http://librarian.launchpad.net/2395419/it.po Example of a PO file (from rosetta)]
* [http://news.com.com/2100-1013_3-5146581.html Microsoft and XML]
* [http://en.wikipedia.org/wiki/XML#Quick_syntax_tour XML syntax description on Wikipedia]
* [http://doc.trolltech.com/4.1/i18n.html Trolltech i18n]
* [http://translate.sourceforge.net/wiki/ open source i18n and l10n project]

User talk:Manus

2006-09-04T08:13:05Z

Leo:

==Vandalism==

Hi Manus, I wanted to inform you that there are two users that did some vandalism:
* [[User:Ceas]] did [http://eiffelsoftware.origo.ethz.ch/index.php?title=Main_Page&diff=next&oldid=4215 this]
* [[User:Moralest]] did [http://eiffelsoftware.origo.ethz.ch/index.php?title=Main_Page&diff=4442&oldid=4401 this]
I propose to block their username... I've already removed the changes. [[User:Etienner|'''E''''''T''''''N''']] [[User talk:Etienner|'''talk''']]

: Not worth it; those are certainlyjust bots, probably run from some zombie. [[User:Leo|Leo]] 10:13, 4 September 2006 (CEST)

Internationalization

2006-08-16T00:31:33Z

Leo:

[[Category:Projects]]
[[Category:Internationalization]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

===Brief history===

Orginally the internationalisation (i18n) project was started as a required project for an ETH Software Architecture course.
The result was less then perfect; pages referring to this first version have been given an 'SA' prefix.
Some members of this SA project team decided to rewrite the library as a semester project. Pages on the wiki not prefixed with 'SA' are either applicable to both or to the semester project.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=== Specific goals of the semester project ===

''to be completed''

=Milestones=

''add milestones of semesterproject''

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Documentation =

* [[Internationalization/developer_manual|Developer manual]]: developer manual for the i18n library
* [[Internationalization/obstacles|Obstacles]]: setbacks we have encountered

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

== Semester project ==

* [[User:leo| Leo Fellmann]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:hong |Hong Zhang]]
* [[User:Trosim |Martino Trosi]]
* Supervisor: [[User:Schoelle| Bernd Schoeller]]

== Old SA project team ==
* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:hong |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization SA project

2006-08-16T00:26:16Z

Leo:

[[Category:Projects]]
[[Category:Internationalization SA project]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=Milestones=

==M2: May 5 ==
* [[Internationalization/feasibility|feasibility]]: look at string classes (unicode and not) and how strings are used in EiffelStudio (creation, composition) ''(Ivano, Carlo, Leo, Hong)''
* [[Internationalization/file_format|file format]]: compare existing file formats for dictionaries ''(Etienne, Andreas)''
* [[Internationalization/tool_evaluation|tool evaluation]]: list and compare existing translation tools ''(Christian, Martino)''

==M3: June 13 ==
* write an initial .po to start translating and have a .mo for testing ''(Leo, Carlo)''
* [[Internationalization/mo parser|mo parser]]: extract translated strings from .mo files ''([[User:etienner|Etienne]], [[User:Trosim|Martino]])''
* [[Internationalization/translation function|translation function]]: map hard-coded strings to translated strings ''(Martino)''
** find a solution with templates
** globality: how to implement, the object should be shared between all modules (see [[Internationalization/class_structure|class structure]])
** find out how to use plurals (see [[Internationalization/plural_forms|plural forms]])
* Test unicode support in Vision2. [See test application in the [https://eiffelsoftware.origo.ethz.ch/svn/es/branches/soft-arch/Src/library/i18n/example/ SVN repository]]
* compile a [[Internationalization/l10n_features|list of basic features]] to provide (e.g. date/time format, system locale) ''[deferred]''

==M4: June 28 ==
* internationalization of EiffelStudio: surround strings with our functions
* [[Internationalization/translation|translation]] of EiffelStudio in some languages, for demo purposes (Italian, German, Chinese, ...) (see [http://slhk.ath.cx/projects/estudio/ pootle] ''Note: this is dead now -Leo'')
* [[Internationalization/code_parser|code parser]]: extract strings to be translated from source code and generate .pot file ''(Leo)''
* language selection: add an entry in the preferences system
* create a function to detect current environment language and settings (aka [[Internationalization/locale|locale]])

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Possible future developments =

* collaborate with the [[ESWizard]] team. Create wizards for programs with translation facilities.

= Documentation =

* [[Internationalization/requirements_specification|Requirements specification]]
* [[Internationalization/SA_developer_manual|Developer manual]]
* [[Internationalization/obstacles|Obstacles]]: why can't achieve all of our goals

= l10n: completed and on the work =

{| border="0" cellspacing="3" cellpadding="5" align="center"
!'''Language'''
!'''Status'''
|-
|Arabic
|Active
|-
|Chinese
|Active
|-
|Italian
|Active
|-
|Rhaeto-Romanic
|Active - Ready for use
|}

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:hong |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization/class structure

2006-08-16T00:24:23Z

Leo:

[[Category:Internationalization]]

''TODO: upload semesterproject UML diagam''

Internationalization/developer manual

2006-08-16T00:23:46Z

Leo:

[[Category:Internationalization]]

{{Warning|This is the developer manual for the i18n library developed as a Software Architecture 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

2006-08-16T00:22:18Z

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

[[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/class structure

2006-08-16T00:21:12Z

Leo:

[[Category:Internationalization SA project]]

''TODO: upload semesterproject UML diagam''

Internationalization/SA class structure

2006-08-16T00:20:27Z

Leo:

[[Category:Internationalization SA project]]

== Class structure ==

[[Image:Internationalization-ClassDiagram.png|Class Diagram]]

== Class description ==

{{Warning|The information below is not up-to-date, revision coming soon.}}

That's the actual structure of the whole thing:

SHARED_I18N_LOCALIZATOR => I18N_LOCALIZATOR => I18N_TEMPLATE_FORMATTER, (I18N_DATASTRUCTURE => I18N_MO_PARSER, I18N_PLURAL_FORMS)
::^
::|
CLASS_TO_LOCALIZE

The CLASS_TO_LOCALIZE simply inherits from our SHARED_I18N_LOCALIZATOR, which only purpose is to return always the same "localizator: I18N_LOCALIZATOR".

This class will in turn ask the archive for the translated strings and then pass it, along with all the arguments, to the template formatter, which will produce the final displayable string.

The datastructure will use the mo_parser for the initial filling of the datastructure (proposal: do it incrementally); the plural forms resolver will be used to find out which plural form should be used.

All this structure is already in place; we don't know yet how to open the right file, should be implemented by an environment variable or for example with a drop-down menu in the configuration dialog?

SHARED_I18N_LOCALIZATOR

* translator: I18N_LOCALIZATOR
* i18n(string): STRING
* i18n_comp(string, args): STRING (or what you want)
i18n (i18n_pl) and i18n_comp (i18n_comp_pl) are interfaces to the translator

I18N_LOCALIZATOR
* archive: I18N_DATASTRUCTURE
* ask(string): STRING (simple interface to ask the archive)
* solve_template(string, args): STRING (function that compose a string from template+arguments)

I18N_DATASCTRUCTURE
* mo_parser: I18N_MO_PARSER
* load(n) (interface to the parser)
* translate(STRING): STRING (interface to the I18N_LOCALIZATOR)
* data_structure: HASH|ARRAY (where the strings are effectively stored)

I18N_MO_PARSER
* open(file)
* load(n): STRING
* load_translated(n): STRING
* load_hash_entry(n): STRING

I18N_PLURAL_FORMS (more on this [[Internationalization/plural_forms|here]])
* get_plural_form(n): INTEGER (interface to the datastructure)

I18N_TEMPLATE_FORMATTER
* solve_template(a_template: STRING_32; a_args: TUPLE): STRING_32 (interface to the localizator)

Internationalization/SA project milestones

2006-08-16T00:18:56Z

Leo:

[[Category:Internationalization SA project]]

=Milestones=

==M2: May 5 ==
* [[Internationalization/feasibility|feasibility]]: look at string classes (unicode and not) and how strings are used in EiffelStudio (creation, composition) ''(Ivano, Carlo, Leo, Hong)''
* [[Internationalization/file_format|file format]]: compare existing file formats for dictionaries ''(Etienne, Andreas)''
* [[Internationalization/tool_evaluation|tool evaluation]]: list and compare existing translation tools ''(Christian, Martino)''

==M3: June 13 ==
* write an initial .po to start translating and have a .mo for testing ''(Leo, Carlo)''
* [[Internationalization/mo parser|mo parser]]: extract translated strings from .mo files ''([[User:etienner|Etienne]], [[User:Trosim|Martino]])''
* [[Internationalization/translation function|translation function]]: map hard-coded strings to translated strings ''(Martino)''
** find a solution with templates
** globality: how to implement, the object should be shared between all modules (see [[Internationalization/class_structure|class structure]])
** find out how to use plurals (see [[Internationalization/plural_forms|plural forms]])
* Test unicode support in Vision2. [See test application in the [https://eiffelsoftware.origo.ethz.ch/svn/es/branches/soft-arch/Src/library/i18n/example/ SVN repository]]
* compile a [[Internationalization/l10n_features|list of basic features]] to provide (e.g. date/time format, system locale) ''[deferred]''

==M4: June 28 ==
* internationalization of EiffelStudio: surround strings with our functions
* [[Internationalization/translation|translation]] of EiffelStudio in some languages, for demo purposes (Italian, German, Chinese, ...) (see [http://slhk.ath.cx/projects/estudio/ pootle])
* [[Internationalization/code_parser|code parser]]: extract strings to be translated from source code and generate .pot file ''(Leo)''
* language selection: add an entry in the preferences system
* create a function to detect current environment language and settings (aka [[Internationalization/locale|locale]])

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

Internationalization SA project

2006-08-16T00:18:45Z

Leo:

[[Category:Projects]]
[[Category:Internationalization SA project]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=Milestones=

==M2: May 5 ==
* [[Internationalization/feasibility|feasibility]]: look at string classes (unicode and not) and how strings are used in EiffelStudio (creation, composition) ''(Ivano, Carlo, Leo, Hong)''
* [[Internationalization/file_format|file format]]: compare existing file formats for dictionaries ''(Etienne, Andreas)''
* [[Internationalization/tool_evaluation|tool evaluation]]: list and compare existing translation tools ''(Christian, Martino)''

==M3: June 13 ==
* write an initial .po to start translating and have a .mo for testing ''(Leo, Carlo)''
* [[Internationalization/mo parser|mo parser]]: extract translated strings from .mo files ''([[User:etienner|Etienne]], [[User:Trosim|Martino]])''
* [[Internationalization/translation function|translation function]]: map hard-coded strings to translated strings ''(Martino)''
** find a solution with templates
** globality: how to implement, the object should be shared between all modules (see [[Internationalization/class_structure|class structure]])
** find out how to use plurals (see [[Internationalization/plural_forms|plural forms]])
* Test unicode support in Vision2. [See test application in the [https://eiffelsoftware.origo.ethz.ch/svn/es/branches/soft-arch/Src/library/i18n/example/ SVN repository]]
* compile a [[Internationalization/l10n_features|list of basic features]] to provide (e.g. date/time format, system locale) ''[deferred]''

==M4: June 28 ==
* internationalization of EiffelStudio: surround strings with our functions
* [[Internationalization/translation|translation]] of EiffelStudio in some languages, for demo purposes (Italian, German, Chinese, ...) (see [http://slhk.ath.cx/projects/estudio/ pootle])
* [[Internationalization/code_parser|code parser]]: extract strings to be translated from source code and generate .pot file ''(Leo)''
* language selection: add an entry in the preferences system
* create a function to detect current environment language and settings (aka [[Internationalization/locale|locale]])

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Possible future developments =

* collaborate with the [[ESWizard]] team. Create wizards for programs with translation facilities.

= Documentation =

* [[Internationalization/requirements_specification|Requirements specification]]
* [[Internationalization/developer_manual|Developer manual]]
* [[Internationalization/obstacles|Obstacles]]: why can't achieve all of our goals

= l10n: completed and on the work =

{| border="0" cellspacing="3" cellpadding="5" align="center"
!'''Language'''
!'''Status'''
|-
|Arabic
|Active
|-
|Chinese
|Active
|-
|Italian
|Active
|-
|Rhaeto-Romanic
|Active - Ready for use
|}

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:hong |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]

Internationalization

2006-08-16T00:17:45Z

Leo: removed some sa-specific stuff

Internationalization SA project

2006-08-16T00:14:22Z

Leo: old Internationalization page - copy/paste move because I don't have proper move permissions

[[Category:Projects]]
[[Category:Internationalization]]
[[Category:Internationalization SA project]]
[[Image:ebabylon.png|right|frame| Our Eiffel Tower of Babylon]]

=Overview=

''"Many [people] would simply love seeing their computer screen showing a lot less of English, and far more of their own language."'' -- gettext doc

Our aim is not only to provide a framework to ease the translation of Eiffel-written applications, allowing the user to chose his/her preferred language at runtime, but also to let the developer access information and formats based on users' locale.

==What is internationalisation?==

The first thing that comes to mind is translation. But internationalisation isn't restricted to enabling translation: it includes making it possible to localise notations (time, date, numbers), measures, paper size, and much more.

==What should we achieve?==
*Applications should be able to load localized strings at runtime and be provided with localized format strings (e.g date format).
*Developers can use tools that automagically extract strings from source code and can try to get them translated in a file to distribute along with the application.
*Users will still be unhappy and get depressed ''but in their own language'', which we can all agree is a significant step forward.

=Milestones=

==M2: May 5 ==
* [[Internationalization/feasibility|feasibility]]: look at string classes (unicode and not) and how strings are used in EiffelStudio (creation, composition) ''(Ivano, Carlo, Leo, Hong)''
* [[Internationalization/file_format|file format]]: compare existing file formats for dictionaries ''(Etienne, Andreas)''
* [[Internationalization/tool_evaluation|tool evaluation]]: list and compare existing translation tools ''(Christian, Martino)''

==M3: June 13 ==
* write an initial .po to start translating and have a .mo for testing ''(Leo, Carlo)''
* [[Internationalization/mo parser|mo parser]]: extract translated strings from .mo files ''([[User:etienner|Etienne]], [[User:Trosim|Martino]])''
* [[Internationalization/translation function|translation function]]: map hard-coded strings to translated strings ''(Martino)''
** find a solution with templates
** globality: how to implement, the object should be shared between all modules (see [[Internationalization/class_structure|class structure]])
** find out how to use plurals (see [[Internationalization/plural_forms|plural forms]])
* Test unicode support in Vision2. [See test application in the [https://eiffelsoftware.origo.ethz.ch/svn/es/branches/soft-arch/Src/library/i18n/example/ SVN repository]]
* compile a [[Internationalization/l10n_features|list of basic features]] to provide (e.g. date/time format, system locale) ''[deferred]''

==M4: June 28 ==
* internationalization of EiffelStudio: surround strings with our functions
* [[Internationalization/translation|translation]] of EiffelStudio in some languages, for demo purposes (Italian, German, Chinese, ...) (see [http://slhk.ath.cx/projects/estudio/ pootle])
* [[Internationalization/code_parser|code parser]]: extract strings to be translated from source code and generate .pot file ''(Leo)''
* language selection: add an entry in the preferences system
* create a function to detect current environment language and settings (aka [[Internationalization/locale|locale]])

==M5: July ?? ==
* Refactoring of whole library
* Use our library for EiffelStudio
* Clean up Wiki and improve Developer manual
* Add support for other aspects of localisation - dates, number format etc. ''(possibly we can defer this a bit)''
** Compile a [[Internationalization/l10n_features | list of basic features]] to provide (e.g. date/time format, system locale) ''(deferred from M3)''

= Possible future developments =

* collaborate with the [[ESWizard]] team. Create wizards for programs with translation facilities.

= Documentation =

* [[Internationalization/requirements_specification|Requirements specification]]
* [[Internationalization/developer_manual|Developer manual]]
* [[Internationalization/obstacles|Obstacles]]: why can't achieve all of our goals

= l10n: completed and on the work =

{| border="0" cellspacing="3" cellpadding="5" align="center"
!'''Language'''
!'''Status'''
|-
|Arabic
|Active
|-
|Chinese
|Active
|-
|Italian
|Active
|-
|Rhaeto-Romanic
|Active - Ready for use
|}

=Relevant Links=
[http://www.debian.org/doc/manuals/intro-i18n/ Introduction to i18n]

==What other people have done==
[http://doc.trolltech.com/4.1/i18n.html internationalisation with QT]

[http://oss.erdfunkstelle.de/kde-i18n/tiki-index.php?page=miniHowtoGui howto for internationalisation of KDE programs ]

[http://l10n.kde.org/docs/translation-howto/ another KDE howto (doesn't Gnome do any internationalisation?)]

=Team=

Everyone interested in this project is welcome to [http://origo.ethz.ch/cgi-bin/mailman/listinfo/es-i18n join our mailinglist] es-i18n@origo.ethz.ch

* Project Leader: [[User:Carlo|Carlo Vanini]]
* [[User:leo| Leo Fellmann]]
* [[User:kiwi| Ivano Somaini]]
* [[User:murbi|Andreas Murbach]]
* [[User:etienner|Etienne Reichenbach]]
* [[User:hong |Hong Zhang]]
* [[User:cconti | Christian Conti]]
* [[User:Trosim |Martino Trosi]]
* [[User:Schoelle| Bernd Schoeller]]