Changes between Version 25 and Version 26 of CookBook/PluginL10N

Timestamp:

Sep 26, 2012, 12:32:53 AM (12 years ago)

Author:

Christian Boos

Comment:

#Option-i18n: mention the doc_domain keyword

CookBook/PluginL10N

@@ -409 +409 @@
 == Advanced stuff
 
-=== Translating `Option*` documentation
+=== Translating `Option*` documentation  #Option-i18n
 
 Trac 1.0 added support for a special kind of `N_` marker, `cleandoc_`, which can be used to reformat multiline messages in a compact form. There's also support to apply this "cleandoc" transformation to the documentation of instances of `trac.config.Option` and its subclasses. However, this support is coming from a special Python extractor which has to be used instead of the default Python extractor from Babel.
@@ -431 +431 @@
 }}}
 
-The default `cleanup_keywords` (the `Option` subclasses) are not automatically `keywords` however. The corresponding option for the `extract_messages` section of the `setup.cfg` file should therefore contain the `cleandoc_` token, or the various `Config` subclasses together with the position of the doc argument in that subclass.
-As a (somewhat complex) example, see the following excerpt from Trac's [source:tags/trac-1.0/setup.cfg setup.cfg] file:
+The default `cleanup_keywords` (the `Option` subclasses) are not automatically `keywords` however. The corresponding option for the `[extract_messages]` section of the `setup.cfg` file should therefore contain the `cleandoc_` token, or the various `Config` subclasses together with the position of the doc argument in that subclass.
+As an example, see the following excerpt from the SpamFilter plugin [source:plugins/1.0/spam-filter/setup.cfg setup.cfg] file:
 {{{#!python
-[extract_messages_tracini]
+[extract_messages]
 add_comments = TRANSLATOR:
-copyright_holder = Edgewall Software
-msgid_bugs_address = trac-dev@googlegroups.com
-output_file = trac/locale/tracini.pot
-keywords = ConfigSection:2 Option:4 BoolOption:4 IntOption:4 FloatOption:4 ListOption:6 ChoiceOption:4 PathOption:4 ExtensionOption:5 OrderedExtensionsOption:6
-no-default-keywords = yes
-mapping_file = tracini.cfg
-}}}
-
+msgid_bugs_address = [...]
+output_file = tracspamfilter/locale/messages.pot
+keywords = _ ngettext:1,2 N_ tag_ Option:4 BoolOption:4 IntOption:4 ListOption:6 ExtensionOption:5
+width = 72
+}}}
+This makes it possible for the extractor to get the doc strings from those options automatically. For example, in [source:plugins/1.0/spam-filter/tracspamfilter/adapters.py#?IntOption adapters.py]:
+{{{#!python
+class AttachmentFilterAdapter(Component):
+    """Interface to check attachment uploads for spam.
+    """
+    implements(IAttachmentManipulator)
+
+    sample_size = IntOption('spam-filter', 'attachment_sample_size', 16384,
+        """The number of bytes from an attachment to pass through the spam
+        filters.""", doc_domain='tracspamfilter')
+}}}
+as you can see, it's also necessary to specify the //domain//, otherwise the lookup of the translated message at runtime (within the ![[TracIni]] macro, typically) will fail.
 
 === About 'true' l10n