Changes between Version 21 and Version 22 of CookBook/PluginL10N

Timestamp:

Jun 13, 2010, 8:55:39 PM (14 years ago)

Author:

Christian Boos

Comment:

#Javascript brand new section on adding i18n support to Javascript code

CookBook/PluginL10N

@@ -81 +81 @@
 ==== Preset configuration for i18n/l10n helper programs ====
 Add some lines to `setup.cfg` or, if it doesn't exist by now, create it with the following content:
-{{{
+{{{#!ini
 [extract_messages]
 add_comments = TRANSLATOR:
@@ -118 +118 @@
 
 ==== Mark text for extraction ====
-In python scripts you'll have to wrap text with the translation function `_()` to get it handled by translation helper programs. Some code, that was
-{{{
-    msg = 'This is a msg text.'
-}}}
-before, will read like
-{{{
-    msg = _("This is a msg text.")
-}}}
-afterwards.
+In python scripts you'll have to wrap text with the translation function `_()` to get it handled by translation helper programs. 
+{{{#!diff
+--- a/<path>/api.py
++++ b/<path>/api.py
+@@ -1,1 +1,1 @@
+-    msg = 'This is a msg text.'
++    msg = _("This is a msg text.")
+}}}
 
 Note, that quoting of (i18n) message texts should really be done in double quotes. Single quotes are reserved for string constants (see commit note for r9751).
@@ -186 +185 @@
 }}}
 
-==== Text extraction from Javascript code ====
-
-
+==== Text extraction from Javascript code ==== #Javascript
+
+Adding support for translating the marked strings in the Javascript code is a bit more involved, but if you made it to this point, that shouldn't scare you away...
+
+We currently support only statically deployed Javascript files, which means they can't be translated like template files on the server, but that the translation has to happen dynamically on the client side. To this end, we want to send an additional `.js` file containing a dictionary of the messages that have to be translated, and only those. In order to clearly identify which strings have to be present in this dictionary, we'll extract the messages marked for translation (the usual `_(...)` ways) from the Javascript code into a dedicated catalog template, and from there, we'll create dedicated catalogs for each locale. In the end, the translations present in each compiled catalog will be extracted and placed into a `.js` file containing the messages dictionary and some setup code.
+
+The first change is to use `get_l10n_js_cmdclass` in lieu of `get_l10n_cmdclass`. The former adds a few more setup commands for extracting messages strings from Javascript `.js` files and `<script type="text/javascript">` snippets in `.html` files, initialization and updating of dedicated catalog files, and finally compiling that catalog and creating a `.js` file containing the dictionary of strings, ready to be used by the `babel.js` support code already present in Trac pages.
+
+The change to `setup.py` looks like this:
+{{{#!diff
+diff -u a/setup.py b/setup.py
+--- a/setup.py
++++ b/setup.py
+@@ -5,8 +5,8 @@ from setuptools import setup
+ extra = {}
+ 
+-from trac.util.dist import get_l10n_cmdclass
+-cmdclass = get_l10n_cmdclass()
++from trac.util.dist import get_l10n_js_cmdclass
++cmdclass = get_l10n_js_cmdclass()
+ if cmdclass:
+     extra['cmdclass'] = cmdclass
+     extra['message_extractors'] = {
+}}}
+
+That was the easiest part.
+
+Now, as you need to actually send that `.js` file containing the messages dictionary, call `add_script()` as appropriate in the `process_request()` method from your module:
+
+{{{#!diff
+--- a/<path>/api.py
++++ b/<path>/api.py
+@@ -243,6 +243,8 @@ class FooTracPlugin(Component):
+         builds = self._extract_builds(self._get_info(start, stop))
+         data = {'builds': list(builds)}
+         add_script(req, '<path>/hudsontrac.js')
++        if req.locale is not None:
++            add_script(req, '<path>/foo/%s.js' % req.locale)
+         add_stylesheet(req, '<path>/foo.css')
+         return 'foo-build.html', data, None
+ 
+}}}
+
+Now, you need to expand the `setup.cfg` file with the configuration that the new `cmdclass` dedicated to Javascript translation need. Those classes all end with an `_js` suffix.
+
+{{{#!ini
+[extract_messages_js]
+add_comments = TRANSLATOR:
+copyright_holder = <Your Name>
+msgid_bugs_address = <Your E-Mail>
+output_file = <path>/locale/messages-js.pot
+keywords = _ ngettext:1,2 N_
+mapping_file = messages-js.cfg
+
+[init_catalog_js]
+domain = foo-js
+input_file = <path>/locale/messages-js.pot
+output_dir = <path>/locale
+
+[compile_catalog_js]
+domain = foo-js
+directory = <path>/locale
+
+[update_catalog_js]
+domain = foo-js
+input_file = <path>/locale/messages-js.pot
+output_dir = <path>/locale
+
+[generate_messages_js]
+domain = foo-js
+input_dir = <path>/locale
+output_dir = <path>/htdocs/foo
+}}}
+
+As before, replace `<path>` with what's appropriate for your plugin. Note that the domain name is now `foo-js`, not just `foo` as before. This is necessary as we want to have only the strings actually needed Javascript to be stored in the `.js` file containing the messages dictionary.
+
+We're nearly done yet... noticed the `mapping_file = messages-js.cfg` line?
+We need to configure separately how to do the extraction for this `messages-js.pot` catalog template.
+The `messages-js.cfg` file has the following content:
+{{{#!ini
+# mapping file for extracting messages from javascript files into
+# <path>/locale/messages-js.pot (see setup.cfg)
+[javascript: **.js]
+
+[extractors]
+javascript_script = trac.util.dist:extract_javascript_script
+
+[javascript_script: **.html]
+}}}
+
+Bonus points for anyone who will manage to //simplify// a bit this procedure ;-)
 
 ==== Register message catalog files for packaging ====