7.7. 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:

  • 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 any text that comes after ("This is a warning" 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`