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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
.. _user-guide-i18n:
Internationalization
====================
This theme contains localizable (translatable) strings.
There are two kinds of strings in this theme, with different steps to translate each:
* **Built-in strings** are hard-coded in the theme's templates. They will be translated by volunteers if the language is `supported <https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/locale>`__.
To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-new-language` sections in the documentation.
* **Configurable strings** are user-defined with the ``html_theme_options`` variable in your ``conf.py`` file (see other
sections in :doc:`the user guide <index>` for examples of these configurable strings).
To translate these strings, see the :ref:`translating-configurable-strings` section in this page.
.. _translating-configurable-strings:
Translating configurable strings
--------------------------------
These instructions are for translating configurable strings (those that are customizable in ``html_theme_options`` within
the ``conf.py`` file).
These instructions assume that you store your translations in a ``locale`` directory under your documentation directory
and that you want to use ``messages`` as the name of the message catalog for these strings (you can change this name if
needed).
Note you will also need to install `pybabel <https://babel.pocoo.org/en/latest/installation.html>`__ to handle your
documentation translations.
#. In your ``conf.py`` file:
.. code-block:: python
import os.path
from sphinx.locale import get_translation
catalog = "messages"
_ = get_translation(catalog)
html_theme_options = {
"search_bar_text": _("Search the docs..."),
# You only need to translate the following if you use these features.
"icon_links_label": _("Quick Links"),
"icon_links": [
{
"name": _("GitHub"),
"url": "https://github.com/<your-org>/<your-repo>",
"icon": "fab fa-github-square",
},
],
"external_links": [
{
"name": _("link-one-name"),
"url": "https://<link-one>",
},
],
}
def setup(app):
locale_dir = os.path.join(os.path.abspath(os.path.dirname(__file__), "locale")
app.add_message_catalog(catalog, locale_dir)
#. Extract the strings to localize:
.. code-block:: bash
pybabel extract . -o locale/messages.pot
#. Create a message catalog by specifying the `ISO 639-1 code <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__ for the new language (using the ``--locale`` flag):
.. code-block:: bash
# for example, to add French (ISO 639-1 code: fr)
pybabel init --input-file=locale/messages.pot --domain=messages --output-dir=locale --locale=fr
#. Translate the message catalog by editing the file.
#. Compile the message catalog:
.. code-block:: bash
pybabel compile --directory=locale --domain=messages
Done! Your configurable strings are now localized.
|
