Traducerea documentației folosind Sphinx

Sphinx este un instrument pentru crearea de documentație frumoasă. Folosește o sintaxă simplă reStructuredText și poate genera rezultate în mai multe formate. Dacă sunteți în căutarea unui exemplu, această documentație este, de asemenea, construită cu ajutorul lui. Însoțitorul foarte util pentru utilizarea Sphinx este serviciul Read the Docs, care va construi și va publica documentația dumneavoastră gratuit.

Nu mă voi concentra pe scrierea documentației în sine, dacă aveți nevoie de îndrumare în acest sens, urmați instrucțiunile de pe site-ul Sphinx. Odată ce documentația este gata, traducerea ei este destul de ușoară, deoarece Sphinx vine cu suport pentru acest lucru și este destul de bine acoperit în Internationalization. Este o chestiune de câteva directive de configurare și de invocare a instrumentului sphinx-intl.

Dacă utilizați serviciul Read the Docs, puteți începe să creați documentația tradusă pe pagina Read the Docs. Documentul lor Localization of Documentation acoperă cam tot ceea ce aveți nevoie - crearea unui alt proiect, setarea limbii acestuia și crearea unei legături cu proiectul principal ca traducere.

Acum tot ce trebuie să faceți este să traduceți conținutul documentației. Sphinx generează un fișier PO pentru fiecare director sau fișier de nivel superior, ceea ce poate duce la un număr destul de mare de fișiere de tradus (în funcție de setările gettext_compact). Puteți importa fișierul index.po în Weblate ca o componentă inițială și apoi să configurați add-onul Descoperirea componentelor pentru a descoperi automat toate celelalte.

Configurația componentei

Denumirea componentei

Documentation

Masca de fișier

docs/locales/*/LC_MESSAGES/index.po

Șablon pentru traduceri noi

docs/locales/index.pot

Formatul fișierului

gettext PO file

Indicarorii traducerii

rst-text

Configurația de descoperire a componentelor

Expresie regulată pentru a se potrivi cu fișierele de traducere

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

Personalizați numele componentei

Documentație: {{ component|title }}

Definiți fișierul de bază pentru noile traduceri

docs/locales/{{ component }}.pot

Sugestie

Ați prefera ca Sphinx să genereze doar un singur fișier PO? Începând cu Sphinx 3.3.0, puteți realiza acest lucru folosind:

gettext_compact = "docs"

Puteți găsi mai multe proiecte de documentare care sunt traduse folosind această abordare: