Internationalization/User guide - Revision history

Peter gummer: /* Interface */

2007-04-05T10:56:53Z

‎Interface

Manus at 19:34, 31 October 2006

2006-10-31T19:34:26Z

Manus at 19:33, 31 October 2006

2006-10-31T19:33:20Z

Manus at 19:32, 31 October 2006

2006-10-31T19:32:59Z

Leo at 11:42, 24 October 2006

2006-10-24T11:42:37Z

Leo: update

2006-10-21T23:48:06Z

update

Leo at 15:31, 14 October 2006

2006-10-14T15:31:07Z

Leo: added formatting

2006-10-14T15:29:29Z

added formatting

Etienner: /* Usage */ small correction

2006-10-14T06:33:04Z

‎Usage: small correction

Leo at 22:17, 12 October 2006

2006-10-12T22:17:04Z

@@ Line 11: / Line 11: @@
 ==Interface==
-The library provides most of it's services through one class: LOCALE. This presents all formatting and translation facilities for a given locale.
+The library provides most of its 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.

← Older revision		Revision as of 19:34, 31 October 2006
Line 1:		Line 1:
−	~~[[Category:Projects]]~~
	[[Category:Internationalization]]		[[Category:Internationalization]]
	==Overview==		==Overview==

← Older revision		Revision as of 19:33, 31 October 2006
Line 1:		Line 1:
	[[Category:Projects]]		[[Category:Projects]]
		+	[[Category:Internationalization]]
	==Overview==		==Overview==

← Older revision		Revision as of 19:32, 31 October 2006
Line 1:		Line 1:
		+	[[Category:Projects]]
	==Overview==		==Overview==

@@ Line 16: / Line 16: @@
 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.
+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.get_system_locale
+my_locale := locale_mananger.default_locale
 </code>
@@ Line 35: / Line 35: @@
 (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.
+You can then retrieve the corresponding LOCALE object by calling locale_with_id, providing the desired LOCALE_ID.
@@ Line 45: / Line 45: @@
 =====Interface=====
 <code>[eiffel, N]
-translate (original: STRING_GENERAL): STRING_32
+translated (original: STRING_GENERAL): STRING_32
-translate_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
+translated_plural (original_singular, original_plural: STRING_GENERAL; plural_form : INTEGER): STRING_32
-format_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
+formatted_string (original: STRING_GENERAL; token_values: TUPLE[STRING_GENERAL]): STRING_32
 </code>
 =====Usage=====
@@ Line 59: / Line 59: @@
 The resulting code would look like this
 <code>[eiffel, N]
-io.put_string(my_locale.translate("My hovercraft is full of eels"))
+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!
@@ Line 65: / Line 65: @@
 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
+n := number_of_hovercraft
 if n = 1 then
 	io.put_string("My hovercraft is full of eels")
@@ Line 77: / Line 77: @@
 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
+n := number_of_hovercraft
-io.put_string(my_locale.translate_plural("My hovercraft is full of eels","My hovercraft are full of eels",n))
+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.
@@ Line 84: / Line 84: @@
 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
+n := number_of_hovercraft
 if n = 1 then
 	io.put_string("My hovercraft is full of eels")
@@ Line 95: / Line 95: @@
 Let's see how this works:
 <code>[eiffel,n]
-n := get_number_of_hovercraft
+n := number_of_hovercraft
-plural_string := my_locale.translate_plural("My hovercraft is full of eels","My $1 hovercraft are full of eels",n)
+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.format_string(plural_string, [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.
@@ Line 106: / Line 106: @@
 <code>[eiffel, N]
-n := get_number_of_eels
+n := number_of_eels
-io.put_string(my_locale.translate("My hovercraft has "+n.out+"eels"))
+io.put_string(my_locale.translated("My hovercraft has "+n.out+"eels"))
 </code>
@@ Line 120: / Line 120: @@
 DATE_FORMATTER provides:
 <code>[eiffel, N]
-format_date(date:DATE):STRING_32
+formatted_date(date:DATE):STRING_32
-format_time(time: TIME): STRING_32
+formatted_time(time: TIME): STRING_32
-format_date_time(date_time:DATE_TIME):STRING_32
+formatted_date_time(date_time:DATE_TIME):STRING_32
 </code>
 CURRENCY_FORMATTER provides:
 <code>[eiffel, N]
-format_currency (a_value: REAL_64): STRING_32
+formatted_currency (a_value: REAL_64): STRING_32
 </code>
 VALUE_FORMATTER provides:
 <code>[eiffel, N]
-format_integer_8 (a_integer_8: INTEGER_8): STRING_32
+formatted_integer_8 (a_integer_8: INTEGER_8): STRING_32
-format_integer_16 (a_integer_16: INTEGER_16): STRING_32
+formatted_integer_16 (a_integer_16: INTEGER_16): STRING_32
-format_integer_32 (a_integer_32: INTEGER_32): STRING_32
+formatted_integer_32 (a_integer_32: INTEGER_32): STRING_32
-format_integer_64 (a_integer_64: INTEGER_64): STRING_32
+formatted_integer_64 (a_integer_64: INTEGER_64): STRING_32
-format_real_32 (a_real_32: REAL_32): STRING_32
+formatted_real_32 (a_real_32: REAL_32): STRING_32
-format_real_64 (a_real_64: REAL_64): STRING_32
+formatted_real_64 (a_real_64: REAL_64): STRING_32
 </code>
 =====Usage=====
@@ Line 149: / Line 149: @@
 <code>[eiffel, n]
-io.put_string(my_locale.format_date(create {DATE}.make_now))
+io.put_string(my_locale.formatted_date(create {DATE}.make_now))
 </code>

@@ Line 26: / Line 26: @@
 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
+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_formatting_info (a_locale_id: I18N_LOCALE_ID): BOOLEAN
 </code>
 You can then retrieve the corresponding LOCALE object by calling get_locale.
@@ Line 97: / Line 100: @@
 </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====
@@ Line 148: / Line 166: @@
 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.
+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.
 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.
@@ Line 168: / Line 187: @@
 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 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.

@@ Line 124: / Line 124: @@
 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.
+Using these formatters is fairly straightforward: you simply call the appropriate function for  the type of object that you want to format.
 ======Date formatting======

@@ Line 1: / Line 1: @@
 ==Overview==
@@ Line 101: / Line 100: @@
 ====Formatting====
 =====Interface=====
-TODO!
+DATE_FORMATTER provides:
 =====Usage=====
-TODO!
 ==String extraction==
@@ Line 123: / Line 160: @@
 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")
+create my_locale_manager.make("/path/to/my/files")
 </code>

← Older revision		Revision as of 22:17, 12 October 2006
Line 1:		Line 1:
−	~~User documentation for the i18n library~~

	==Overview==		==Overview==