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

[Ade Lee]

Great explanation. thanks!

Lets use the latest jquery -- and find out a little more about any
license requirements.

ACK.

Ade 
On Fri, 2012-11-30 at 23:44 -0600, Endi Sukma Dewata wrote:
> 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.
>