# Translating documentation using Sphinx

[Sphinx](https://www.sphinx-doc.org/) is a tool for creating beautiful documentation. It uses simple
reStructuredText syntax and can generate output in many formats. If you’re
looking for an example, this documentation is also built using it. The very
useful companion for using Sphinx is the [Read the Docs](https://about.readthedocs.com/) service, which will
build and publish your documentation for free.

I will not focus on writing documentation itself, if you need guidance with
that, just follow instructions on the [Sphinx](https://www.sphinx-doc.org/) website. Once you have
documentation ready, translating it is quite easy as Sphinx comes with support
for this and it is quite nicely covered in their [Internationalization](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#intl). It’s
matter of a few configuration directives and invoking the `sphinx-intl`
tool.

If you are using Read the Docs service, you can start building translated
documentation on Read the Docs. Their [Localization and Internationalization](https://docs.readthedocs.com/platform/latest/localization.html) covers pretty
much everything you need - creating another project, setting its language, and linking
it from the main project as a translation.

Now all you need is translating the documentation content. Sphinx generates PO
file for each directory or top-level file, which can lead to quite a lot of
files to translate (depending on [`gettext_compact`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-gettext_compact) settings).
You can import the `index.po` into Weblate as an initial component and
then configure [Otkrivanje komponenti](https://docs.weblate.org/hr/latest/admin/addons.md#addon-weblate-discovery-discovery) add-on to automatically
discover all others.

#### Konfiguracija komponente

| [Ime komponente](https://docs.weblate.org/hr/latest/admin/projects.md#component-name)                  | `Documentation`                       |
|-----------------------------------------------------------------------------------------------|---------------------------------------|
| [Maska datoteke](https://docs.weblate.org/hr/latest/admin/projects.md#component-filemask)              | `docs/locales/*/LC_MESSAGES/index.po` |
| [Predložak za nove prijevode](https://docs.weblate.org/hr/latest/admin/projects.md#component-new-base) | `docs/locales/index.pot`              |
| [Format datoteke](https://docs.weblate.org/hr/latest/admin/projects.md#component-file-format)          | gettext PO datoteka                   |
| [Prevodilačke oznake](https://docs.weblate.org/hr/latest/admin/projects.md#component-check-flags)      | `rst-text`                            |

#### Konfiguracija za otkrivanje komponenti

| Regularni izraz za usporedbu s prevodilačkim datotekama   | `docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po`   |
|-----------------------------------------------------------|----------------------------------------------------------------------------|
| Prilagodi ime komponente                                  | `Documentation: {{ component|title }}`                                     |
| Odredi osnovnu datoteku za nove prijevode                 | `docs/locales/{{ component }}.pot`                                         |

#### HINT
Želiš li radije da Sphinx generira samo jednu PO datoteku? Od Sphinx verzije 3.3.0 to možeš postići pomoću:

```python
gettext_compact = "docs"
```

Postoje nekoliko projekata dokumentacije koji se prevode koristeći ovaj pristup:

* [Weblate dokumentacija](https://docs.weblate.org/) (nju upravo čitaš)
* [Godot engine dokumentacija](https://docs.godotengine.org/en/stable/)
* [Gallette dokumentacija](https://doc.galette.eu/)
* [phpMyAdmin dokumentacija](https://docs.phpmyadmin.net/)