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/caveats.rst | 308 +++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/en/rst/localizing/caveats.rst (limited to 'docs/en/rst/localizing/caveats.rst') diff --git a/docs/en/rst/localizing/caveats.rst b/docs/en/rst/localizing/caveats.rst new file mode 100644 index 000000000..ce988dabe --- /dev/null +++ b/docs/en/rst/localizing/caveats.rst @@ -0,0 +1,308 @@ +.. _caveats: + +Template Caveats +################ + +================ +[% %] and [%+ %] +================ + +``[% %]`` is used by Template Toolkit to enclose some TT code, which will be +often be replaced by a variable or something else when the template is +rendered. + +Generally, you should follow the exact text layout of the English version, but +if you need to change the position of a ``[% %]`` block in a line, you should +be aware of this rule: when two ``[% %]`` blocks are following each other, +the second member will not be separated with a space from the first one, even +if you separate them with a space. For instance, these lines of template code: + +.. raw:: html + + 
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+      This [% terms.bug %] has been marked as a duplicate of [% terms.bug %] [% dupe_of FILTER html %]
+
+ +will display in the browser as: + +.. code-block:: text + + This bug has been marked as duplicate of bug12345 + +To preserve whitespace, you should add a "+" sign inside the second member: + +.. raw:: html + + 
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+       This [% terms.bug %] has been marked as a duplicate of [% terms.bug %] [%+ dupe_of FILTER html %]
+
+ +Will then be displayed as: + +.. code-block:: text + + This bug has been marked as duplicate of bug 12345 + +This is the same when a [% %] member is at the beginning of a new line. These +lines of template code: + +.. code-block:: text + + [% IF groups_added_to.size %] +
  • + The account has been added to the + [% groups_added_to.join(', ') FILTER html %] + group[% 's' IF groups_added_to.size > 1 %]. +
    • + [% END %] + +will be shown as: + +.. code-block:: text + + The account has been added to thebz_sudo_protect group. + +Again, insert a "+" sign: + +.. raw:: html + + 
    +          [% IF groups_added_to.size %]
+            <li>
+              The account has been added to the
+              [%+ groups_added_to.join(', ') FILTER html %]
+              group[% 's' IF groups_added_to.size > 1 %].
+            </li>
+          [% END %]
+
    + +So that the sentence is displayed as: + +.. code-block:: text + + The account has been added to the bz_sudo_protect group. + +Sometimes, pluralization is dealt with using explicit Template Toolkit code, +which needs to be altered for your language. + +For example, if one wanted to localize the previous example into French, +the words order would not be not correct and the markup has to be rearranged. +The member ``[% groups_added_to.join(', ') FILTER html %]`` will actually display +the name of one group or several group names separated with a comma and a space (', '). +The member ``[% 's' IF groups_added_to.size > 1 %]`` will add an "s" +to the word "group" if there is more than one. In French, the group name should be put +after the term "group" and words need to be declensed when plural is used. That +would give for instance the following: + +.. code-block:: text + + [% IF groups_added_to.size %] +
  • + Le compte a été ajouté + [% IF groups_added_to.size > 1 %] + aux groupes[% ELSE %]au groupe[% END %][%+ groups_added_to.join(', ') FILTER html %]. +
    • + [% END %] + +The browser would then display for one group: + +.. raw:: html + + Le compte a été ajouté au groupe bz_sudo_protect + +And for several groups: + +.. raw:: html + + Le compte a été ajouté aux groupes bz_sudo_protect, canconfirm, editbugs + +=============================== +Double quotes and single quotes +=============================== + +Template Toolkit strings in directives are quote-delimited, and can use either +single or double quotes. But, obviously, you can't put double quotes inside +a double-quoted string. The following example will break the user interface: + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = "Click here if the page "does not" redisplay automatically." %] + + +Instead, you can escape them with a backslash ("\"): + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = "Click here if the page \"does not\" redisplay automatically." %] + + +Or you can substitute the surrounding double quotes with single quotes: + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = 'Click here if the page "does not" redisplay automatically.' %] + +=========== +Declensions +=========== + +English only deals with one plural form and has no declension. Your locale +might need to implement declensions, and reorder words inside a sentence. + +Let's say we have the following: + +.. code-block:: text + + [% IF !Param("allowbugdeletion") %] +

    + Sorry, there + + [% IF comp.bug_count > 1 %] + are [% comp.bug_count %] [%+ terms.bugs %] + [% ELSE %] + is [% comp.bug_count %] [%+ terms.bug %] + [% END %] + + pending for this component. You should reassign + + [% IF comp.bug_count > 1 %] + these [% terms.bugs %] + [% ELSE %] + this [% terms.bug %] + [% END %] + + to another component before deleting this component. +

    + [% ELSE %] + +Here, the following expression comp.bug_count obviously gives the count number of bugs +for a component. ``IF comp.bug_count > 1`` means "if there are more than one bug". + +Let's say your language has to deal with three plural forms and that the terms "bug" and +"pending" should be declensed as well. + +First, you'll have to populate the :file:`/template/en/default/global/variables.none.tmp` +file with the declensions for "bug", which would give something like: + +.. code-block:: text + + [% terms = { + "bug0" => "declension for zero bug", + "bug" => "declension for one bug", + "bug2" => "declension for two bugs", + "bug3" => "declension for three bugs", + "bugs" => "declension for more than three bugs", + + +Then, the previous code should look like: + +.. code-block:: text + + [% IF !Param("allowbugdeletion") %] +

    + Sorry, there + + [% IF comp.bug_count > 3 %] + are [% comp.bug_count %] pending [% terms.bugs %] + [% ELSE %] + [% IF comp.bug_count == 0 %] + is [% comp.bug_count %] pending [% terms.bug0 %] + [% ELSE %] + [% IF comp.bug_count == 1 %] + is [% comp.bug_count %] pending [% terms.bug %] + [% ELSE %] + [% IF comp.bug_count == 2 %] + are [% comp.bug_count %] pending [% terms.bug2 %] + [% ELSE %] + [% IF comp.bug_count == 3 %] + are [% comp.bug_count %] pending [% terms.bug3 %] + [% END %] + + for this component. You should reassign + + [% IF comp.bug_count > 1 %] + these [% terms.bugs %] + [% ELSE %] + this [% terms.bug %] + [% END %] + + to another component before deleting this component. +

    + [% ELSE %] + +========== +$terms.foo +========== + +As seen previously, term substitutions can be made across all template files. +Such substitutions are defined in ``*.none.tmpl`` files, which are: + +* template/en/default/global/field-descs.none.tmpl +* template/en/default/global/variables.none.tmpl +* template/en/default/global/value-descs.none.tmpl +* template/en/default/global/reason-descs.none.tmpl +* template/en/default/global/setting-descs.none.tmpl +* template/en/default/bug/field-help.none.tmpl + +These variables appear in the template files under three different forms. +``[% terms.foo %]`` is the standard, simple substitution of a term into a run +of text. ``$terms.foo`` is used when substituting into a Template Toolkit +string, and ``${terms.foo}`` is used when you need to separate the variable +name from the surrounding content to resolve ambiguity. + +To illustrate this last point: during your localizing contribution, you may +have to reorganize sentences, and sometimes a variable of the form +``$terms.foo`` will come at the end of a sentence which ends with a full stop, +like this: + +.. raw:: html + + 
    +    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de $terms.bug.<br> " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+
    + +If you leave it like that, the substitution would not take place and the +result in the user interface would be wrong. Instead, change the form +``$terms.foo`` into the form ``${terms.foo}``, like this: + +.. raw:: html + + 
    +    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de ${terms.bug}.<br> " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+
    + +======== +b[% %]ug +======== + +Once and a while you would find something like: + +.. code-block:: text + + A b[% %]ug on b[% %]ugs.debian.org. + +You remember that the file :file:`variables.none.tmpl` holds the substitutions +for different terms. The release process of Bugzilla has a script that +parses all the templates to check if you wrote the bare word "bug" instead of +"$terms.bug" or similar, to make sure that this feature keeps working. + +In the example above, we really want to write the term "bug" and we neither +want it to be substituted afterwards nor be warned by the test script. + +This check only looks at the English terms bug, bugs, and Bugzilla, so you can +safely ignore the ``[% %]`` and localize ``b[% %]ug``, but you would keep +``b[% %]ugs.debian.org`` unchanged as it's a URL. -- cgit v1.2.3-24-g4f1b