blob: 7d30fa1c80a43e468366fca5247f4beca71352b0 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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> This is a warning</code>. 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).</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>
|
