Bug 1156785 - add new Localization Guide for in-place review.

contrib/new-locale.pl

+#!/usr/bin/perl -w
+
+use File::Find;
+use File::Copy::Recursive qw(dircopy);
+
+($ARGV[0] && $ARGV[0] =~ /\w\w(-\w\w)?/) || usage();
+
+sub process {
+    if ($_ eq 'en' && $File::Find::name !~ /\/data\//) {
+        dircopy($_, $ARGV[0]);
+    }
+}
+
+find(\&process, ".");
+
+sub usage {
+    print "Usage: new-locale.pl <lang code>\n";
+    print " e.g.: new-locale.pl fr\n";
+}

docs/en/rst/index.rst

@@ -12,6 +12,7 @@ Bugzilla Documentation
    administering/index
    integrating/index
    api/index
+   localizing/index
    
 .. toctree::
    :hidden:

docs/en/rst/installing/linux.rst

@@ -45,7 +45,7 @@ If you want to install a version of Bugzilla from the Bugzilla project, you
 will instead need:
 
 :command:`yum install httpd mysql-server mod_perl mod_perl-devel httpd-devel
-gd-devel mysql-devel
+gd-devel mysql-devel rst2pdf
 graphviz patchutils gcc 'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)'
 'perl(Authen::SASL)' 'perl(Cache::Memcached)' 'perl(CGI)' 'perl(Chart::Lines)'
 'perl(Daemon::Generic)' 'perl(Date::Format)' 'perl(DateTime)'
@@ -57,7 +57,7 @@ graphviz patchutils gcc 'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)'
 'perl(HTML::Scrubber)' 'perl(IO::Scalar)' 'perl(JSON::RPC)' 'perl(JSON::XS)'
 'perl(List::MoreUtils)' 'perl(LWP::UserAgent)' 'perl(Math::Random::ISAAC)'
 'perl(MIME::Parser)' 'perl(mod_perl2)' 'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)'
-'perl(PatchReader)' 'perl(SOAP::Lite)' 'perl(Template)'
+'perl(PatchReader)' 'perl(SOAP::Lite)' 'perl(Template)' 'perl(File::Which)'
 'perl(Template::Plugin::GD::Image)' 'perl(Test::Taint)' 'perl(TheSchwartz)'
 'perl(URI)' 'perl(XMLRPC::Lite)' 'perl(XML::Twig)'`
 
@@ -82,10 +82,10 @@ libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl
 libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl
 libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl
 libtest-taint-perl libauthen-radius-perl libfile-slurp-perl
-libencode-detect-perl libmodule-build-perl libnet-ldap-perl
+libencode-detect-perl libmodule-build-perl libnet-ldap-perl libfile-which-perl
 libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl
 libhtml-formattext-withlinks-perl libgd-dev libmysqlclient-dev lynx-cur
-graphviz python-sphinx`
+graphviz python-sphinx rst2pdf`
 
 If you plan to use a database other than MySQL, you will need to also install
 the appropriate packages for that.

docs/en/rst/installing/quick-start.rst

@@ -50,7 +50,7 @@ Install Prerequisites
 
 :command:`apt-get install git nano`
 
-:command:`apt-get install apache2 mysql-server libappconfig-perl libdate-calc-perl libtemplate-perl libmime-perl build-essential libdatetime-timezone-perl libdatetime-perl libemail-sender-perl libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl libtest-taint-perl libauthen-radius-perl libfile-slurp-perl libencode-detect-perl libmodule-build-perl libnet-ldap-perl libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl libhtml-formattext-withlinks-perl libgd-dev libmysqlclient-dev lynx-cur graphviz python-sphinx`
+:command:`apt-get install apache2 mysql-server libappconfig-perl libdate-calc-perl libtemplate-perl libmime-perl build-essential libdatetime-timezone-perl libdatetime-perl libemail-sender-perl libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl libtest-taint-perl libauthen-radius-perl libfile-slurp-perl libencode-detect-perl libmodule-build-perl libnet-ldap-perl libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl libhtml-formattext-withlinks-perl libfile-which-perl libgd-dev libmysqlclient-dev lynx-cur graphviz python-sphinx rst2pdf`
 
 This will take a little while. It's split into two commands so you can do
 the next steps (up to step 7) in another terminal while you wait for the

docs/en/rst/localizing/checking-templates.rst

+.. _checking-templates:
+
+Checking Templates
+##################
+
+Checking Syntax
+---------------
+
+This step is important because if you have some wrong syntax in your template, this will break the user interface.
+
+You can see the checking scripts in the ``t/`` subdirectory in your Bugzilla root directory.
+
+To check the localized templates, you would only need to run these three ones:
+
+* t/004template.t
+* t/008filter.t
+* t/009bugwords.t
+
+So run e.g.:
+
+:command:`prove -Q t/004template.t`
+
+If your templates are valid, you should see a result like this:
+
+.. raw:: html
+
+  <pre>
+  t/004template.t .. ok         
+  <span class="green">All tests successful.</span>
+  Files=1, Tests=1236,  5 wallclock secs ( 0.11 usr  0.00 sys +  4.70 cusr  0.05 csys =  4.86 CPU)
+  Result: PASS
+  </pre>
+
+If something went wrong, you will see something like this:
+
+.. raw:: html
+
+  <pre>
+  #   Failed test 'template/fr/default/index.html.tmpl has bad syntax --ERROR'
+  #   at t/004template.t line 106.
+  # Looks like you failed 1 test of 1236.
+  
+  Test Summary Report
+  -------------------
+  <mark>t/004template.t (Wstat: 256 Tests: 1236 Failed: 1)
+    Failed test:  671
+    Non-zero exit status: 1</mark>
+  Files=1, Tests=1236,  4 wallclock secs ( 0.09 usr  0.01 sys +  4.74 cusr  0.04 csys =  4.88 CPU)
+  Result: FAIL
+  </pre>
+
+where you would hopefully see the faulty template and the line number where the error occurred.
+
+Then, fix the error and run the scripts again.
+
+Viewing In Bugzilla
+-------------------
+
+Once your templates have good syntax, you will want to use them in Bugzilla.
+
+Run:
+
+:command:`./checksetup.pl`
+
+to compile the templates and clear the language cache. Bugzilla will then
+have a language chooser in the top right corner. By default, it uses the
+``Accept-Language`` HTTP header to decide which version to serve you, but you can
+override that by choosing a version explicitly. This is then remembered
+in a cookie.
+
+Choose the language you have localized in, if it's not already chosen for
+you, and then view every page in Bugzilla to test your templates :-) This
+may take some time...

docs/en/rst/localizing/compiling-documentation.rst

+.. _compiling-documentation:
+
+Compiling The Documentation
+###########################
+
+To compile the documentation, you need the Sphinx software and the :command:`rst2pdf` tool.
+You should have both already if you followed the installation process.
+
+.. note:: PDF generation does not work currently with ``python3-sphinx`` package.
+
+You can test that you are able to compile the docs by running the following command in the :file:`docs/` directory:
+
+:command:`./makedocs.pl`
+
+This will generate the English documentation files in HTML, PDF and plain text formats in the :file:`docs/en` directory
+and its subdirectories.
+
+If all is running fine, you can then copy your localized directory in the :file:`docs/` directory. You should have then
+three directories:
+
+.. code-block: text
+
+  |-- docs
+  |    |-- ab-CD
+  |    |-- en
+  |    |-- lib
+
+You should now customize the file :file:`docs/ab-CD/rst/conf.py`. Here are the sections you should edit:
+
+.. raw:: html
+
+  <pre>
+  # General information about the project.
+  project = u'<mark>Bugzilla</mark>'
+  copyright = u'<mark>2014, The Bugzilla Team</mark>'
+  </pre>
+
+.. raw:: html
+
+  <pre>latex_documents = [
+    ('index', 'Bugzilla.tex', u'<mark>Bugzilla Documentation</mark>',
+     u'<mark>The Bugzilla Team</mark>', 'manual'),
+  ]
+  </pre>
+
+.. raw:: html
+
+  <pre>
+  man_pages = [
+      ('index', 'bugzilla', u'<mark>Bugzilla Documentation</mark>',
+       [u'<mark>The Bugzilla Team</mark>'], 1)
+  ]
+  </pre>
+
+.. raw:: html
+
+  <pre>
+  texinfo_documents = [
+    ('index', 'Bugzilla', u'<mark>Bugzilla Documentation</mark>',
+     u'<mark>The Bugzilla Team</mark>', 'Bugzilla', 'One line description of project.',
+     'Miscellaneous'),
+  ]
+  </pre>
+
+.. raw:: html
+
+  <pre>
+  pdf_documents = [
+  ('index', u'<mark>Bugzilla</mark>', u'<mark>Bugzilla Documentation</mark>', u'<mark>The Bugzilla Team</mark>'),
+  ]
+  </pre>
+
+.. raw:: html
+
+  <pre>
+  rst_epilog = <mark>u</mark>"""
+  
+  ----------
+  
+  <mark>This documentation undoubtedly has bugs; if you find some, please file
+  them `here &lt;https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=Documentation&gt;`_.</mark>
+  """
+  </pre>
+
+For this last section, pay attention to the letter ``u`` added before the three double quotes: it is not present in the English
+version of this file. This letter indicates that the text following will contain non-ASCII characters and your language will probably
+needs non-ASCII characters. If you omit to add this letter and that your localization contains non-ASCII characters, the compilation
+of the documentation will not work. The multiple dashes are here for formatting purposes and will render as a line in the HTML version.
+
+Another section you will want to edit is the following one:
+
+.. code-block:: text
+
+  # The language for content autogenerated by Sphinx. Refer to documentation
+  # for a list of supported languages.
+  #language = None
+
+If your locale is available for Sphinx (to find out, consult the `Sphinx documentation <http://sphinx-doc.org/config.html#confval-language>`_)
+then you should uncomment the line and specify your locale code here:
+
+.. raw:: html
+
+  <pre>
+  # The language for content autogenerated by Sphinx. Refer to documentation
+  # for a list of supported languages.
+  <mark>language = 'fr'</mark>
+  </pre>
+
+If your locale is not available for Sphinx, then the labels for navigation elements -- next, previous, search box, etc. -- will not be localized.
+
+
+

docs/en/rst/localizing/files-to-be-localized.rst

+.. _files-to-be-localized:
+
+Files To Be Localized
+#####################
+
+There are several different types of files to be localized:
+
+Templates
+---------
+
+\*.tmpl files
+   These files are `Template Toolkit <http://template-toolkit.org/>`_
+   templates, which are used to generate the HTML pages which make up
+   Bugzilla's user interface. There are templates in both
+   the :file:`extensions` and :file:`template` subdirectories.
+
+strings.txt.pl:
+   This is a Perl file. It contains strings which are used when displaying
+   information or error messages during Bugzilla's setup, when the templating
+   infrastructure is not available. It is located in the
+   :file:`template/en/default/setup` directory.
+
+Documentation
+-------------
+
+\*.rst files:
+   These files are `ReStructuredText <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_,
+   and contain Bugzilla's documentation. There are reST files in the
+   :file:`docs` and :file:`extensions/Example/docs/en/rst` subdirectories.
+
+bzLifecycle.xml:
+   This is an XML source file for the diagramming tool
+   `Dia <https://wiki.gnome.org/Apps/Dia>`_. It is used to generate the flow
+   diagram showing the different states in a bug lifecycle, which is part of
+   the documentation.

docs/en/rst/localizing/get-the-source.rst

+.. _get-the-source:
+
+Get The Source Files
+####################
+
+First, you need to install Bugzilla and get it running. See the
+:ref:`installing`.
+
+The installed software should have the following tree structure:
+
+.. raw:: html
+
+  <pre>
+  |-- Bugzilla
+  |-- contrib
+  |-- docs
+  |   `-- <mark>en</mark>
+  |-- extensions
+  |   |-- BmpConvert
+  |   |-- Example
+  |   |   |-- docs
+  |   |   |   `-- <mark>en</mark>
+  |   |   |-- lib
+  |   |   `-- template
+  |   |       `-- <mark>en</mark>
+  |   |-- MoreBugUrl
+  |   |   |-- lib
+  |   |   `-- template
+  |   |       `-- <mark>en</mark>
+  |   `-- Voting
+  |       |-- template
+  |       |   `-- <mark>en</mark>
+  |-- images
+  |-- js
+  |-- template
+  |   `-- <mark>en</mark>
+  | ...
+  </pre>
+
+All localizable content is in directories called ``en``, for English. You
+are going to create a parallel set of directories named after your locale
+code, and build your localized version in there.
+
+So next, you need to work out your locale code. You
+can find the locale code matching your language on
+`this wiki page <https://wiki.mozilla.org/L10n:Simple_locale_names>`_.
+For instance, ``fr`` is used for French and ``ca`` for Catalan. You can
+also use a four-letter locale code, e.g. ``pt-BR`` for Brazilian Portuguese or
+``zh-CN`` for Chinese (Simplified). In the rest of this guide, your locale
+code will be represented by ``ab-CD``.
+
+Then, run:
+
+:command:`contrib/new-locale.pl ab-CD`
+
+This will make a copy of all the English documentation for you, in parallel
+directories to the "en" directories, named after your locale code.

docs/en/rst/localizing/hosting-documentation.rst

+.. _hosting-documentation:
+
+Hosting The Documentation On readthedocs.org
+############################################
+
+You will want to make your templates and documentation available in a
+localization tarball for sites to install. However, Bugzilla's main
+documentation site is readthedocs.org. If you put your localized documentation
+up on that site, then it can be linked in with the main Bugzilla docs and
+appear as an alternative version.
+
+To do this, you need to have a
+`DVCS <https://en.wikipedia.org/wiki/Distributed_revision_control>`_ repository
+of your files accessible from the Internet. ReadTheDocs.org currently supports
+Mercurial, Git, Subversion and Bazaar repositories, but if you are working in
+a clone of the main Bugzilla repo, you will be using Git.
+You can create your repository on sites such as
+`Github <https://github.com/>`_ or `sourceforge.net <https://sourceforge.net/>`_.
+It is both easiest and best if you publish your entire code tree, including the
+Bugzilla source code, as some of it is needed to compile the docs.
+
+You should localize on the branch or head named after the major number of the
+release, for instance '``5.0``'. If you are making your own repo rather than
+cloning the Bugzilla one, you should name your branches in this way also.
+
+Then, get on the `readthedocs.org <https://readthedocs.org>`_ site and create
+an account by clicking on the button :guilabel:`Sign up`. Fill up the form and
+click on the :guilabel:`Sign Up »` button:
+
+.. image:: ../../images/RTD1.png
+
+*Sign Up Form*
+
+On the page that appears, click on the :guilabel:`Import a Project` button:
+
+.. image:: ../../images/RTD2.png
+
+*Ready to share your documentation*
+
+Then, either connect to your GitHub account or click on the :guilabel:`Manually Import Project`
+button. The manual way will be explained below.
+
+.. image:: ../../images/RTD3.png
+
+*Import a Project*
+
+You should now name your project, following the naming rule ``bugzilla-ab-CD`` --where ab-CD is your locale code--,
+specify the URL for your repository and its type, and tick the :guilabel:`Edit advanced project options:` square. Click then
+on the :guilabel:`Next` button:
+
+.. image:: ../../images/RTD4.png
+
+*Project Details*
+
+Fill now the new form, especially the :guilabel:`Description`, :guilabel:`Documentation` and :guilabel:`Language` fields. The other
+fields can be ignored and modified later if necessary. Then, click on the :guilabel:`Finish` button:
+
+.. image:: ../../images/RTD5.png
+
+*Project Extra Details*
+
+Now, click on the :guilabel:`Versions` button in the navigation header and in the :guilabel:`Inactive Versions` section, choose
+the version you want to activate by clicking on the :guilabel:`Edit` button:
+
+.. image:: ../../images/RTD6.png
+
+*Versions*
+
+.. image:: ../../images/RTD7.png
+
+*Inactive versions*
+
+Tick the :guilabel:`Active:` square and click on the :guilabel:`Save` button:
+
+.. image:: ../../images/RTD8.png
+
+*Editing Version*
+
+Now, click on the :guilabel:`Overview` button in the navigation header. The version you have just made active should appear there.
+In the :guilabel:`Build a version` dropdown list, select the version you want to compile and click on the :guilabel:`Build` button to compile
+your localized documentation:
+
+.. image:: ../../images/RTD9.png
+
+*Overview*
+
+.. image:: ../../images/RTD10.png
+
+*Compilation Results*
+
+If the result is ``Passed``, your documentation has been successfully compiled. If the result is ``Failed``, click
+on the link to see what went wrong and fix it.
+
+Finally, you should inform the Bugzilla Project that the documentation is ready in your language by sending a mail to
+the mailing-list ``developers AT bugzilla.org`` giving your project name, that is ``bugzilla-ab-CD``. They can
+then link your docs into the main Bugzilla docs so that they show up as an alternative language.

docs/en/rst/localizing/index.rst

+.. _l10n:
+
+==================
+Localization Guide
+==================
+
+Bugzilla's user interface can be localized into another language. This guide
+explains how to do that. It assumes you are using Linux or some other operating
+system with a Unix-like command line available.
+
+.. toctree::
+   :maxdepth: 2
+
+   get-the-source
+   files-to-be-localized
+   localizing-templates
+   caveats
+   checking-templates
+   localizing-bzlifecycle
+   localizing-documentation
+   compiling-documentation
+   shipping
+   hosting-documentation
+   up-to-date
+

docs/en/rst/localizing/localizing-bzlifecycle.rst

+.. _localizing-bzlifecycle:
+
+Localizing bzLifecycle.xml
+##########################
+
+.. image:: ../../images/bzLifecycle.png
+
+This picture shows the lifecycle of a bug through its different statuses and
+resolutions. This picture is included in the documentation. It was generated
+using `Dia <https://wiki.gnome.org/Apps/Dia>`_.
+
+To localize it, open the file :file:`docs/ab-CD/images/bzLifecycle.xml` with
+``Dia``, localize it and export it as a .png file by selecting the
+:guilabel:`Pixbuf[png] (*.png)` filter in the dropdown. You need to save it as
+:file:`docs/ab-CD/images/bzLifecycle.png`.

docs/en/rst/localizing/localizing-documentation.rst

+.. _localizing-documentation:
+
+Localizing The Documentation
+############################
+
+The Bugzilla documentation uses `reStructured Text (reST) <http://docutils.sourceforge.net/rst.html>`_,
+as extended by our documentation compilation tool, `Sphinx <http://sphinx-doc.org/>`_.
+
+`The Sphinx documentation <http://sphinx-doc.org/latest/rest.html>`_
+gives a good introduction to reST and the Sphinx-specific extensions. Reading
+that one immediately-linked page should be enough to get started. Later, the
+`inline markup section <http://sphinx-doc.org/latest/markup/inline.html>`_
+is worth a read.
+
+As with the template files, the ``.rst`` files should be localized using an UTF8 compliant editor.
+
+Spacing, blank lines and indentation are very important in reStructured Text, so be sure to follow exactly
+the pattern of the English, otherwise your localized version will not look the same as the English one.
+
+Though I recommend that you read the documents stated above, here are a few rules:
+
+.. raw:: html
+
+  <ul>
+    <li>In <code>index.rst</code> files, never localize what is under the <code>.. toctree::</code> directive: these are file names.</li>
+    <li>Never localize a term surrounded with a double dot and two colons. For instance: <code><mark>.. warning::</mark> <span class="green">This is a warning.</span></code>. This
+    will be automatically localized if necessary at compilation time. You can localize what is located after, in green in this example.</li>
+    <li>Exception: do not localize what is located after the directive <code>.. highlight:: console</code>. The word console here is for formatting purpose.</li>
+    <li>Do not localize a term surrounded with two colons or with the signs lesser than and greater than:
+    <code>:<mark>ref</mark>:`<span class="green">Démarrage rapide</span>&lt;<mark>quick-start</mark>&gt;`</code>. "ref" is a reserved word and "quick-start" is a file name. In the following syntax example, do not localize "using"
+    as it is also a file name: <code>:<mark>ref</mark>:`<mark>using</mark>`</code></li>
+  </ul>

docs/en/rst/localizing/localizing-templates.rst

+.. _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
+
+  <pre>
+  [% title = BLOCK %]<mark>Delete Component '</mark>[% comp.name FILTER html %]<mark>'
+  of Product '</mark>[% product.name FILTER html %]<mark>'</mark>
+    [% END %]
+
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  &lt;table border="1" cellpadding="4" cellspacing="0"&gt;
+  &lt;tr bgcolor="#6666FF"&gt;
+    &lt;th valign="top" align="left"&gt;<mark>Field</mark>&lt;/th&gt;
+    &lt;th valign="top" align="left"&gt;<mark>Value</mark>&lt;/th&gt;
+  &lt;/tr&gt;
+  </pre>
+
+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
+
+  <pre>
+  [% title = BLOCK %]<mark>Supprimer le composant « </mark>[% comp.name FILTER html %]<mark> »
+  du produit « </mark>[% product.name FILTER html %]<mark> »</mark>
+    [% END %]
+  
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  &lt;table border="1" cellpadding="4" cellspacing="0"&gt;
+  &lt;tr bgcolor="#6666FF"&gt;
+    &lt;th valign="top" align="left"&gt;<mark>Champ</mark>&lt;/th&gt;
+    &lt;th valign="top" align="left"&gt;<mark>Valeur</mark>&lt;/th&gt;
+  &lt;/tr&gt;
+  </pre>
+
+Another common occurrence in the templates is text enclosed between an opening
+and a closing tag, or in an HTML attribute value:
+
+.. raw:: html
+
+  <pre>
+  &lt;td valign="top"&gt;<mark>Description du produit :</mark>&lt;/td&gt;
+  
+  &lt;td valign="top"&gt;[% IF product.disallow_new %]<mark>Oui</mark>[% ELSE %]<mark>Non</mark>[% END %]&lt;/td&gt;
+  
+    &lt;a title="<mark>Liste des</mark> [% terms.bugs %] <mark>pour le composant « </mark>[% comp.name FILTER html %]<mark> »</mark>"
+       href="buglist.cgi?component=[% comp.name FILTER url_quote %]&amp;product=
+            [%- product.name FILTER url_quote %]"&gt;[% comp.bug_count %]&lt;/a&gt;
+  </pre>
+
+You will encounter many buttons you will want to localize. These look like this:
+
+.. raw:: html
+
+  <pre>
+    &lt;input type="submit" id="create" value="<mark>Add</mark>"&gt;
+    &lt;input type="hidden" name="action" value="new"&gt;
+    &lt;input type="hidden" name='product' value="[% product.name FILTER html %]"&gt;
+    &lt;input type="hidden" name="token" value="[% token FILTER html %]"&gt;
+  </pre>
+
+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
+
+  <pre>
+    &lt;input type="submit" id="create" value="<mark>Ajouter</mark>"&gt;
+    &lt;input type="hidden" name="action" value="new"&gt;
+    &lt;input type="hidden" name='product' value="[% product.name FILTER html %]"&gt;
+    &lt;input type="hidden" name="token" value="[% token FILTER html %]"&gt;
+  </pre>
+
+
+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
+ 
+  <pre>
+  [% terms = {
+    "bug" => "<mark>bug</mark>",
+    "Bug" => "<mark>Bug</mark>",
+    "abug" => "<mark>a bug</mark>",
+    "Abug" => "<mark>A bug</mark>",
+    "ABug" => "<mark>A Bug</mark>",
+    "bugs" => "<mark>bugs</mark>",
+    "Bugs" => "<mark>Bugs</mark>",
+    "zeroSearchResults" => "<mark>Zarro Boogs found</mark>",
+    "bit" => "<mark>bit</mark>",
+    "bits" => "<mark>bits</mark>",
+    "Bugzilla" => "<mark>Bugzilla</mark>"
+    }
+  %]
+  </pre>
+
+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.

docs/en/rst/localizing/shipping.rst

+.. _localizing-templates:
+
+Shipping
+########
+
+Once you have localized everything, you will want to ship it. The best way
+of doing this is still to create a tarball of all your files, which the
+Bugzilla administrator will untar in their ``$BUGZILLA_HOME`` directory.
+
+This command will find all of the files you've localized and put them into
+an appropriate tarball. Don't forget to replace both instances of ``ab-CD``:
+
+:command:`find -name "ab-CD" -print0 -o -path "./data" -prune | tar -cjvf ../bugzilla-ab-CD.tar.bz2 --null -T -`

docs/en/rst/localizing/up-to-date.rst

+.. _up-to-date:
+
+Keeping Templates and Documentation Up-To-Date
+##############################################
+
+Some localizers like to keep their locale up to date with the development
+trunk; others like to do all the work in one go when the software nears
+release. If you are of the former sort, you should watch the Bugzilla Git
+repositories to catch the changes in the files.
+
+To do so, you can subscribe to the Atom or RSS feeds that log every commit in the repositories.
+
+Different development branches of Bugzilla are referred to by the Git source control
+system in this context as ``heads``. The list of heads can be found
+on `the bottom of this page <http://git.mozilla.org/?p=bugzilla/bugzilla.git;a=summary>`_ in the
+"heads" section. The head named "master" is the current focus of Bugzilla development,
+and the place from which the next release will come.
+Click on the link of the version you want to watch. At the bottom right corner of the page that is
+then displayed, you will find the RSS or Atom link to subscribe to. An so, you will be noticed for each commit
+that happens on this head.