Dokumentáció fordítása Sphinx használatával

A Sphinx egy eszköz látványos dokumentációk létrehozására. Egyszerű reStructuredText szintaxist használ, és számos kimeneti formátumot támogat. Ha példát keres, akkor jó tudni, hogy ez a dokumentáció is Sphinx segítségével készült. A Sphinx kiváló kiegészítője a Read the Docs szolgáltatás, amely ingyenesen építi és közzéteszi a dokumentációját.

Magának a dokumentációnak az írására most nem térünk ki — ehhez kövesse a Sphinx weboldalán található útmutatót. Ha a dokumentáció elkészült, annak fordítása viszonylag egyszerű, mivel a Sphinx beépített támogatással rendelkezik ehhez, amit a Internationalization rész jól lefed. Ehhez csupán néhány konfigurációs direktívára és a sphinx-intl eszköz futtatására van szükség.

Ha a Read the Docs szolgáltatást használja, ott el is indíthatja a lefordított dokumentáció építését. Az ő Localization and Internationalization szakaszuk gyakorlatilag mindent lefed: új projekt létrehozása, nyelv beállítása, majd összekapcsolása a fő projekttel, mint fordítás.

Ezután már csak a dokumentáció tartalmát kell lefordítani. A Sphinx minden könyvtárhoz vagy felső szintű fájlhoz külön PO-fájlt generál, ami a gettext_compact beállítástól függően sok fájlt is jelenthet. Az index.po fájlt importálhatja a Weblate-be kezdeti összetevőként, majd az Összetevők felismerése kiegészítővel automatikusan felismerheti a többit.

Összetevőkonfiguráció

Összetevő neve

Documentation

Fájlmaszk

docs/locales/*/LC_MESSAGES/index.po

Sablon az új fordításokhoz

docs/locales/index.pot

Fájlformátum

gettext PO-fájl

Fordítási jelzők

rst-text
Összetevő-felismerés konfigurálása

Reguláris kifejezés, amellyel a fordítási fájlokat egyezteti

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

Az összetevő nevének testreszabása

Documentation: {{ component|title }}

Új fordítások alapfájljának meghatározása

docs/locales/{{ component }}.pot

Tipp

Szeretné, ha a Sphinx csak egyetlen PO-fájlt generálna? A Sphinx 3.3.0 verziójától ez már lehetséges az alábbi beállítással:

gettext_compact = "docs"

Számos dokumentációs projekt is létezik, amelyek fordítása ezen a módon történik: