7.8. 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 for the template files, the .rst files should be localized using an UTF8 compliant editor.

First copy the docs/en directory and rename it with your locale code. You can now start to localize the files.

Spacing, blank lines and indentation are very important in reStructured Text, so be sure to follow exactly the English pattern, otherwise, your localized version will not look the same as the English one and the layout might be very, very different.

Though I recommend you to read the documents stated above, here are a few rules:

  • 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`

This documentation undoubtedly has bugs; if you find some, please file them here.

Previous topic

7.7. Keeping Templates And Documentation Up-to-date

Next topic

7.9. Compiling The Documentation