Vai al contenuto

Traduci messaggi completi
con le t-string di Python

gettext-tstrings collega le t-string di Python 3.14+ ai normali cataloghi gettext e agli strumenti di Babel. Valori e formattazione restano nel codice applicativo; i traduttori lavorano con messaggi completi e semplici segnaposto {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

Il catalogo contiene Hello {name}. Una traduzione può spostare o ripetere {name}. Se lo elimina, lo rinomina o ne cambia la formattazione, la validazione del catalogo segnala l'errore. Se una voce non valida arriva comunque in produzione, la libreria registra un avviso e rende il messaggio sorgente invece di andare in crash.

Inizia il tutorial di cinque minuti Confronta le alternative

Alpha · Python 3.14+ · cataloghi PO/MO standard · nessuna dipendenza a runtime di terze parti

Questo sito mette in pratica ciò che documenta: ogni edizione linguistica — navigazione, etichette e il report di build con le forme plurali — è generata dai cataloghi PO da gettext-tstrings stessa.

Fa per te?

Va bene già oggi se la tua applicazione gira su Python 3.14 o più recente; usi già gettext e Babel, oppure vuoi adottare il loro flusso di lavoro PO/MO; e vuoi la sintassi delle t-string con segnaposto nominati che vengono verificati prima di essere resi.

Non fa ancora per te se ti serve Python 3.13 o precedente; ti serve un'API Python stabile — questa è una alpha, e la specifica ne è la parte che si è assestata; oppure quasi tutto il tuo testo traducibile vive in un linguaggio di template anziché nel sorgente Python.

Hai già dei cataloghi? Continuano a funzionare. _("Hello {name}").format(name=name) e tr(t"Hello {name}") producono lo stesso msgid, quindi le traduzioni esistenti sopravvivono al cambio — Migrazione percorre l'intero passaggio.

Che cosa può dire il catalogo

Una traduzione non può cambiare la struttura del messaggio che traduce. Questa è tutta la promessa, e il resto di questo sito ne discende. Una traduzione può riordinare o ripetere {name}, e può riscrivere ogni altra parola attorno a esso. Non può eliminare il segnaposto, inventarne uno nuovo, passarci attraverso per arrivare ai tuoi oggetti o aggiungere formattazione propria.

La libreria lo verifica all'ingresso — quando i cataloghi vengono compilati — e di nuovo al momento del rendering, che è la differenza tra un errore trovato in revisione e un errore trovato da un utente.

Nuovo a gettext? L'intero flusso di lavoro in quattro frasi

gettext è il modo standard in cui il software viene tradotto, in Python e ben oltre. Il tuo codice marca i messaggi traducibili; un estrattore li raccoglie in un file template (.pot); un traduttore — di solito non un programmatore — compila un file di catalogo (.po) per lingua, che viene compilato in un .mo binario caricato dall'applicazione a runtime. Il nome convenzionale della funzione di traduzione è _, così _(t"Hello {name}") si legge come "traduci questo messaggio". Il tutorial percorre l'intero cammino — marcare, estrarre, tradurre, compilare, eseguire — in circa cinque minuti.

Il problema che risolve

Una f-string è già interpolata prima che una libreria possa vederla — f"Hello {name}" è ormai diventata "Hello Ada", e tradurre i frammenti attorno a un valore rompe la grammatica della maggior parte delle lingue. Una t-string (PEP 750) mantiene separati il testo statico, i valori valutati, le espressioni sorgente, le conversioni e le specifiche di formato — che è esattamente la separazione di cui un catalogo di messaggi ha bisogno. Che cosa cambia, rispetto a %(name)s, .format() e alle $-string.

Nulla in gettext o Babel dice però come una t-string diventi un messaggio. Questa libreria compie quella scelta, la mette per iscritto in una specifica versionata e distribuisce la suite di conformità per verificarla.

Le regole di progetto

  • Tradurre messaggi completi, mai frammenti di frase.
  • Accettare soltanto nomi di variabile semplici come {name}.
  • Tenere !r e :.2f sotto il controllo dell'applicazione, fuori dal catalogo.
  • Permettere alle traduzioni di riordinare e ripetere i segnaposto noti, impedendo loro al tempo stesso di arrivare agli attributi o di aggiungere formattazione.
  • Riutilizzare i normali file POT, PO e MO, e gli strumenti che già li leggono.

E l'elenco corrispondente di ciò che lascia deliberatamente stare: non localizza numeri, valute o date — formattali prima, con Babel; non fa l'escaping dell'output reso per l'HTML, una shell o un terminale; e non sa giudicare se una traduzione sia corretta, ma solo se i suoi segnaposto sono intatti.

Installazione

python -m pip install gettext-tstrings

Python 3.14 o più recente. Il rendering non ha dipendenze — usa il modulo gettext della libreria standard e nient'altro.

L'estrazione e la validazione dei cataloghi passano per Babel: installa quell'extra ovunque giri pybabel, di solito un ambiente di sviluppo o CI e non un'immagine di produzione:

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

Dove andare adesso

Inizia da qui — nessuna esperienza con gettext richiesta:

  • Tutorial — da una directory vuota a una traduzione giapponese funzionante in cinque passi, ogni comando mostrato con il suo output.
  • Perché le t-string — lo stesso messaggio scritto in quattro modi, e che cosa %(name)s, .format() e le $-string consegnano ciascuno al catalogo.

Usala — i riferimenti di lavoro:

  • Guida — l'API a runtime: quale entry point usare, plurali, lingue per richiesta, stringhe differite e che cosa succede quando un catalogo è sbagliato.
  • Estrazione — il riferimento per pybabel: configurazione, nomi di funzione personalizzati e come gli strumenti esistenti validano questi cataloghi gratis.
  • In produzione — il ciclo come lo conduce un team: il ciclo di aggiornamento, le voci fuzzy, i controlli in CI, le piattaforme di traduzione e la distribuzione.
  • Migrazione — adottarla in un progetto che ha già cataloghi, un punto di chiamata alla volta.
  • Per i traduttori — una pagina sola da consegnare a chi modifica i file .po.

Capiscila — dalla storia all'implementazione:

  • Contesto — perché questa libreria esiste: trent'anni di gettext, due PEP e la discussione sulla stdlib chiusa senza una risposta.
  • Insidie — che cosa ha rotto davvero la traduzione di questo sito in trentacinque lingue, e quale metà uno strumento può intercettare.
  • Come funziona — dall'oggetto template della PEP 750 alla stringa finale, e le cache che rendono economico il controllo.

Riferimento — i contratti:

  • API — tutto ciò che il pacchetto esporta, in una sola pagina.
  • Specifica — la convenzione t-string ↔ msgid come contratto stabile e versionato, con una suite di conformità leggibile dalle macchine.

Stato
Versione del pacchetto 0.1.0a8
Stabilità dell'API alpha — l'API Python può ancora cambiare
Specifica v1, con una suite di conformità
Python 3.14 e successive; testata su 3.14, 3.14t (free-threaded) e 3.15
Babel 2.18 o successiva, e solo dove gira pybabel
Dipendenze a runtime nessuna — il gettext della libreria standard
Formato dei cataloghi POT, PO e MO ordinari
Modifiche CHANGELOG

Una alpha. Il contratto è piccolo di proposito e la specifica ne è la parte stabile; l'API Python può ancora muoversi. Prima di una release stabile servono fixture per più lingue, un tracciamento costante delle prestazioni, revisioni dell'API da parte di chi usa gettext e Babel sul serio, e test di compatibilità su ogni versione supportata di Python e Babel.

Issue e pull request sono benvenute — una alpha è esattamente il momento in cui vale ancora la pena discutere dell'interfaccia.

Unisciti alla comunità