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

15 files changed, 936 insertions, 5 deletions

diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index b4ca1107e..4611178aa 100644
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -12,6 +12,7 @@ Bugzilla Documentation
    administering/index
    integrating/index
    api/index
+   localizing/index
    
 .. toctree::
    :hidden:
diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst
index 0dad2056e..58cf5cb5e 100644
--- a/docs/en/rst/installing/linux.rst
+++ b/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.
diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst
index ac1a9521a..848532a9d 100644
--- a/docs/en/rst/installing/quick-start.rst
+++ b/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
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
+
+  <pre>
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+      This [% terms.bug %] has been marked as a duplicate of <mark>[% terms.bug %] [% dupe_of FILTER html %]</mark>
+  </pre>
+
+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
+
+  <pre>
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+       This [% terms.bug %] has been marked as a duplicate of [% terms.bug %] [%<mark>+</mark> dupe_of FILTER html %]
+  </pre>
+
+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 %]
+            <li>
+              The account has been added to the
+              [% groups_added_to.join(', ') FILTER html %]
+              group[% 's' IF groups_added_to.size &gt; 1 %].
+            </li>
+          [% END %]
+
+will be shown as:
+
+.. code-block:: text
+
+  The account has been added to thebz_sudo_protect group.
+
+Again, insert a "+" sign:
+
+.. raw:: html
+
+  <pre>
+          [% IF groups_added_to.size %]
+            &lt;li&gt;
+              The account has been added to the
+              [%<mark>+</mark> groups_added_to.join(', ') FILTER html %]
+              group[% 's' IF groups_added_to.size &gt; 1 %].
+            &lt;/li&gt;
+          [% END %]
+  </pre>
+
+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 %]
+            <li>
+              Le compte a été ajouté
+              [% IF groups_added_to.size &gt; 1 %]
+              aux groupes[% ELSE %]au groupe[% END %][%+ groups_added_to.join(', ') FILTER html %].
+            </li>
+          [% END %]
+
+The browser would then display for one group:
+
+.. raw:: html
+
+  Le compte a été ajouté <mark>au groupe</mark> bz_sudo_protect
+
+And for several groups:
+
+.. raw:: html
+
+  Le compte a été ajouté <mark>aux groupes</mark> 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") %]
+    <p>
+      Sorry, there
+  
+      [% IF comp.bug_count &gt; 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 &gt; 1 %]
+         these [% terms.bugs %]
+      [% ELSE %]
+         this [% terms.bug %]
+      [% END %]
+  
+      to another component before deleting this component.
+    </p>
+    [% 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") %]
+    <p>
+      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 &gt; 1 %]
+         these [% terms.bugs %]
+      [% ELSE %]
+         this [% terms.bug %]
+      [% END %]
+  
+      to another component before deleting this component.
+    </p>
+    [% 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
+
+  <pre>
+    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de <mark>$terms.bug.</mark>&lt;br&gt; " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+  </pre>
+
+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
+
+  <pre>
+    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de <mark>${terms.bug}.</mark>&lt;br&gt; " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+  </pre>
+
+========
+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.
diff --git a/docs/en/rst/localizing/checking-templates.rst b/docs/en/rst/localizing/checking-templates.rst
new file mode 100644
index 000000000..0bd390c93
--- /dev/null
+++ b/docs/en/rst/localizing/checking-templates.rst
@@ -0,0 +1,73 @@
+.. _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...
diff --git a/docs/en/rst/localizing/compiling-documentation.rst b/docs/en/rst/localizing/compiling-documentation.rst
new file mode 100644
index 000000000..06f61709f
--- /dev/null
+++ b/docs/en/rst/localizing/compiling-documentation.rst
@@ -0,0 +1,112 @@
+.. _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.
+
+
+
diff --git a/docs/en/rst/localizing/files-to-be-localized.rst b/docs/en/rst/localizing/files-to-be-localized.rst
new file mode 100644
index 000000000..f25ce91e7
--- /dev/null
+++ b/docs/en/rst/localizing/files-to-be-localized.rst
@@ -0,0 +1,35 @@
+.. _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.
diff --git a/docs/en/rst/localizing/get-the-source.rst b/docs/en/rst/localizing/get-the-source.rst
new file mode 100644
index 000000000..d25f8266e
--- /dev/null
+++ b/docs/en/rst/localizing/get-the-source.rst
@@ -0,0 +1,57 @@
+.. _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.
diff --git a/docs/en/rst/localizing/hosting-documentation.rst b/docs/en/rst/localizing/hosting-documentation.rst
new file mode 100644
index 000000000..0bf4e8df8
--- /dev/null
+++ b/docs/en/rst/localizing/hosting-documentation.rst
@@ -0,0 +1,96 @@
+.. _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.
diff --git a/docs/en/rst/localizing/index.rst b/docs/en/rst/localizing/index.rst
new file mode 100644
index 000000000..18c5e7381
--- /dev/null
+++ b/docs/en/rst/localizing/index.rst
@@ -0,0 +1,25 @@
+.. _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
+
diff --git a/docs/en/rst/localizing/localizing-bzlifecycle.rst b/docs/en/rst/localizing/localizing-bzlifecycle.rst
new file mode 100644
index 000000000..71d569f8b
--- /dev/null
+++ b/docs/en/rst/localizing/localizing-bzlifecycle.rst
@@ -0,0 +1,15 @@
+.. _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`.
diff --git a/docs/en/rst/localizing/localizing-documentation.rst b/docs/en/rst/localizing/localizing-documentation.rst
new file mode 100644
index 000000000..593bcd4d1
--- /dev/null
+++ b/docs/en/rst/localizing/localizing-documentation.rst
@@ -0,0 +1,32 @@
+.. _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>
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
+
+  <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.
diff --git a/docs/en/rst/localizing/shipping.rst b/docs/en/rst/localizing/shipping.rst
new file mode 100644
index 000000000..556d88114
--- /dev/null
+++ b/docs/en/rst/localizing/shipping.rst
@@ -0,0 +1,13 @@
+.. _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 -`
diff --git a/docs/en/rst/localizing/up-to-date.rst b/docs/en/rst/localizing/up-to-date.rst
new file mode 100644
index 000000000..bed612371
--- /dev/null
+++ b/docs/en/rst/localizing/up-to-date.rst
@@ -0,0 +1,20 @@
+.. _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.