Edgewall Software

Changes between Version 30 and Version 31 of CookBook/PluginL10N


Ignore:
Timestamp:
Feb 14, 2023, 2:06:13 PM (15 months ago)
Author:
figaro
Comment:

Cosmetic changes, needs more work notably with respect to Jinja templating

Legend:

Unmodified
Added
Removed
Modified

  • CookBook/PluginL10N

    v30 v31  
    33
    44== Intro and Motivation ==
    5 If you want to learn about translation for a plugin, that as you know already provides one/several message catalog/s, the section '[#Dotranslatorswork Do translators work]' and following parts are for you.
    6 
    7 Ultimately, all plugin maintainers and developers in general, who are facing requests and are willing to take care for growing demand of their plugin to speak same (foreign) language(s) as Trac >= 0.12 should, just read on.
     5If you want to learn about translation for a plugin that already has translated end-user display strings, then the section '[#Dotranslatorswork Do translators work]' and following parts will be useful.
    86
    97=== i18n, l10n introduction
    10 '''i18n''' stands for '''`i`'''`nternationalizatio`'''`n`''' (count 18 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 in most cases including Trac) and a given locale as well. Such features are eg sentence structure, including punctuation and formatting of numbers, date/time strings and currencies. Once you did some ground work at the source (i18n), what's remaining is proper translation work (l10n), preserving the meaning of the original while looking as native locale as possible.^[#a1 1]^
     8'''i18n''' stands for '''`i`'''`nternationalizatio`'''`n`''' (count 18 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 in most cases including Trac) as well as a given locale. Such features are eg sentence structure, including punctuation and formatting of numbers, date/time strings and currencies. Once you did some ground work at the source (i18n), what remains is proper translation work (l10n), preserving the meaning of the original while looking as native locale as possible.^[#a1 1]^
    119
    1210'''NLS''' (National Language Support or Native Language Support) is meant to be the sum of both.^[#a1 1], [#a2 2]^
    … …  
    1412=== Background and concept of i18n/l10n support for Trac plugins
    1513
    16 It begun with adding [Babel:] to Trac, a powerful translation framework. For one part, it is a message extraction tool: it can extract messages from source code files (in our case, Python and Javascript) as well as from Genshi templates, and create catalog templates (`.pot` files). It can also create and update the message catalogs (`.po` files), and compile those catalogs (`.mo` files). For the other part, as a Python library used within Trac, it provides the implementation of the message retrieval functions (`gettext` and related). For more information, see [http://babel.edgewall.org/ Babel].
     14It begun with adding [Babel:] to Trac, a powerful translation framework. For one part, it is a message extraction tool: it can extract messages from source code files (in our case, Python and Javascript) as well as from the Genshi templates, and create so-called catalog templates (`.pot` files). It can also create and update the message catalogs (`.po` files), and compile those catalogs (`.mo` files). For the other part, as a Python library used within Trac, it provides the implementation of the message retrieval functions (`gettext` and related). For more information, see [http://babel.edgewall.org/ Babel].
    1715
    1816Some 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 was not a desirable situation. And Trac core maintainers took responsibility with adding functions dedicated to i18n/l10n support for Trac plugins.
    … …  
    3028 - create a `setup.cfg` files for adding options to the Babel commands
    3129 - in your Python source code:
    32    - define specializations of the translation functions for your specific domain; there's a helper function for doing that easily
     30   - define specializations of the translation functions for your specific domain; there is a helper function for doing that easily
    3331   - in the "root" `Component` in your plugin (one you're sure is always enabled) and initialize the translation domain in its `__init__` method
    3432   - use your translation functions appropriately
    … …  
    168166Note: `N_` and `gettext()` are usually used in tandem. For example, when you have a global dict containing strings that need to extracted, you want to mark those strings for extraction but you don't want to put their //translation// in the dict: use `N_("the string")`; when you later use that dict and want to retrieve the translation for the string corresponding to some key, you don't want to mark anything here: use `gettext(mydict.get(key))`.
    169167
    170 To inform Trac about where the plugin's message catalogs can be found, you'll have to call the `add_domain` function obtained via `domain_functions` as shown above. One place to do this is in the `__init__` function of your plugin's main component, like this:
     168To inform Trac about where the plugin's message catalogs can be found, call the `add_domain` function obtained via `domain_functions` as shown above. One place to do this is in the `__init__` function of your plugin's main component, like this:
    171169{{{#!python
    172170    def __init__(self):
    … …  
    188186
    189187==== Mark text for extraction ====
    190 In python scripts you'll have to wrap text with the translation function `_()` to get it handled by translation helper programs.
     188To mark text for translation by helper programs, wrap the relevant Python code with the translation function `_()`:
    191189{{{#!diff
    192190--- a/<path>/api.py
    … …  
    339337General advice from [[TracL10N]] on making good translation for Trac applies here too.
    340338
    341 I.e. it's desirable to maintain a consistent wording across Trac and Trac plugins.
     339It is desirable to maintain a consistent wording across Trac and Trac plugins.
    342340Since this is going beyond the scope of aforementioned [[TracL10N]], there might be the need for more coordination.
    343341Consider joining the [th:TracPluginTranslation Trac plugin l10n project], that utilizes [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex] for uniform access to message catalogs for multiple plugins backed by a dedicated (Mercurial) [http://bitbucket.org/hasienda/trac_plugins-l10n message catalog repository] at Bitbucket.org.
    … …  
    349347}}}
    350348
    351 Extract the messages that where marked for translation before, or on case of Genshi templates are exposed by other means:
     349Extract the messages that where marked for translation before, or in case of Genshi templates are exposed by other means:
    352350{{{
    353351python ./setup.py extract_messages
    354352}}}
    355 The attentive reader will notice that the argument to `setup.py` has the same wording as a section in `setup.cfg`, that is not incidental. And this does apply to the following command lines as well.
    356 
    357 If you attempt to improve on existing message catalogs, you'll update the one for your desired language:
     353The attentive reader will notice that the argument to `setup.py` has the same wording as a section in `setup.cfg`, that is not coincidental. And this does apply to the following command lines as well.
     354
     355If you attempt to improve existing message catalogs, you'll update the one for your desired language:
    358356{{{
    359357python ./setup.py update_catalog -l de_DE
    … …  
    444442See [wiki:TracL10N] and more specifically [wiki:TracL10N#ForDevelopers TracL10N#ForDevelopers], which contains general tips that are also valid for plugin translation.
    445443
    446 [=#a1 ^1^] http://en.wikipedia.org/wiki/Internationalization_and_localization - Internationalization and localization[[BR]]
    447 [=#a2 ^2^] http://en.wikipedia.org/w/index.php?title=Multilingualism&section=18 - Multilingualism in computing[[BR]]
    448 [=#a3 ^3^] http://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names - GNU 'gettext' utilities: Locale Names[[BR]]
    449 [=#a4 ^4^] http://www.gnu.org/software/gettext/manual/gettext.html#Editing - GNU 'gettext' utilities: Editing PO Files[[BR]]
    450 [=#a5 ^5^] http://techbase.kde.org/Localization/Concepts/PO_Odyssey - PO Odyssey in '!Localization/Concepts' section of KDE !TechBase
     444=== Referenced resources
     445* [=#a1 ^1^] [wikipedia:Internationalization_and_localization Internationalization and localization]
     446* [=#a2 ^2^] [wikipedia:Multilingualism#Computing Multilingualism in computing]
     447* [=#a3 ^3^] [http://www.gnu.org/software/gettext/manual/gettext.html#Locale-Names GNU 'gettext' utilities: Locale Names]
     448* [=#a4 ^4^] [http://www.gnu.org/software/gettext/manual/gettext.html#Editing GNU 'gettext' utilities: Editing PO Files]
     449* [=#a5 ^5^] [http://techbase.kde.org/Localization/Concepts/PO_Odyssey PO Odyssey in '!Localization/Concepts' section of KDE TechBase]