From 7321534b42aab3ab2064c73b6326d52f395f023c Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Wed, 30 Sep 2015 09:03:22 +0100 Subject: Bug 1156785 - add new Localization Guide for in-place review. --- contrib/new-locale.pl | 19 ++ docs/en/images/RTD1.png | Bin 0 -> 102100 bytes docs/en/images/RTD10.png | Bin 0 -> 38912 bytes docs/en/images/RTD2.png | Bin 0 -> 84061 bytes docs/en/images/RTD3.png | Bin 0 -> 158345 bytes docs/en/images/RTD4.png | Bin 0 -> 127351 bytes docs/en/images/RTD5.png | Bin 0 -> 252238 bytes docs/en/images/RTD6.png | Bin 0 -> 52782 bytes docs/en/images/RTD7.png | Bin 0 -> 20628 bytes docs/en/images/RTD8.png | Bin 0 -> 85173 bytes docs/en/images/RTD9.png | Bin 0 -> 126453 bytes docs/en/rst/index.rst | 1 + docs/en/rst/installing/linux.rst | 8 +- docs/en/rst/installing/quick-start.rst | 2 +- docs/en/rst/localizing/caveats.rst | 308 +++++++++++++++++++++ docs/en/rst/localizing/checking-templates.rst | 73 +++++ docs/en/rst/localizing/compiling-documentation.rst | 112 ++++++++ docs/en/rst/localizing/files-to-be-localized.rst | 35 +++ docs/en/rst/localizing/get-the-source.rst | 57 ++++ docs/en/rst/localizing/hosting-documentation.rst | 96 +++++++ docs/en/rst/localizing/index.rst | 25 ++ docs/en/rst/localizing/localizing-bzlifecycle.rst | 15 + .../en/rst/localizing/localizing-documentation.rst | 32 +++ docs/en/rst/localizing/localizing-templates.rst | 144 ++++++++++ docs/en/rst/localizing/shipping.rst | 13 + docs/en/rst/localizing/up-to-date.rst | 20 ++ 26 files changed, 955 insertions(+), 5 deletions(-) create mode 100755 contrib/new-locale.pl create mode 100644 docs/en/images/RTD1.png create mode 100644 docs/en/images/RTD10.png create mode 100644 docs/en/images/RTD2.png create mode 100644 docs/en/images/RTD3.png create mode 100644 docs/en/images/RTD4.png create mode 100644 docs/en/images/RTD5.png create mode 100644 docs/en/images/RTD6.png create mode 100644 docs/en/images/RTD7.png create mode 100644 docs/en/images/RTD8.png create mode 100644 docs/en/images/RTD9.png create mode 100644 docs/en/rst/localizing/caveats.rst create mode 100644 docs/en/rst/localizing/checking-templates.rst create mode 100644 docs/en/rst/localizing/compiling-documentation.rst create mode 100644 docs/en/rst/localizing/files-to-be-localized.rst create mode 100644 docs/en/rst/localizing/get-the-source.rst create mode 100644 docs/en/rst/localizing/hosting-documentation.rst create mode 100644 docs/en/rst/localizing/index.rst create mode 100644 docs/en/rst/localizing/localizing-bzlifecycle.rst create mode 100644 docs/en/rst/localizing/localizing-documentation.rst create mode 100644 docs/en/rst/localizing/localizing-templates.rst create mode 100644 docs/en/rst/localizing/shipping.rst create mode 100644 docs/en/rst/localizing/up-to-date.rst diff --git a/contrib/new-locale.pl b/contrib/new-locale.pl new file mode 100755 index 000000000..a2feb3dda --- /dev/null +++ b/contrib/new-locale.pl @@ -0,0 +1,19 @@ +#!/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 \n"; + print " e.g.: new-locale.pl fr\n"; +} diff --git a/docs/en/images/RTD1.png b/docs/en/images/RTD1.png new file mode 100644 index 000000000..04c8c7308 Binary files /dev/null and b/docs/en/images/RTD1.png differ diff --git a/docs/en/images/RTD10.png b/docs/en/images/RTD10.png new file mode 100644 index 000000000..74c599412 Binary files /dev/null and b/docs/en/images/RTD10.png differ diff --git a/docs/en/images/RTD2.png b/docs/en/images/RTD2.png new file mode 100644 index 000000000..adb5c1416 Binary files /dev/null and b/docs/en/images/RTD2.png differ diff --git a/docs/en/images/RTD3.png b/docs/en/images/RTD3.png new file mode 100644 index 000000000..4c6816d1e Binary files /dev/null and b/docs/en/images/RTD3.png differ diff --git a/docs/en/images/RTD4.png b/docs/en/images/RTD4.png new file mode 100644 index 000000000..2f1ab8bf9 Binary files /dev/null and b/docs/en/images/RTD4.png differ diff --git a/docs/en/images/RTD5.png b/docs/en/images/RTD5.png new file mode 100644 index 000000000..e4612ec20 Binary files /dev/null and b/docs/en/images/RTD5.png differ diff --git a/docs/en/images/RTD6.png b/docs/en/images/RTD6.png new file mode 100644 index 000000000..c204c03bf Binary files /dev/null and b/docs/en/images/RTD6.png differ diff --git a/docs/en/images/RTD7.png b/docs/en/images/RTD7.png new file mode 100644 index 000000000..ceaec2920 Binary files /dev/null and b/docs/en/images/RTD7.png differ diff --git a/docs/en/images/RTD8.png b/docs/en/images/RTD8.png new file mode 100644 index 000000000..ab135948e Binary files /dev/null and b/docs/en/images/RTD8.png differ diff --git a/docs/en/images/RTD9.png b/docs/en/images/RTD9.png new file mode 100644 index 000000000..25431bed6 Binary files /dev/null and b/docs/en/images/RTD9.png differ 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 + + 
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+      This [% terms.bug %] has been marked as a duplicate of [% terms.bug %] [% dupe_of FILTER html %]
+
+ +will display in the browser as: + +.. code-block:: text + + This bug has been marked as duplicate of bug12345 + +To preserve whitespace, you should add a "+" sign inside the second member: + +.. raw:: html + + 
+    [% ELSIF message_tag == "bug_duplicate_of" %]
+       This [% terms.bug %] has been marked as a duplicate of [% terms.bug %] [%+ dupe_of FILTER html %]
+
+ +Will then be displayed as: + +.. code-block:: text + + This bug has been marked as duplicate of bug 12345 + +This is the same when a [% %] member is at the beginning of a new line. These +lines of template code: + +.. code-block:: text + + [% IF groups_added_to.size %] +
  • + The account has been added to the + [% groups_added_to.join(', ') FILTER html %] + group[% 's' IF groups_added_to.size > 1 %]. +
    • + [% END %] + +will be shown as: + +.. code-block:: text + + The account has been added to thebz_sudo_protect group. + +Again, insert a "+" sign: + +.. raw:: html + + 
    +          [% IF groups_added_to.size %]
+            <li>
+              The account has been added to the
+              [%+ groups_added_to.join(', ') FILTER html %]
+              group[% 's' IF groups_added_to.size > 1 %].
+            </li>
+          [% END %]
+
    + +So that the sentence is displayed as: + +.. code-block:: text + + The account has been added to the bz_sudo_protect group. + +Sometimes, pluralization is dealt with using explicit Template Toolkit code, +which needs to be altered for your language. + +For example, if one wanted to localize the previous example into French, +the words order would not be not correct and the markup has to be rearranged. +The member ``[% groups_added_to.join(', ') FILTER html %]`` will actually display +the name of one group or several group names separated with a comma and a space (', '). +The member ``[% 's' IF groups_added_to.size > 1 %]`` will add an "s" +to the word "group" if there is more than one. In French, the group name should be put +after the term "group" and words need to be declensed when plural is used. That +would give for instance the following: + +.. code-block:: text + + [% IF groups_added_to.size %] +
  • + Le compte a été ajouté + [% IF groups_added_to.size > 1 %] + aux groupes[% ELSE %]au groupe[% END %][%+ groups_added_to.join(', ') FILTER html %]. +
    • + [% END %] + +The browser would then display for one group: + +.. raw:: html + + Le compte a été ajouté au groupe bz_sudo_protect + +And for several groups: + +.. raw:: html + + Le compte a été ajouté aux groupes bz_sudo_protect, canconfirm, editbugs + +=============================== +Double quotes and single quotes +=============================== + +Template Toolkit strings in directives are quote-delimited, and can use either +single or double quotes. But, obviously, you can't put double quotes inside +a double-quoted string. The following example will break the user interface: + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = "Click here if the page "does not" redisplay automatically." %] + + +Instead, you can escape them with a backslash ("\"): + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = "Click here if the page \"does not\" redisplay automatically." %] + + +Or you can substitute the surrounding double quotes with single quotes: + +.. code-block:: text + + [% ELSIF message_tag == "buglist_adding_field" %] + [% title = "Adding field to search page..." %] + [% link = 'Click here if the page "does not" redisplay automatically.' %] + +=========== +Declensions +=========== + +English only deals with one plural form and has no declension. Your locale +might need to implement declensions, and reorder words inside a sentence. + +Let's say we have the following: + +.. code-block:: text + + [% IF !Param("allowbugdeletion") %] +

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

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

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

    + [% ELSE %] + +========== +$terms.foo +========== + +As seen previously, term substitutions can be made across all template files. +Such substitutions are defined in ``*.none.tmpl`` files, which are: + +* template/en/default/global/field-descs.none.tmpl +* template/en/default/global/variables.none.tmpl +* template/en/default/global/value-descs.none.tmpl +* template/en/default/global/reason-descs.none.tmpl +* template/en/default/global/setting-descs.none.tmpl +* template/en/default/bug/field-help.none.tmpl + +These variables appear in the template files under three different forms. +``[% terms.foo %]`` is the standard, simple substitution of a term into a run +of text. ``$terms.foo`` is used when substituting into a Template Toolkit +string, and ``${terms.foo}`` is used when you need to separate the variable +name from the surrounding content to resolve ambiguity. + +To illustrate this last point: during your localizing contribution, you may +have to reorganize sentences, and sometimes a variable of the form +``$terms.foo`` will come at the end of a sentence which ends with a full stop, +like this: + +.. raw:: html + + 
    +    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de $terms.bug.<br> " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+
    + +If you leave it like that, the substitution would not take place and the +result in the user interface would be wrong. Instead, change the form +``$terms.foo`` into the form ``${terms.foo}``, like this: + +.. raw:: html + + 
    +    defaultplatform => "Plateforme qui est pré-sélectionnée dans le formulaire de soumission " _
+                       "de ${terms.bug}.<br> " _
+                       "Vous pouvez laisser ce champ vide : " _
+                       "Bugzilla utilisera alors la plateforme indiquée par le navigateur.",
+
    + +======== +b[% %]ug +======== + +Once and a while you would find something like: + +.. code-block:: text + + A b[% %]ug on b[% %]ugs.debian.org. + +You remember that the file :file:`variables.none.tmpl` holds the substitutions +for different terms. The release process of Bugzilla has a script that +parses all the templates to check if you wrote the bare word "bug" instead of +"$terms.bug" or similar, to make sure that this feature keeps working. + +In the example above, we really want to write the term "bug" and we neither +want it to be substituted afterwards nor be warned by the test script. + +This check only looks at the English terms bug, bugs, and Bugzilla, so you can +safely ignore the ``[% %]`` and localize ``b[% %]ug``, but you would keep +``b[% %]ugs.debian.org`` unchanged as it's a URL. 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 + + 
    +  t/004template.t .. ok         
+  All tests successful.
+  Files=1, Tests=1236,  5 wallclock secs ( 0.11 usr  0.00 sys +  4.70 cusr  0.05 csys =  4.86 CPU)
+  Result: PASS
+
    + +If something went wrong, you will see something like this: + +.. raw:: html + + 
    +  #   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
+  -------------------
+  t/004template.t (Wstat: 256 Tests: 1236 Failed: 1)
+    Failed test:  671
+    Non-zero exit status: 1
+  Files=1, Tests=1236,  4 wallclock secs ( 0.09 usr  0.01 sys +  4.74 cusr  0.04 csys =  4.88 CPU)
+  Result: FAIL
+
    + +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 + + 
    +  # General information about the project.
+  project = u'Bugzilla'
+  copyright = u'2014, The Bugzilla Team'
+
    + +.. raw:: html + + 
    latex_documents = [
+    ('index', 'Bugzilla.tex', u'Bugzilla Documentation',
+     u'The Bugzilla Team', 'manual'),
+  ]
+
    + +.. raw:: html + + 
    +  man_pages = [
+      ('index', 'bugzilla', u'Bugzilla Documentation',
+       [u'The Bugzilla Team'], 1)
+  ]
+
    + +.. raw:: html + + 
    +  texinfo_documents = [
+    ('index', 'Bugzilla', u'Bugzilla Documentation',
+     u'The Bugzilla Team', 'Bugzilla', 'One line description of project.',
+     'Miscellaneous'),
+  ]
+
    + +.. raw:: html + + 
    +  pdf_documents = [
+  ('index', u'Bugzilla', u'Bugzilla Documentation', u'The Bugzilla Team'),
+  ]
+
    + +.. raw:: html + + 
    +  rst_epilog = u"""
+  
+  ----------
+  
+  This documentation undoubtedly has bugs; if you find some, please file
+  them `here <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation>`_.
+  """
+
    + +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 `_) +then you should uncomment the line and specify your locale code here: + +.. raw:: html + + 
    +  # The language for content autogenerated by Sphinx. Refer to documentation
+  # for a list of supported languages.
+  language = 'fr'
+
    + +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 `_ + 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 `_, + 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 `_. 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 + + 
    +  |-- Bugzilla
+  |-- contrib
+  |-- docs
+  |   `-- en
+  |-- extensions
+  |   |-- BmpConvert
+  |   |-- Example
+  |   |   |-- docs
+  |   |   |   `-- en
+  |   |   |-- lib
+  |   |   `-- template
+  |   |       `-- en
+  |   |-- MoreBugUrl
+  |   |   |-- lib
+  |   |   `-- template
+  |   |       `-- en
+  |   `-- Voting
+  |       |-- template
+  |       |   `-- en
+  |-- images
+  |-- js
+  |-- template
+  |   `-- en
+  | ...
+
    + +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 `_. +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 `_ 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 `_ or `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 `_ 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 `_. + +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) `_, +as extended by our documentation compilation tool, `Sphinx `_. + +`The Sphinx documentation `_ +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 `_ +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 + +
      +
    • In index.rst files, never localize what is under the .. toctree:: directive: these are file names.
      • +
    • Never localize a term surrounded with a double dot and two colons. For instance: .. warning:: This is a warning.. This + will be automatically localized if necessary at compilation time. You can localize what is located after, in green in this example.
      • +
    • Exception: do not localize what is located after the directive .. highlight:: console. The word console here is for formatting purpose.
      • +
    • Do not localize a term surrounded with two colons or with the signs lesser than and greater than: + :ref:`Démarrage rapide<quick-start>`. "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: :ref:`using`
      • +
    diff --git a/docs/en/rst/localizing/localizing-templates.rst b/docs/en/rst/localizing/localizing-templates.rst new file mode 100644 index 000000000..f66b8e07b --- /dev/null +++ b/docs/en/rst/localizing/localizing-templates.rst @@ -0,0 +1,144 @@ +.. _localizing-templates: + +Localizing The Templates +######################## + +.. note:: Use an UTF-8-compliant editor, like Gedit, Kate or Emacs under + GNU/Linux systems or Notepad++ under Windows systems, and make sure + you save the templates using the UTF-8 encoding. + +Templates contain both code and localizable strings mixed together. So the +question arises: what is to be localized and what is not? Here are some +examples to help you localize the correct parts of each file. + +You can see at the top of each template file lines like these: + +.. code-block:: text + + [%# This Source Code Form is subject to the terms of the Mozilla Public + # License, v. 2.0. If a copy of the MPL was not distributed with this + # file, You can obtain one at http://mozilla.org/MPL/2.0/. + # + # This Source Code Form is "Incompatible With Secondary Licenses", as + # defined by the Mozilla Public License, v. 2.0. + #%] + +DO NOT translate any text located between ``[%#`` and ``#%]``. Such text is a +comment. + +Here are some examples of what does need to be translated: + +.. raw:: html + + 
    +  [% title = BLOCK %]Delete Component '[% comp.name FILTER html %]'
+  of Product '[% product.name FILTER html %]'
+    [% END %]
+
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  <table border="1" cellpadding="4" cellspacing="0">
+  <tr bgcolor="#6666FF">
+    <th valign="top" align="left">Field</th>
+    <th valign="top" align="left">Value</th>
+  </tr>
+
    + +As a general rule, never +translate capitalized words enclosed between ``[%`` and ``%]`` - these are +Template Toolkit directives. Here is the localized version of the above: + +.. raw:: html + + 
    +  [% title = BLOCK %]Supprimer le composant « [% comp.name FILTER html %] »
+  du produit « [% product.name FILTER html %] »
+    [% END %]
+  
+  [% PROCESS global/header.html.tmpl
+    title = title
+  %]
+  
+  <table border="1" cellpadding="4" cellspacing="0">
+  <tr bgcolor="#6666FF">
+    <th valign="top" align="left">Champ</th>
+    <th valign="top" align="left">Valeur</th>
+  </tr>
+
    + +Another common occurrence in the templates is text enclosed between an opening +and a closing tag, or in an HTML attribute value: + +.. raw:: html + + 
    +  <td valign="top">Description du produit :</td>
+  
+  <td valign="top">[% IF product.disallow_new %]Oui[% ELSE %]Non[% END %]</td>
+  
+    <a title="Liste des [% terms.bugs %] pour le composant « [% comp.name FILTER html %] »"
+       href="buglist.cgi?component=[% comp.name FILTER url_quote %]&product=
+            [%- product.name FILTER url_quote %]">[% comp.bug_count %]</a>
+
    + +You will encounter many buttons you will want to localize. These look like this: + +.. raw:: html + + 
    +    <input type="submit" id="create" value="Add">
+    <input type="hidden" name="action" value="new">
+    <input type="hidden" name='product' value="[% product.name FILTER html %]">
+    <input type="hidden" name="token" value="[% token FILTER html %]">
+
    + +Whenever you see this, the only line that needs to be localized is the one +with ``type="submit"``. DO NOT translate lines with ``type="hidden"``: + +.. raw:: html + + 
    +    <input type="submit" id="create" value="Ajouter">
+    <input type="hidden" name="action" value="new">
+    <input type="hidden" name='product' value="[% product.name FILTER html %]">
+    <input type="hidden" name="token" value="[% token FILTER html %]">
+
    + + +Some of the templates are a bit special. One such is +:file:`/template/en/default/global/variables.none.tmpl`. +This file contains several terms that are be substituted all around the +template files. In particular, it contains code so the administrator can easily and +consistently use whatever alternative term their organization uses for "bug" +and also for "Bugzilla" (i.e. the name of the system). Whenever you see expressions like +``&terms.ABug`` or ``&terms.bugs`` in templates, they will be replaced in the +user interface with the corresponding value from this file. + +As these are commonly-requested changes, you probably want to retain this +flexibility in your localization, although you may have to alter exactly how +it works if your language does not have exact equivalents for "a" and "the". + +.. raw:: html + + 
    +  [% terms = {
+    "bug" => "bug",
+    "Bug" => "Bug",
+    "abug" => "a bug",
+    "Abug" => "A bug",
+    "ABug" => "A Bug",
+    "bugs" => "bugs",
+    "Bugs" => "Bugs",
+    "zeroSearchResults" => "Zarro Boogs found",
+    "bit" => "bit",
+    "bits" => "bits",
+    "Bugzilla" => "Bugzilla"
+    }
+  %]
+
    + +You need to come up with an equivalent set of mappings for your language, and +then whenever you are talking about bugs in the user interface, use your +equivalent of ``&terms.ABug`` or ``&terms.bugs`` and friends instead. 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 `_ 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. -- cgit v1.2.3-24-g4f1b