[Pki-devel] [PATCH] 184 I18n for ProfileList.template.

[Endi Sukma Dewata]

On 11/14/2012 8:23 AM, Endi Sukma Dewata wrote:
> The messages in ProfileList.template in CA EE has been extracted
> into a properties file which can be translated separately.
>
> The original messages in the template have been marked as follows:
>    <span class="message" name="...key...">...message...</span>
>
> When the page is loaded into the browser, the original message will
> be replaced with the translated message.
>
> Ticket #406

Just to clarify, this patch demonstrates how message customization could 
be done. A full solution will require many incremental patches due to 
the number of messages to be customized. Here is how it works.

Previously a theme consist of HTML/Velocity templates, JS files, images 
and CSS files. The HTML/Velocity templates contain HTML code, JS code, 
paths to images/CSS files, and text messages.

To create a custom theme we had to clone the default Dogtag theme, then 
customize the files as needed. Most of the time we'll only be changing 
the images, CSS, and messages, but we still have to duplicate everything 
in the theme. This becomes a maintenance issue because if we change 
anything in the default theme, the custom theme will not be updated 
automatically, and it could be hard to merge the changes.

Recently we've been moving the templates and JS files out of the theme 
packages into the core packages because they are less likely to be 
changed, leaving just the images and CSS files in the theme. However, 
the messages are still part of the templates. To support customization 
we need to separate the messages from the templates.

JQuery and jquery-i18n-properties are tools that we can use to load 
custom messages from a separate properties file and then replace the 
original messages in the template.

Suppose we have a template which contains the following HTML code:

   <tr>
     <td>Dogtag</td>
     <td>
       The Dogtag Certificate System is an enterprise-class open
       source Certificate Authority.
     </td>
   </tr>

To make the messages customizable we need to mark them. Here we are 
using a <span> which shouldn't be visible in the browser:

   <tr>
     <td>
       <span class="message" name="title">Dogtag</span>
     </td>
     <td>
       <span class="message" name="description">The Dogtag Certificate
       System is an enterprise-class open source Certificate
       Authority.</span>
     </td>
   </tr>

The <span> element is assigned a class "message" which will be used to 
locate all messages. The element is also assigned a name which will be 
used as message key. The original message itself is left intact within 
the <span> to help visualize the page. Then we create a 
Messages.properties that maps the message keys to the actual messages:

   title = Dogtag
   description = The Dogtag Certificate System is an enterprise-class\
       open source Certificate Authority.

The messages in the properties file can be customized as needed. Then 
we'll use the tools to load the custom messages and replace the original 
messages in the template:

   $.i18n.properties({
       name: 'Messages',
       ...
       callback: function() {
           var key;
           for (key in $.i18n.map) {
               var message = $.i18n.prop(key);
               $('span.message[name='+key+']').html(message);
           }
       }
   });

After the browser finishes loading the page the $.i18n.properties() will 
run to load the custom messages from Messages.properties. Once they are 
loaded the callback() will run to replace all marked messages with the 
custom messages.

There are 2 different purposes for message customization which require 
different strategies: branding and translation.

If we're doing branding only, like the current implementation, we need 
to use separate properties for each theme, for example:

   Messages.properties - Dogtag theme
   Messages.properties - Other theme

If we're doing translation only we need to use separate properties file 
for each language, for example:

   Messages.properties - Dogtag theme in English
   Messages_es.properties - Dogtag theme in Spanish
   Messages_fr.properties - Dogtag theme in French

If we're doing both branding and translation the number of files will be 
multiplied:

   Messages.properties - Dogtag theme in English
   Messages_es.properties - Dogtag theme in Spanish
   Messages_fr.properties - Dogtag theme in French

   Messages.properties - Other theme in English
   Messages_es.properties - Other theme in Spanish
   Messages_fr.properties - Other theme in French

One possible solution is to do the translation and branding separately 
using different message markers:

   <tr>
     <td>
       <span class="product" name="title">Dogtag</span>
     </td>
     <td>
       <span class="message" name="description">The <span
       class="product" name="long_title">Dogtag Certificate
       System</span> is an enterprise-class open source Certificate
       Authority.</span>
     </td>
   </tr>

Here we can load the translated "message" first, then load the 
untranslated "product" after that. This solution doesn't require as many 
properties files:

   Messages.properties - English messages
   Messages_es.properties - Spanish messages
   Messages_fr.properties - French messages

   Product.properties - Dogtag theme
   Product.properties - Other theme

If we can assume the messages are fixed, we can actually include the 
messages in the core packages and leave the branding in the theme packages.

We could also stack the theme files, similar to the sections in the 
configuration file, so the custom theme only needs to store the files 
that are different from the default theme. This will require the ability 
to install multiple themes and deploy the custom theme on top of the 
default theme.

-- 
Endi S. Dewata