Changes between Version 9 and Version 10 of CookBook/PluginL10N

Timestamp:

May 9, 2010, 4:01:04 PM (14 years ago)

Author:

Christian Boos

Comment:

reviewed first half of the page

CookBook/PluginL10N

@@ -10 +10 @@
 
 == i18n, l10n, ... help! ==
-In short '''i18n''' stands for '''`i`'''`nternationalizatio`'''`n`''' (count 18 more chars between i and n) and is defined as software design for programs with translation support. '''`l`'''`ocalisatio`'''`n`''' that is abbreviated as '''l10n''' could be seen as a follow-up process providing data for one or more locales. It is taking care of feature differences between the original/default (that is English is most cases including Trac) and a given locale as well. Such features are i.e. sentence structure including punctuation and formatting of numbers, date/time strings, and currencies. Once you did some ground work at the source (i18n), most remaining is proper translation work (l10n) putting more or less effort in preserving the sense of the original while looking as native locale as possible.^1^
-
-'''NLS''' (National Language Support or Native Language Support) is meant to be the sum of both. And there are more related terms that we could safely skip for now.^1, 2^
+In short '''i18n''' stands for '''`i`'''`nternationalizatio`'''`n`''' (count 18 more chars between i and n) and is defined as software design for programs with translation support. '''`l`'''`ocalisatio`'''`n`''' that is abbreviated as '''l10n''' could be seen as a follow-up process providing data for one or more locales. It is taking care of feature differences between the original/default (that is English is most cases including Trac) and a given locale as well. Such features are i.e. sentence structure including punctuation and formatting of numbers, date/time strings, and currencies. Once you did some ground work at the source (i18n), most remaining is proper translation work (l10n) putting more or less effort in preserving the sense of the original while looking as native locale as possible.^[#a1 1]^
+
+'''NLS''' (National Language Support or Native Language Support) is meant to be the sum of both. And there are more related terms that we could safely skip for now.^[#a1 1], [#a2 2]^
 
 == Background and concept of i18n/l10n support for Trac plugins ==
 It begun with adding Babel to Trac. Some plugin maintainers created their own translation module inside each plugin separately. Growing amount of code redundancy and possibility of error within imperfect copies and variants of a translation module all that was certainly not a desirable situation. And Trac core maintainers took responsibility with adding functions dedicated to i18n/l10n support for Trac plugins.
 
-The evolution of this functions has been documented in [comment:11:ticket:7497 ticket 7497]. The final implementation as mentioned there in [comment:12:ticket:7497 comment 12] was introduced to Trac trunk in [changeset: changeset r7705] and finally done with [changeset: changeset r7714].
+The evolution of this functions has been documented in [comment:11:ticket:7497 ticket 7497]. The final implementation as mentioned there in [comment:12:ticket:7497 comment 12] was introduced to Trac trunk in changeset r7705 and finally done with changeset r7714.
 
 Now adding the needed i18n/l10n helper functions is done by importing a set of functions from `trac/util/translation.py` and providing proper configuration for an additional translation layer ('domain') inside the plugin code. On plugin initialization the dedicated translation domain is created as well and corresponding catalog files holding translated messages are loaded into it. Whenever a translatable text is encountered during runtime inside plugin's code, i18n/l10n helper functions will try to get the corresponding translation from the message catalog of plugin's domain and fall back silently to Trac's main message catalog, if needed.
 
+//
 Both searches take the locale setting as a second request argument. Valid settings are a combination of language and country code, often extended further by the character encoding used, i.e. to read like ‘de_DE.UTF-8’. The encoding is of special relevance for languages that had an older encoding per default that was not sufficient for all common chars used by native speakers of that language. 'C' is a special locale code since it disables all translations and programs use English texts as required by POSIX standard. Character encoding is highly dependent on the underlying operation system then.^3^
+//
+ I'm not sure to what the above refers. Which search? What locale argument? 
+ I don't think the character encoding plays any role here (we deal with unicode internally,
+ catalogs themselves are always encoded in UTF-8) - cboos
 
 First matching translation will replace the default text what by gettext convention is the same as the msgid, that is used, if all attempts fail to find an exact matching translation.
@@ -31 +36 @@
 ==== Import i18n/l10n helper programs ====
 For a '''fictional plugin 'foo' ''' just add
-{{{
+{{{#!python
 from trac.util.translation import domain_functions
 
@@ -38 +43 @@
 }}}
 at the beginning of the main python script file.
+  // TODO  I think I'll change that to: //
+{{{#!python
+from trac.util.translation import domain_functions
+
+_, tag_, N_, add_domain = domain_functions('foo', ('_', 'tag_', 'N_', 'add_domain'))
+}}}
+ //FIXME give the list of available domain functions//
 
 To bring in the compiled message catalog for actually using plugin's message catalogs you'll have to extend the `__init__` function of plugins main class as well. This could be done like this:
-{{{
+{{{#!python
     def __init__(self):
-        self._version = None
-        self.ui = None
         # bind the 'foo' catalog to the specified locale directory
         locale_dir = pkg_resources.resource_filename(__name__, 'locale')
@@ -50 +60 @@
 assuming that folder `locale` will reside in `./foo/locale/` within the directory structure (as observable inside the Python egg after packaging).
 
-[FIXME: explain what _version and ui are used for or leave them out, if unnecessary here]
-
 If you didn't have it in the source by now, add another import statement
-{{{
+{{{#!python
 import pkg_resources
 }}}
@@ -59 +67 @@
 
 The i18n/l10n helper programs are available inside the plugin now, but if the plugin code contains several python script files and you encounter text for translation in one of them too, you need to import the functions from the main script, say it's name is `api.py`, there:
-{{{
+{{{#!python
 from api import _, tag_, N_
+}}}
+{{{#!comment
+resume review here...
 }}}
 
@@ -183 +194 @@
 == Related resources ==
 
-^1^ http://en.wikipedia.org/wiki/Internationalization_and_localization - Internationalization and localization[[BR]]
-^2^ http://en.wikipedia.org/w/index.php?title=Multilingualism&section=18 - Multilingualism in computing[[BR]]
-^3^ http://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names - GNU 'gettext' utilities: Locale Names[[BR]]
-^4^ http://www.gnu.org/software/gettext/manual/gettext.html#Editing - GNU 'gettext' utilities: Editing PO Files[[BR]]
-^5^ http://techbase.kde.org/Localization/Concepts/PO_Odyssey - PO Odyssey in '!Localization/Concepts' section of KDE !TechBase
+[=#a1 ^1^] http://en.wikipedia.org/wiki/Internationalization_and_localization - Internationalization and localization[[BR]]
+[=#a2 ^2^] http://en.wikipedia.org/w/index.php?title=Multilingualism&section=18 - Multilingualism in computing[[BR]]
+[=#a3 ^3^] http://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names - GNU 'gettext' utilities: Locale Names[[BR]]
+[=#a4 ^4^] http://www.gnu.org/software/gettext/manual/gettext.html#Editing - GNU 'gettext' utilities: Editing PO Files[[BR]]
+[=#a5 ^5^] http://techbase.kde.org/Localization/Concepts/PO_Odyssey - PO Odyssey in '!Localization/Concepts' section of KDE !TechBase