Aller au contenu

Traduisez des messages complets
avec les t-strings de Python

gettext-tstrings relie les t-strings de Python 3.14+ aux catalogues gettext standard et à l'outillage Babel. Les valeurs et le formatage restent dans le code applicatif ; les traducteurs travaillent avec des messages complets et de simples marqueurs {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

Le catalogue contient Hello {name}. Une traduction peut déplacer ou répéter {name}. Si elle supprime, renomme ou reformate le marqueur, la validation du catalogue signale l'erreur. Si une entrée invalide atteint malgré tout la production, la bibliothèque journalise un avertissement et rend le message source au lieu de planter.

Commencer le tutoriel de cinq minutes Comparer les alternatives

Alpha · Python 3.14+ · catalogues PO/MO standard · aucune dépendance tierce à l'exécution

Ce site pratique ce qu'il documente : chaque édition linguistique — navigation, libellés et rapport de build avec pluriels — est rendue depuis des catalogues PO par gettext-tstrings lui-même.

Est-ce fait pour vous ?

Un bon choix dès aujourd'hui si votre application tourne sur Python 3.14 ou plus récent ; si vous utilisez déjà gettext et Babel, ou souhaitez adopter leur workflow PO/MO ; et si vous voulez la syntaxe t-string avec des marqueurs nommés vérifiés avant leur rendu.

Pas encore un bon choix si vous avez besoin de Python 3.13 ou antérieur ; si vous exigez une API Python stable — ceci est une alpha, et la spécification en est la partie qui a pris forme ; ou si la quasi- totalité de votre texte traduisible vit dans un langage de gabarits plutôt que dans du source Python.

Vous avez déjà des catalogues ? Ils continuent de fonctionner. _("Hello {name}").format(name=name) et tr(t"Hello {name}") produisent le même msgid, si bien que les traductions existantes survivent au changement — Migration parcourt le déplacement entier.

Ce que le catalogue a le droit de dire

Une traduction ne peut pas changer la structure du message qu'elle traduit. Voilà toute la promesse, et tout le reste de ce site en découle. Une traduction peut réordonner ou répéter {name}, et peut réécrire tous les autres mots autour de lui. Elle ne peut ni supprimer le marqueur, ni en inventer un nouveau, ni passer à travers lui pour atteindre vos objets, ni attacher son propre formatage.

La bibliothèque le vérifie à l'entrée — quand les catalogues sont compilés — puis à nouveau au moment du rendu, ce qui fait la différence entre une erreur trouvée en revue et une erreur trouvée par un utilisateur.

gettext est nouveau pour vous ? Tout le workflow en quatre phrases

gettext est la façon standard de traduire des logiciels, en Python et bien au-delà. Votre code marque les messages traduisibles ; un extracteur les collecte dans un fichier modèle (.pot) ; un traducteur — en général pas un programmeur — remplit un fichier catalogue (.po) par langue, compilé en un .mo binaire que votre application charge à l'exécution. Le nom conventionnel de la fonction de traduction est _, donc _(t"Hello {name}") se lit « traduis ce message ». Le tutoriel parcourt tout le chemin — marquer, extraire, traduire, compiler, exécuter — en cinq minutes environ.

Le problème résolu

Une f-string est déjà interpolée lorsqu'une bibliothèque la reçoit — f"Hello {name}" est devenue "Hello Ada", et traduire les fragments autour d'une valeur casse la grammaire de la plupart des langues. Une t-string (PEP 750) conserve séparément le texte statique, les valeurs évaluées, les expressions source, les conversions et les spécifications de format — c'est exactement la séparation qu'attend un catalogue de messages. Ce que cela change, comparé à %(name)s, .format() et aux chaînes $.

Ni gettext ni Babel ne disent cependant comment une t-string devient un message. Cette bibliothèque fait ce choix, le consigne dans une spécification versionnée et livre la suite de conformité qui le vérifie.

Les règles de conception

  • Traduire des messages complets, jamais des fragments de phrase.
  • N'accepter que des noms de variables simples comme {name}.
  • Garder !r et :.2f sous le contrôle de l'application, hors du catalogue.
  • Autoriser les traductions à réordonner et répéter les marqueurs connus, tout en les empêchant d'atteindre des attributs ou d'ajouter du formatage.
  • Réutiliser les fichiers POT, PO et MO ordinaires, et les outils qui les lisent déjà.

Et la liste symétrique de ce qu'elle laisse délibérément de côté : elle ne localise ni les nombres, ni les devises, ni les dates — formatez-les d'abord avec Babel ; elle n'échappe pas la sortie rendue pour du HTML, un shell ou un terminal ; et elle ne peut pas juger si une traduction est correcte, seulement si ses marqueurs sont intacts.

Installation

python -m pip install gettext-tstrings

Python 3.14 ou plus récent. Le rendu n'a aucune dépendance : il utilise le gettext de la bibliothèque standard et rien d'autre.

L'extraction et la validation des catalogues passent par Babel. Installez donc cet extra là où pybabel s'exécute, c'est-à-dire en général un environnement de développement ou de CI plutôt qu'une image de production :

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

Pour continuer

Commencer ici — aucune expérience de gettext supposée :

  • Tutoriel — d'un répertoire vide à une traduction japonaise qui fonctionne, en cinq étapes, chaque commande montrée avec sa sortie.
  • Pourquoi les t-strings — le même message écrit de quatre façons, et ce que %(name)s, .format() et les chaînes $ confient chacun au catalogue.

Passer à la pratique — les références de travail :

  • Guide — l'API d'exécution : quel point d'entrée choisir, les pluriels, la langue par requête, les chaînes différées, et ce qui se passe quand un catalogue est incorrect.
  • Extraction — la référence pybabel : configuration, noms de fonctions personnalisés, et comment les outils existants valident ces catalogues gratuitement.
  • En production — la boucle telle qu'une équipe la fait tourner : le cycle de mise à jour, les entrées fuzzy, les barrières de CI, les plateformes de traduction et la livraison.
  • Migration — adopter tout cela dans un projet qui possède déjà des catalogues, un site d'appel à la fois.
  • Pour les traducteurs — une seule page à remettre à qui édite les fichiers .po.

Comprendre le fond — de l'histoire à l'implémentation :

  • Contexte — pourquoi cette bibliothèque existe : trente ans de gettext, deux PEP et la discussion sur la bibliothèque standard close sans réponse.
  • Pièges — ce que la traduction de ce site en trente-cinq langues a réellement cassé, et la moitié qu'un outil sait attraper.
  • Fonctionnement — de l'objet template de la PEP 750 à la chaîne rendue, et les caches qui rendent la vérification bon marché.

Référence — les contrats :

  • API — tout ce que le paquet exporte, sur une seule page.
  • Spécification — la convention t-string ↔ msgid comme contrat stable et versionné, avec une suite de conformité lisible par machine.

État
Version du paquet 0.1.0a8
Stabilité de l'API alpha — l'API Python peut encore changer
Spécification v1, avec une suite de conformité
Python 3.14 et plus récent ; testé sur 3.14, 3.14t (free-threaded) et 3.15
Babel 2.18 ou plus récent, et seulement là où pybabel s'exécute
Dépendances d'exécution aucune — le gettext de la bibliothèque standard
Format de catalogue POT, PO et MO ordinaires
Changements CHANGELOG

Une alpha. Le contrat reste volontairement réduit et la spécification en est la partie stable ; l'API Python peut encore bouger. Avant une version stable, il faudra davantage de langues de test, un suivi durable des performances, une revue d'API par des gens qui utilisent sérieusement gettext et Babel, et des tests de compatibilité sur chaque version prise en charge de Python et de Babel.

Les issues et pull requests sont bienvenues : une alpha est exactement le moment où l'interface vaut encore la peine d'être discutée.

Rejoindre la communauté