Sari la conținut

Tradu mesaje complete
cu t-stringuri Python

gettext-tstrings leagă t-stringurile din Python 3.14+ de cataloagele gettext standard și de uneltele Babel. Valorile și formatarea rămân în codul aplicației; traducătorii lucrează cu mesaje complete și cu substituenți simpli {name}:

import gettext

from gettext_tstrings import Translator

_ = Translator(gettext.translation("messages", localedir="locales"))
name = "Ada"
print(_(t"Hello {name}"))  # with a Japanese catalog: こんにちは Ada

Catalogul conține Hello {name}. O traducere poate muta sau repeta {name}. Dacă elimină, redenumește sau reformatează substituentul, validarea catalogului semnalează eroarea. Dacă o intrare invalidă ajunge totuși în producție, biblioteca jurnalizează un avertisment și randează mesajul sursă, în loc să cadă.

Începe tutorialul de cinci minute Compară alternativele

Alpha · Python 3.14+ · cataloage PO/MO standard · fără dependențe terțe la rulare

Acest sit practică ceea ce documentează: fiecare ediție lingvistică — navigarea, etichetele și raportul de build conștient de plural — este randată din cataloage PO de gettext-tstrings însuși.

Este pentru tine?

Se potrivește astăzi dacă aplicația ta rulează pe Python 3.14 sau mai nou; folosești deja gettext și Babel, sau vrei să le adopți fluxul PO/MO; și vrei sintaxă de t-string cu substituenți denumiți, verificați înainte de a fi randați.

Nu se potrivește încă dacă ai nevoie de Python 3.13 sau mai vechi; îți trebuie un API Python stabil — acesta este un alpha, iar specificația este partea lui care s-a așezat; sau dacă aproape tot textul tău traductibil trăiește într-un limbaj de șabloane, nu în sursă Python.

Ai deja cataloage? Ele continuă să funcționeze. _("Hello {name}").format(name=name) și tr(t"Hello {name}") produc același msgid, așa că traducerile existente supraviețuiesc trecerii — Migrare parcurge toată mutarea.

Ce poate spune catalogul

O traducere nu poate schimba structura mesajului pe care îl traduce. Aceasta este toată promisiunea, iar restul sitului decurge din ea. O traducere poate reordona sau repeta {name} și poate rescrie fiecare alt cuvânt din jurul lui. Ea nu poate elimina substituentul, nu poate inventa unul nou, nu poate ajunge prin el la obiectele tale și nu îi poate atașa formatare proprie.

Biblioteca verifică asta la intrare — când sunt compilate cataloagele — și încă o dată la randare, ceea ce face diferența dintre o greșeală găsită la recenzie și una găsită de un utilizator.

Nou la gettext? Întregul flux în patru propoziții

gettext este modul standard în care software-ul ajunge să fie tradus, în Python și cu mult dincolo de el. Codul tău marchează mesajele traductibile; un extractor le adună într-un fișier șablon (.pot); un traducător — de obicei nu un programator — completează câte un fișier catalog (.po) pe limbă, care este compilat într-un .mo binar pe care aplicația ta îl încarcă la rulare. Numele convențional al funcției de traducere este _, așa că _(t"Hello {name}") se citește ca „tradu mesajul acesta”. Tutorialul parcurge întregul drum — marchează, extrage, tradu, compilează, rulează — în vreo cinci minute.

Problema pe care o rezolvă

Un f-string este deja interpolat până când vreo bibliotecă apucă să îl vadă — f"Hello {name}" a devenit "Hello Ada", iar traducerea fragmentelor din jurul unei valori strică gramatica majorității limbilor. Un t-string (PEP 750) ține separate textul static, valorile evaluate, expresiile sursă, conversiile și specificațiile de format — exact împărțirea de care are nevoie un catalog de mesaje. Ce schimbă asta, în comparație cu %(name)s, .format() și $-stringurile.

Nimic din gettext sau Babel nu spune însă cum devine un t-string un mesaj. Biblioteca de față face acea alegere, o consemnează ca specificație versionată și livrează suita de conformitate care o verifică.

Regulile de proiectare

  • Traduce mesaje complete, niciodată fragmente de propoziție.
  • Acceptă doar nume simple de variabile, precum {name}.
  • Ține !r și :.2f sub controlul aplicației, în afara catalogului.
  • Permite traducerilor să reordoneze și să repete substituenții cunoscuți, împiedicându-le totodată să ajungă la atribute sau să adauge formatare.
  • Reutilizează fișiere POT, PO și MO obișnuite, și uneltele care le citesc deja.

Și lista pe potrivă a ceea ce lasă în mod deliberat în pace: nu localizează numere, monede sau date — formatează-le întâi, cu Babel; nu escapează ieșirea randată pentru HTML, un shell sau un terminal; și nu poate judeca dacă o traducere este corectă, ci doar dacă substituenții ei sunt intacți.

Instalare

python -m pip install gettext-tstrings

Python 3.14 sau mai nou. Randarea nu are dependențe — folosește gettext din biblioteca standard și nimic altceva.

Extragerea și validarea cataloagelor trec prin Babel, așa că instalează acel extra oriunde rulează pybabel, ceea ce înseamnă de obicei un mediu de dezvoltare sau de CI, mai degrabă decât o imagine de producție:

python -m pip install "gettext-tstrings[babel]"

Încotro mai departe

Începe aici — fără a presupune experiență cu gettext:

  • Tutorial — de la un director gol la o traducere japoneză care rulează, în cinci pași, fiecare comandă arătată cu ieșirea ei.
  • De ce t-stringuri — același mesaj scris în patru feluri, și ce anume dau catalogului %(name)s, .format() și $-stringurile.

Folosește-l — referințele de lucru:

  • Ghid — API-ul de rulare: ce punct de intrare să folosești, plural, limbi per cerere, șiruri amânate și ce se întâmplă când un catalog este greșit.
  • Extragere — referința pybabel: configurare, nume proprii de funcții și felul în care uneltele existente validează gratuit aceste cataloage.
  • În producție — bucla așa cum o rulează o echipă: ciclul de actualizare, intrările fuzzy, porțile de CI, platformele de traducere și livrarea.
  • Migrare — adoptarea acestei biblioteci într-un proiect care are deja cataloage, un loc de apel pe rând.
  • Pentru traducători — o singură pagină de dat celui care editează fișierele .po.

Înțelege-l — de la istorie la implementare:

  • Context — de ce există această bibliotecă: treizeci de ani de gettext, două PEP-uri și discuția din biblioteca standard care s-a închis fără un răspuns.
  • Capcane — ce a stricat cu adevărat traducerea acestui sit în treizeci și cinci de limbi, și ce jumătate din asta poate prinde o unealtă.
  • Cum funcționează — de la obiectul șablon al PEP 750 până la șirul randat, și cache-urile care fac verificarea ieftină.

Referință — contractele:

  • API — tot ce exportă pachetul, pe o singură pagină.
  • Specificație — convenția t-string ↔ msgid ca un contract stabil și versionat, cu o suită de conformitate lizibilă de mașină.

Stadiu
Versiunea pachetului 0.1.0a8
Stabilitatea API-ului alpha — API-ul Python încă se poate schimba
Specificație v1, cu o suită de conformitate
Python 3.14 și mai nou; testat pe 3.14, 3.14t (free-threaded) și 3.15
Babel 2.18 sau mai nou, și doar acolo unde rulează pybabel
Dependențe la rulare niciuna — gettext din biblioteca standard
Formatul catalogului POT, PO și MO obișnuite
Modificări CHANGELOG

Un alpha. Contractul este mic în mod intenționat, iar specificația este partea lui stabilă; API-ul Python încă se poate mișca. Înainte de o lansare stabilă, aici este nevoie de fixture-uri lingvistice mai largi, de urmărire susținută a performanței, de o recenzie de API din partea celor care folosesc gettext și Babel în serios, și de testare a compatibilității pe fiecare versiune suportată de Python și de Babel.

Tichetele și pull requesturile sunt binevenite — un alpha este exact momentul în care încă merită să te cerți despre interfață.

Alătură-te comunității