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 and Internationalization 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 Descoperire componente pentru a descoperi automat toate celelalte.

Configurația componentei

Nume componentă	Documentation
Mască de fișier	docs/locales/*/LC_MESSAGES/index.po
Șablon pentru traduceri noi	docs/locales/index.pot
Format fișier	gettext PO file
Indicarori traducere	rst-text

Configurația de descoperire a componentelor

Expresie regulată pentru a potrivi fișierele de traducere	docs/locales/(?P<limbă>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po`
Personalizează numele componentei	Documentație: {{ component|title }}
Definește fișierul de bază pentru traduceri noi	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:

• Documentația Weblate (o citiți acum)

• Documentația motorului Godot

• Șablon de documentare <https://doc.galette.eu/>

• Documentația phpMyAdmin <https://docs.phpmyadmin.net/>