diff options
Diffstat (limited to 'docs/en/rst')
| -rw-r--r-- | docs/en/rst/index.rst | 1 | ||||
| -rw-r--r-- | docs/en/rst/installing/linux.rst | 8 | ||||
| -rw-r--r-- | docs/en/rst/installing/quick-start.rst | 2 | ||||
| -rw-r--r-- | docs/en/rst/localizing/caveats.rst | 308 | ||||
| -rw-r--r-- | docs/en/rst/localizing/checking-templates.rst | 73 | ||||
| -rw-r--r-- | docs/en/rst/localizing/compiling-documentation.rst | 112 | ||||
| -rw-r--r-- | docs/en/rst/localizing/files-to-be-localized.rst | 35 | ||||
| -rw-r--r-- | docs/en/rst/localizing/get-the-source.rst | 57 | ||||
| -rw-r--r-- | docs/en/rst/localizing/hosting-documentation.rst | 96 | ||||
| -rw-r--r-- | docs/en/rst/localizing/index.rst | 25 | ||||
| -rw-r--r-- | docs/en/rst/localizing/localizing-bzlifecycle.rst | 15 | ||||
| -rw-r--r-- | docs/en/rst/localizing/localizing-documentation.rst | 32 | ||||
| -rw-r--r-- | docs/en/rst/localizing/localizing-templates.rst | 144 | ||||
| -rw-r--r-- | docs/en/rst/localizing/shipping.rst | 13 | ||||
| -rw-r--r-- | docs/en/rst/localizing/up-to-date.rst | 20 |
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 > 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. 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 <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. + + + 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><<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> 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 + %] + + <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. 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. |