Przejdź do treści

Tłumacz kompletne komunikaty
z t-stringami Pythona

gettext-tstrings łączy t-stringi Pythona 3.14+ ze standardowymi katalogami gettext i narzędziami Babel. Wartości i formatowanie zostają w kodzie aplikacji; tłumacze pracują z kompletnymi komunikatami i prostymi symbolami zastępczymi {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

Katalog zawiera Hello {name}. Tłumaczenie może przenieść {name} albo je powtórzyć. Jeśli usunie, przemianuje lub przeformatuje symbol zastępczy, walidacja katalogu zgłosi błąd. Jeśli błędny wpis mimo to trafi na produkcję, biblioteka loguje ostrzeżenie i renderuje komunikat źródłowy zamiast powodować awarię.

Rozpocznij pięciominutowy samouczek Porównaj alternatywy

Alfa · Python 3.14+ · standardowe katalogi PO/MO · brak zewnętrznych zależności w czasie działania

Ta strona praktykuje to, co dokumentuje: każda wersja językowa — nawigacja, etykiety i raport z budowania świadomy form liczby mnogiej — jest renderowana z katalogów PO przez sam gettext-tstrings.

Czy to jest dla Ciebie?

Pasuje już dziś, gdy Twoja aplikacja działa na Pythonie 3.14 lub nowszym; używasz już gettext i Babel albo chcesz przyjąć ich przepływ pracy z plikami PO/MO; i chcesz składni t-stringów z nazwanymi symbolami zastępczymi, które są sprawdzane, zanim się wyrenderują.

Jeszcze nie pasuje, gdy potrzebujesz Pythona 3.13 lub starszego; wymagasz stabilnego API Pythona — to jest wersja alfa, a specyfikacja jest tą jej częścią, która się ustaliła; albo prawie cały Twój tekst do przetłumaczenia mieszka w języku szablonów, a nie w źródłach Pythona.

Masz już katalogi? Działają dalej. _("Hello {name}").format(name=name) i tr(t"Hello {name}") dają ten sam msgid, więc istniejące tłumaczenia przetrwają zmianę — Migracja prowadzi przez całe przejście.

Co wolno powiedzieć katalogowi

Tłumaczenie nie może zmienić struktury komunikatu, który tłumaczy. Na tym polega cała obietnica, a reszta tej strony z niej wynika. Tłumaczenie może zmieniać kolejność {name} albo je powtarzać i może przepisać każde inne słowo wokół niego. Nie może pominąć symbolu zastępczego, wymyślić nowego, sięgnąć przez niego do Twoich obiektów ani dołączyć własnego formatowania.

Biblioteka sprawdza to na wejściu — przy kompilacji katalogów — i ponownie w czasie renderowania, a to właśnie różnica między błędem znalezionym w przeglądzie a błędem znalezionym przez użytkownika.

gettext to dla Ciebie nowość? Cały przepływ pracy w czterech zdaniach

gettext to standardowy sposób tłumaczenia oprogramowania, w Pythonie i daleko poza nim. Twój kod oznacza łańcuchy do przetłumaczenia; ekstraktor zbiera je do pliku szablonu (.pot); tłumacz — zwykle nie programista — wypełnia po jednym pliku katalogu (.po) na język, kompilowanym do binarnego .mo, który aplikacja wczytuje w czasie działania. Konwencjonalna nazwa funkcji tłumaczącej to _, więc _(t"Hello {name}") czyta się jako „przetłumacz to zdanie". Samouczek przechodzi całą ścieżkę — oznacz, wyodrębnij, przetłumacz, skompiluj, uruchom — w około pięć minut.

Problem, który rozwiązuje

F-string jest już zinterpolowany, zanim zobaczy go jakakolwiek biblioteka — f"Hello {name}" stał się "Hello Ada", a tłumaczenie fragmentów wokół wartości łamie gramatykę większości języków. T-string (PEP 750) utrzymuje osobno tekst statyczny, obliczone wartości, wyrażenia źródłowe, konwersje i specyfikacje formatu — a to dokładnie ten podział, którego potrzebuje katalog komunikatów. Co to zmienia w porównaniu z %(name)s, .format() i $-stringami.

Nic w gettext ani w Babel nie mówi jednak, jak t-string ma stać się komunikatem. Ta biblioteka dokonuje tego wyboru, spisuje go jako wersjonowaną specyfikację i dostarcza zestaw testów zgodności, który go sprawdza.

Zasady projektowe

  • Tłumacz kompletne komunikaty, nigdy fragmenty zdań.
  • Akceptuj wyłącznie proste nazwy zmiennych, takie jak {name}.
  • Trzymaj !r i :.2f pod kontrolą aplikacji, poza katalogiem.
  • Pozwól tłumaczeniom zmieniać kolejność i powtarzać znane symbole zastępcze, nie pozwalając im sięgać do atrybutów ani dodawać formatowania.
  • Używaj zwykłych plików POT, PO i MO oraz narzędzi, które już je czytają.

A do tego pasująca lista tego, czego biblioteka celowo nie dotyka: nie lokalizuje liczb, walut ani dat — sformatuj je wcześniej, Bablem; nie escape'uje wyrenderowanego wyjścia dla HTML-a, powłoki ani terminala; i nie potrafi ocenić, czy tłumaczenie jest poprawne — tylko czy jego symbole zastępcze są nienaruszone.

Instalacja

python -m pip install gettext-tstrings

Python 3.14 lub nowszy. Renderowanie nie ma zależności — korzysta z modułu gettext biblioteki standardowej i z niczego więcej.

Ekstrakcja i walidacja katalogów przechodzą przez Babel, zainstaluj więc to rozszerzenie tam, gdzie działa pybabel, czyli zwykle w środowisku deweloperskim lub CI, a nie w obrazie produkcyjnym:

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

Dokąd dalej

Zacznij tutaj — bez zakładania doświadczenia z gettext:

  • Samouczek — od pustego katalogu do działającego japońskiego tłumaczenia w pięciu krokach, każde polecenie pokazane z jego wynikiem.
  • Dlaczego t-stringi — ten sam komunikat zapisany na cztery sposoby i to, co %(name)s, .format() oraz $-stringi oddają katalogowi.

Używanie — robocze materiały odniesienia:

  • Przewodnik — API czasu działania: którego punktu wejścia użyć, liczba mnoga, języki na żądanie, odroczone łańcuchy i to, co się dzieje, gdy katalog jest błędny.
  • Ekstrakcja — dokumentacja pybabel: konfiguracja, własne nazwy funkcji i to, jak istniejące narzędzia walidują te katalogi za darmo.
  • W produkcji — pętla tak, jak prowadzi ją zespół: cykl aktualizacji, wpisy fuzzy, bramki CI, platformy tłumaczeniowe i wysyłka.
  • Migracja — przyjęcie tego w projekcie, który ma już katalogi, jedno miejsce wywołania naraz.
  • Dla tłumaczy — jedna strona do przekazania temu, kto edytuje pliki .po.

Zrozumienie — od historii do implementacji:

  • Geneza — dlaczego ta biblioteka istnieje: trzydzieści lat gettext, dwa PEP-y i dyskusja o bibliotece standardowej zamknięta bez odpowiedzi.
  • Pułapki — co naprawdę zepsuło się przy tłumaczeniu tej strony na trzydzieści pięć języków i którą połowę potrafi wychwycić narzędzie.
  • Jak to działa — od obiektu szablonu z PEP 750 do wyrenderowanego łańcucha oraz pamięci podręczne, które czynią sprawdzanie tanim.

Referencja — kontrakty:

  • API — wszystko, co eksportuje pakiet, na jednej stronie.
  • Specyfikacja — konwencja t-string ↔ msgid jako stabilny, wersjonowany kontrakt z maszynowo czytelnym zestawem testów zgodności.

Status
Wersja pakietu 0.1.0a8
Stabilność API alfa — API Pythona może się jeszcze zmieniać
Specyfikacja v1, z zestawem testów zgodności
Python 3.14 i nowsze; testowane na 3.14, 3.14t (free-threaded) i 3.15
Babel 2.18 lub nowszy, i tylko tam, gdzie działa pybabel
Zależności w czasie działania brak — moduł gettext biblioteki standardowej
Format katalogów zwykłe POT, PO i MO
Zmiany CHANGELOG

Wersja alfa. Kontrakt jest celowo mały, a specyfikacja jest jego stabilną częścią; API Pythona może się jeszcze zmieniać. Przed stabilnym wydaniem potrzebne są szersze zestawy testowe dla języków, stałe śledzenie wydajności, przegląd API przez osoby używające gettext i Babel na poważnie oraz testy zgodności z każdą wspieraną wersją Pythona i Babel.

Zgłoszenia i pull requesty są mile widziane — alfa to dokładnie ten moment, w którym o interfejs wciąż warto się spierać.

Dołącz do społeczności