Добавление переключателя языка¶

Давайте создадим простой переключатель языков и добавим его на боковую панель. Мы также добавим стартовую страницу, содержащую ссылки на нашу документацию на разных языках.

Переключатель языка на боковой панели¶

Переключатель языка должен содержать все три языка: английский, русский и португальский. Текущий язык страницы должен отображаться в виде текста, а два других языка должны быть связаны с той же страницей на этих языках.

Например, переключатель языка на easter-egg.html на английском языке должен выглядеть так:

► English ¹

Русский ²

Português ³

Просто текст. Треугольник указывает текущий язык.
Ссылка на easter-egg.html на русском языке.
Ссылка на easter-egg.html на португальском языке.

Для переключателя языка мы будем использовать шаблоны Jinja. В нашем шаблоне используются две предопределенные переменные Jinja: pagename и language.

Добавьте переключатель языка в наш проект:

Создайте файл в кодировке UTF-8, назовите его switcher.html и поместите в него этот код:

<div class = "switcherheading">
{% set heading = {'en': 'Documentation language:',
                  'ru': 'Язык документации:',
                  'pt_BR': 'Idioma da documentação:'}
 %}

{{ heading[language] }}
</div>

<div class = "switcher">
{% for lcode, lname in [('en', 'English'),
                        ('ru', 'Русский'),
                        ('pt_BR', 'Português')]
 %}
        {% if language != lcode %}
        <a href = "../{{lcode}}/{{pagename}}.html">{{lname}}</a></br>
        {% else %}
        &#9654; {{lname}}</br>
        {% endif %}
{% endfor %}
</div>

Кроме того, вы можете загрузить switcher.html.

Поместите switcher.html в папку _templates; по умолчанию Sphinx ищет шаблоны Jinja в этой папке.
В соответствии с документацией Alabaster добавьте явный параметр html_sidebars в conf.py:
```
html_sidebars = {
        '**': [
                'about.html',
                'navigation.html',
                'switcher.html'
        ]
}
```
Я добавила switcher.html на боковую панель Alabaster по умолчанию и удалила элементы, которые нам не нужны (donate.html, relations.html и т. д.). Как обычно, вы можете скачать обновленный файл conf.py.

Теперь Sphinx будет использовать switcher.html для добавления переключателя языка на боковую панель каждой страницы документации.

После того, как вы пересоберете документацию, вы увидите только что добавленный переключатель языка:

Переключатель языка на странице index.html

Чтобы наш переключатель языков работал, документация для каждого языка должна быть помещена в папку, названную в соответствии с кодом языка, и эти папки должны быть на одном уровне вложенности, например:

<папка_документации>/en/<файлы_документации_на_английском>
<папка_документации>/ru/<файлы_документации_на_русском>
<папка_документации>/pt_BR/<файлы_документации_на_португальском>

Мы уже собрали нашу документацию таким образом.

Если вы используете аналогичный переключатель языка в своем проекте, обязательно сохраните структуру папок при выгрузке документации в Интернет.

Стартовая страница¶

Наша стартовая страница представляет собой простой HTML-файл, содержащий несколько ссылок и изображений.

Файл стартовой страницы с именем index.html содержит следующий код:

<!DOCTYPE html>
<html>
        <head>
                <title>PEP 20</title>
                <style>
                        .parent {
                                width: 100%;
                                height: 100%;
                                position: fixed;
                                top: 0;
                                left: 0;
                                display: flex;
                                align-items: center;
                                align-content: center;
                                justify-content: center;
                                overflow: auto;
                        }
                        .block {
                                margin-top: -20%;
                                img {
                                        display: block;
                                        border: none;
                                }
                        }
                        p {
                                font-family: sans-serif;
                        }
                        a {
                                text-decoration: none;
                                border-bottom: 1px dotted #004B6B;
                                color: #444;
                        }
                        a:hover {
                                border-bottom: 1px solid #6D4100;
                        }

                </style>
        </head>
        <body>
        <div class="parent">
                <div class="block">
                        <img src="img/logo_index.png" alt="PEP 20">
                        <p><img src="img/en.png" alt="PEP 20 EN"> <a href="en/index.html">The Zen of Python</a></p>
                        <p><img src="img/ru.png" alt="PEP 20 RU"> <a href="ru/index.html">Дзен Питона</a></p>
                        <p><img src="img/pt_BR.png" alt="PEP 20 PT_BR"> <a href="pt_BR/index.html">O Zen de Python</a></p>
                </div>
        </div>
        </body>
</html>

На стартовой странице используются четыре изображения:

logo_index.png для логотипа нашего проекта.
en.png для британского флага.
ru.png для российского флага.
pt_BR.png для бразильского флага.

Изображения должны быть размещены в каталоге img на том же уровне, что и файл index.html. Вы можете скачать index.html и каталог img, а затем поместить их в каталог _build/html нашей документации, вот так:

html
│   index.html
│
├───img
│       en.png
│       logo_index.png
│       pt_BR.png
│       ru.png

Вам не нужно пересобирать документацию после добавления стартовой страницы.

Добавление переключателя языка¶

Переключатель языка на боковой панели¶

Стартовая страница¶

sphinx-intl

Навигация