--- /dev/null
+#!/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";
+}
administering/index
integrating/index
api/index
+ localizing/index
.. toctree::
:hidden:
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)'
'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)'`
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.
: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
--- /dev/null
+.. _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 > 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 %]
+ <li>
+ The account has been added to the
+ [%<mark>+</mark> groups_added_to.join(', ') FILTER html %]
+ group[% 's' IF groups_added_to.size > 1 %].
+ </li>
+ [% 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 > 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 > 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.
+ </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 > 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><br> " _
+ "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><br> " _
+ "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.
--- /dev/null
+.. _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...
--- /dev/null
+.. _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 <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation>`_.</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.
+
+
+
--- /dev/null
+.. _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.
--- /dev/null
+.. _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.
--- /dev/null
+.. _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.
--- /dev/null
+.. _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
+
--- /dev/null
+.. _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`.
--- /dev/null
+.. _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><<mark>quick-start</mark>>`</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>
--- /dev/null
+.. _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
+ %]
+
+ <table border="1" cellpadding="4" cellspacing="0">
+ <tr bgcolor="#6666FF">
+ <th valign="top" align="left"><mark>Field</mark></th>
+ <th valign="top" align="left"><mark>Value</mark></th>
+ </tr>
+ </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
+ %]
+
+ <table border="1" cellpadding="4" cellspacing="0">
+ <tr bgcolor="#6666FF">
+ <th valign="top" align="left"><mark>Champ</mark></th>
+ <th valign="top" align="left"><mark>Valeur</mark></th>
+ </tr>
+ </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>
+ <td valign="top"><mark>Description du produit :</mark></td>
+
+ <td valign="top">[% IF product.disallow_new %]<mark>Oui</mark>[% ELSE %]<mark>Non</mark>[% END %]</td>
+
+ <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 %]&product=
+ [%- product.name FILTER url_quote %]">[% comp.bug_count %]</a>
+ </pre>
+
+You will encounter many buttons you will want to localize. These look like this:
+
+.. raw:: html
+
+ <pre>
+ <input type="submit" id="create" value="<mark>Add</mark>">
+ <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 %]">
+ </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>
+ <input type="submit" id="create" value="<mark>Ajouter</mark>">
+ <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 %]">
+ </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.
--- /dev/null
+.. _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 -`
--- /dev/null
+.. _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.
projects / thirdparty / bugzilla.git / commitdiff
