| 37 | | For a '''fictional plugin 'foo' ''' just add |
| | 37 | Pick a reasonably unique name for the catalog, e.g. ** 'foo' ** |
| | 38 | |
| | 39 | This will be the basename for the various translation catalog files |
| | 40 | (e.g. `<path>/locale/fr/LC_MESSAGES/foo.po` for the French catalog). |
| | 41 | |
| | 42 | At run-time, the translation functions (typically `_(...)`) have to know in which catalog the translation will be found. Specifying the 'foo' domain in every such call would be tedious, that's why there's a facility for creating partially instantiated domain-aware translation functions, `domain_functions`. |
| | 43 | |
| | 44 | This helper function should be called at module load time, like this: |
| 41 | | _, tag_, N_, add_domain = domain_functions('foo', |
| 42 | | '_', 'tag_', 'N_', 'add_domain') |
| 43 | | }}} |
| 44 | | at the beginning of the main python script file. |
| 45 | | // TODO I think I'll change that to: // |
| 46 | | {{{#!python |
| 47 | | from trac.util.translation import domain_functions |
| 48 | | |
| 49 | | _, tag_, N_, add_domain = domain_functions('foo', ('_', 'tag_', 'N_', 'add_domain')) |
| 50 | | }}} |
| 51 | | //FIXME give the list of available domain functions// |
| 52 | | |
| 53 | | 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: |
| | 48 | _, tag_, N_, add_domain = \ |
| | 49 | domain_functions('foo', ('_', 'tag_', 'N_', 'add_domain')) |
| | 50 | }}} |
| | 51 | |
| | 52 | The translation functions which can be bound to a domain are: |
| | 53 | - `'_'`: extract and translate |
| | 54 | - `'ngettext'`: extract and translate (singular, plural, num) |
| | 55 | - `'tgettext'`, `'tag_'`: same as `'_'` but for Markup |
| | 56 | - `'tngettext'`, `'tagn_'`: same as `'ngettext'` but for Markup |
| | 57 | - `'gettext'`: translate only, don't extract |
| | 58 | - `'N_'`: extract only, don't translate |
| | 59 | - `'add_domain'`: register the catalog file for the bound domain |
| | 60 | |
| | 61 | To inform Trac about where the plugin's message catalogs can be found, you'll have to call the `'add_domain'` obtained via `domain_functions`. One place to do this is in the `__init__` function of your plugin's main component, like this: |
| 60 | | assuming that folder `locale` will reside in `./foo/locale/` within the directory structure (as observable inside the Python egg after packaging). |
| 61 | | |
| 62 | | If you didn't have it in the source by now, add another import statement |
| 63 | | {{{#!python |
| 64 | | import pkg_resources |
| 65 | | }}} |
| 66 | | at the beginning of the plugin script as well or the line `locale_dir = ...` (see previous code snippet) will throw an '!ImportError'. |
| 67 | | |
| 68 | | 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: |
| | 69 | assuming that folder `locale` will reside in the same folder as the file containing the code above, referred to as `<path>` (as observable inside the Python egg after packaging). |
| | 70 | |
| | 71 | 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 its name is `api.py`, there: |
| 100 | | This will tell the i18n/l10n helper programs where to look for and store message catalog files. Since we prepare for a domain dedicted to the plugin you need to change the configuration to the existing plugin directory (that is a short all-lowercase form of plugin's name in most cases) wherever it reads `foo` in the example. |
| 101 | | |
| 102 | | In the `extract_messages` section there are other lines you may like to change. Starting with `add_comments` there is the place to announce yourself as the translator by adding your name after the default `TRANSLATOR:` label. To allow for direct feedback regarding your translation add a valid e-mail address or a mailing list dedicated to translation issues to `msgid_bugs_address`. |
| | 106 | Replace `<path>` as appropriate (i.e. the relative path to the folder containing the `locale` directory, for example `mytracplugin`). |
| | 107 | |
| | 108 | This will tell the i18n/l10n helper programs where to look for and store message catalog files. |
| | 109 | |
| | 110 | In the `extract_messages` section there are other lines you may like to change. |
| | 111 | |
| | 112 | // Starting with `add_comments` there is the place to announce yourself as the translator by adding your name after the default `TRANSLATOR:` label. To allow for direct feedback regarding your translation add a valid e-mail address or a mailing list dedicated to translation issues to `msgid_bugs_address`. // |
| | 113 | Well, no, add_comments simply list the tags in the comments surrounding the calls to the translation functions in the source code that have to be propagated to the catalogs... (see Babel:wiki:Documentation/0.9/setup.html#extract-messages) |
| | 114 | |
| | 115 | {{{#!comment |
| | 116 | resume review here... |
| | 117 | }}} |
