From 7321534b42aab3ab2064c73b6326d52f395f023c Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Wed, 30 Sep 2015 09:03:22 +0100 Subject: Bug 1156785 - add new Localization Guide for in-place review. --- docs/en/rst/localizing/localizing-templates.rst | 144 ++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/en/rst/localizing/localizing-templates.rst (limited to 'docs/en/rst/localizing/localizing-templates.rst') diff --git a/docs/en/rst/localizing/localizing-templates.rst b/docs/en/rst/localizing/localizing-templates.rst new file mode 100644 index 000000000..f66b8e07b --- /dev/null +++ b/docs/en/rst/localizing/localizing-templates.rst @@ -0,0 +1,144 @@ +.. _localizing-templates: + +Localizing The Templates +######################## + +.. note:: Use an UTF-8-compliant editor, like Gedit, Kate or Emacs under + GNU/Linux systems or Notepad++ under Windows systems, and make sure + you save the templates using the UTF-8 encoding. + +Templates contain both code and localizable strings mixed together. So the +question arises: what is to be localized and what is not? Here are some +examples to help you localize the correct parts of each file. + +You can see at the top of each template file lines like these: + +.. code-block:: text + + [%# This Source Code Form is subject to the terms of the Mozilla Public + # License, v. 2.0. If a copy of the MPL was not distributed with this + # file, You can obtain one at http://mozilla.org/MPL/2.0/. + # + # This Source Code Form is "Incompatible With Secondary Licenses", as + # defined by the Mozilla Public License, v. 2.0. + #%] + +DO NOT translate any text located between ``[%#`` and ``#%]``. Such text is a +comment. + +Here are some examples of what does need to be translated: + +.. raw:: html + + 
+  [% title = BLOCK %]Delete Component '[% comp.name FILTER html %]'
+  of Product '[% product.name FILTER html %]'
+    [% END %]
+
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  <table border="1" cellpadding="4" cellspacing="0">
+  <tr bgcolor="#6666FF">
+    <th valign="top" align="left">Field</th>
+    <th valign="top" align="left">Value</th>
+  </tr>
+
+ +As a general rule, never +translate capitalized words enclosed between ``[%`` and ``%]`` - these are +Template Toolkit directives. Here is the localized version of the above: + +.. raw:: html + + 
+  [% title = BLOCK %]Supprimer le composant « [% comp.name FILTER html %] »
+  du produit « [% product.name FILTER html %] »
+    [% END %]
+  
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  <table border="1" cellpadding="4" cellspacing="0">
+  <tr bgcolor="#6666FF">
+    <th valign="top" align="left">Champ</th>
+    <th valign="top" align="left">Valeur</th>
+  </tr>
+
+ +Another common occurrence in the templates is text enclosed between an opening +and a closing tag, or in an HTML attribute value: + +.. raw:: html + + 
+  <td valign="top">Description du produit :</td>
+  
+  <td valign="top">[% IF product.disallow_new %]Oui[% ELSE %]Non[% END %]</td>
+  
+    <a title="Liste des [% terms.bugs %] pour le composant « [% comp.name FILTER html %] »"
+       href="buglist.cgi?component=[% comp.name FILTER url_quote %]&product=
+            [%- product.name FILTER url_quote %]">[% comp.bug_count %]</a>
+
+ +You will encounter many buttons you will want to localize. These look like this: + +.. raw:: html + + 
+    <input type="submit" id="create" value="Add">
+    <input type="hidden" name="action" value="new">
+    <input type="hidden" name='product' value="[% product.name FILTER html %]">
+    <input type="hidden" name="token" value="[% token FILTER html %]">
+
+ +Whenever you see this, the only line that needs to be localized is the one +with ``type="submit"``. DO NOT translate lines with ``type="hidden"``: + +.. raw:: html + + 
+    <input type="submit" id="create" value="Ajouter">
+    <input type="hidden" name="action" value="new">
+    <input type="hidden" name='product' value="[% product.name FILTER html %]">
+    <input type="hidden" name="token" value="[% token FILTER html %]">
+
+ + +Some of the templates are a bit special. One such is +:file:`/template/en/default/global/variables.none.tmpl`. +This file contains several terms that are be substituted all around the +template files. In particular, it contains code so the administrator can easily and +consistently use whatever alternative term their organization uses for "bug" +and also for "Bugzilla" (i.e. the name of the system). Whenever you see expressions like +``&terms.ABug`` or ``&terms.bugs`` in templates, they will be replaced in the +user interface with the corresponding value from this file. + +As these are commonly-requested changes, you probably want to retain this +flexibility in your localization, although you may have to alter exactly how +it works if your language does not have exact equivalents for "a" and "the". + +.. raw:: html + + 
+  [% terms = {
+    "bug" => "bug",
+    "Bug" => "Bug",
+    "abug" => "a bug",
+    "Abug" => "A bug",
+    "ABug" => "A Bug",
+    "bugs" => "bugs",
+    "Bugs" => "Bugs",
+    "zeroSearchResults" => "Zarro Boogs found",
+    "bit" => "bit",
+    "bits" => "bits",
+    "Bugzilla" => "Bugzilla"
+    }
+  %]
+
+ +You need to come up with an equivalent set of mappings for your language, and +then whenever you are talking about bugs in the user interface, use your +equivalent of ``&terms.ABug`` or ``&terms.bugs`` and friends instead. -- cgit v1.2.3-24-g4f1b