Gå till innehållet

Översätt kompletta meddelanden
med t-strings i Python

gettext-tstrings kopplar samman t-strings i Python 3.14+ med vanliga gettext-kataloger och Babel-verktyg. Värden och formatering stannar i applikationskoden; översättarna arbetar med kompletta meddelanden och enkla {name}-platshållare:

import gettext

from gettext_tstrings import Translator

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

Katalogen innehåller Hello {name}. En översättning får flytta om eller upprepa {name}. Om den utelämnar, byter namn på eller formaterar om platshållaren rapporterar katalogvalideringen felet. Om en ogiltig post ändå når produktion loggar biblioteket en varning och renderar källmeddelandet i stället för att krascha.

Starta den femminuterslånga handledningen Jämför alternativen

Alfa · Python 3.14+ · standardiserade PO/MO-kataloger · inga körningsberoenden från tredje part

Den här webbplatsen praktiserar vad den dokumenterar: varje språkutgåva — navigering, etiketter och den pluralmedvetna byggrapporten — renderas från PO-kataloger av gettext-tstrings självt.

Är det här något för dig?

Det passar redan i dag när din applikation kör på Python 3.14 eller nyare; du redan använder gettext och Babel, eller vill införa deras PO/MO-arbetsflöde; och du vill ha t-string-syntax med namngivna platshållare som kontrolleras innan de renderas.

Det passar inte än när du behöver Python 3.13 eller äldre; du kräver ett stabilt Python-API — det här är en alfa, och specifikationen är den del av det som har satt sig; eller när nästan all din översättbara text bor i ett mallspråk snarare än i Python-källkod.

Har du redan kataloger? De fortsätter att fungera. _("Hello {name}").format(name=name) och tr(t"Hello {name}") ger samma msgid, så befintliga översättningar överlever bytet — Migrering går igenom hela flytten.

Vad katalogen får säga

En översättning kan inte ändra strukturen på det meddelande den översätter. Det är hela löftet, och resten av den här webbplatsen följer av det. En översättning får flytta om eller upprepa {name}, och får skriva om varenda annat ord runt omkring. Den får inte utelämna platshållaren, hitta på en ny, sträcka sig genom den in i dina objekt eller lägga till egen formatering.

Biblioteket kontrollerar det på vägen in — när kataloger kompileras — och igen vid rendering, vilket är skillnaden mellan ett misstag som hittas i granskning och ett misstag som hittas av en användare.

Ny på gettext? Hela arbetsflödet i fyra meningar

gettext är standardsättet att översätta programvara, i Python och långt därbortom. Din kod markerar översättbara meddelanden; en extraktor samlar dem i en mallfil (.pot); en översättare — oftast inte en programmerare — fyller i en katalogfil (.po) per språk, som kompileras till en binär .mo som din applikation läser in vid körning. Det konventionella namnet på översättningsfunktionen är _, så _(t"Hello {name}") läses som "översätt det här meddelandet". Handledningen går igenom hela vägen — markera, extrahera, översätta, kompilera, köra — på ungefär fem minuter.

Problemet det löser

En f-string är redan interpolerad när något bibliotek får se den — f"Hello {name}" har blivit "Hello Ada", och att översätta fragmenten runt ett värde bryter grammatiken i de flesta språk. En t-string (PEP 750) håller den statiska texten, de utvärderade värdena, källuttrycken, konverteringarna och formatspecifikationerna åtskilda — vilket är exakt den uppdelning en meddelandekatalog behöver. Vad det förändrar, jämfört med %(name)s, .format() och $-strängar.

Men ingenting i gettext eller Babel säger hur en t-string blir ett meddelande. Det här biblioteket gör det valet, skriver ner det som en versionerad specifikation och levererar konformitetssviten som kontrollerar det.

Designreglerna

  • Översätt kompletta meddelanden, aldrig meningsfragment.
  • Acceptera endast enkla variabelnamn som {name}.
  • Håll !r och :.2f under applikationens kontroll, utanför katalogen.
  • Låt översättningar flytta om och upprepa kända platshållare, samtidigt som de hindras från att nå attribut eller lägga till formatering.
  • Återanvänd vanliga POT-, PO- och MO-filer, och verktygen som redan läser dem.

Och den motsvarande listan över vad det avsiktligt lämnar i fred: det lokaliserar inte tal, valutor eller datum — formatera dem först, med Babel; det escapar inte renderad utdata för HTML, ett skal eller en terminal; och det kan inte bedöma om en översättning är korrekt, bara om dess platshållare är intakta.

Installera

python -m pip install gettext-tstrings

Python 3.14 eller nyare. Rendering har inga beroenden — den använder standardbibliotekets gettext och ingenting annat.

Extrahering och katalogvalidering går genom Babel, så installera det extrat överallt där pybabel körs, vilket vanligtvis är en utvecklings- eller CI-miljö snarare än en produktionsavbild:

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

Vart härnäst

Börja här — ingen gettext-erfarenhet förutsätts:

  • Handledning — från en tom katalog till en körande japansk översättning i fem steg, varje kommando visat med sin utdata.
  • Varför t-strings — samma meddelande skrivet på fyra sätt, och vad %(name)s, .format() och $-strängar var för sig lämnar över till katalogen.

Använd det — arbetsreferenserna:

  • Guide — körnings-API🇪🇹 vilken ingång du ska använda, pluralformer, språk per förfrågan, uppskjutna strängar, och vad som händer när en katalog är fel.
  • Extrahering — pybabel-referensen: konfiguration, egna funktionsnamn, och hur befintliga verktyg validerar dessa kataloger gratis.
  • I produktion — kretsloppet så som ett team kör det: uppdateringscykeln, fuzzy-poster, CI-grindar, översättningsplattformar och leverans.
  • Migrering — att införa det här i ett projekt som redan har kataloger, ett anropsställe i taget.
  • För översättare — en sida att räcka över till den som redigerar .po-filerna.

Förstå det — från historia till implementation:

  • Bakgrund — varför det här biblioteket finns: trettio år av gettext, två PEP:ar och stdlib-diskussionen som stängdes utan svar.
  • Fallgropar — vad översättningen av den här webbplatsen till trettiofem språk faktiskt gick sönder på, och vilken hälft ett verktyg hinner fånga.
  • Så fungerar det — från PEP 750:s template-objekt till den renderade strängen, och cacharna som gör kontrollerna billiga.

Referens — kontrakten:

  • API — allt paketet exporterar, på en sida.
  • Specifikation — konventionen t-string ↔ msgid som ett stabilt, versionerat kontrakt, med en maskinläsbar konformitetssvit.

Status
Paketversion 0.1.0a8
API-stabilitet alfa — Python-API:et kan fortfarande ändras
Specifikation v1, med en konformitetssvit
Python 3.14 och senare; testad på 3.14, 3.14t (free-threaded) och 3.15
Babel 2.18 eller senare, och endast där pybabel körs
Körtidsberoenden inga — standardbibliotekets gettext
Katalogformat vanlig POT, PO och MO
Ändringar CHANGELOG

En alfa. Kontraktet är avsiktligt litet och specifikationen är den stabila delen av det; Python-API:et kan fortfarande röra sig. Före en stabil utgåva behövs bredare språkfixturer, kontinuerlig prestandauppföljning, API-granskning från personer som använder gettext och Babel på allvar, och kompatibilitetstester över varje Python- och Babel-version som stöds.

Ärenden och pull requests är välkomna — en alfa är exakt rätt tillfälle att fortfarande diskutera gränssnittet.

Gå med i gemenskapen