Kinyerés¶

A kinyerés az a lépés, amely a forráskódodból minden megjelölt üzenetet összegyűjt egy .pot sablonba a fordítók számára — az oktatóanyag ciklusának 3. lépése. Ez az oldal ennek a lépésnek a referenciája: konfiguráció, saját függvénynevek, szigorú CI-mód, és az ellenőrzések, amelyek utána a katalógusaidat őrzik.

A kinyeréshez kell a babel extra:

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

A munkafolyamat¶

Hozd létre a babel.cfg fájlt:

[gettext_tstrings: **.py]
encoding = utf-8

Ezután használd a szokásos Babel-parancsokat:

pybabel extract -F babel.cfg -c "Translators:" -o locales/messages.pot .
pybabel init -i locales/messages.pot -d locales -l ja
pybabel compile -d locales

Az init nyelvenként egyszer fut le; ezután a pybabel update gyúrja bele a friss sablont a meglévő katalógusokba. Ezt a visszatérő kört — és azt, hogy a fuzzy bejegyzései mit jelentenek egy kiadás szempontjából — az Éles üzemben járja végig.

A gettext_tstrings kinyerő a szokásos _(), gettext() és ngettext() hívásokat is kezeli, így egyetlen leképezés lefed egy vegyes kódbázist. Felismeri a _() hívást, a négy szabványos gettext-nevet, a tr() / ntr() aliasokat, valamint a késleltetett lazy_gettext() / lazy_pgettext() hívásokat.

Saját függvénynevek regisztrálása¶

[gettext_tstrings: **.py]
tr_functions = tr translate
ntr_functions = ntr

[[mappings]]
method = "gettext_tstrings"
pattern = "**.py"
tr_functions = ["tr", "translate"]
ntr_functions = ["ntr"]

Egy ini-fájl egyetlen szöveget ad, egy TOML-leképezés listát, és egy szövegen belül szóköz vagy vessző is elválasztja a neveket. Mind a négy írásmód működik.

A beállítások: tr_functions, ntr_functions, gettext_functions, ngettext_functions, pgettext_functions és npgettext_functions.

Helyben elnéző, CI-ben szigorú¶

Alapértelmezés szerint egyetlen rossz fájl nem vet véget a futásnak:

• Az olyan t-stringet, amelyet a kinyerő elutasít — attribútum-hozzáférés, kifejezés, hibás argumentum —, figyelmeztetésként jelenti és kihagyja.
• A nem elemezhető fájlt ugyanígy kihagyja.
• És ugyanígy azt is, amelyet csak a tokenize utasít el, míg az ast elfogadja — ezen a Babel saját menete egyébként megszakadna.

Ez kényelmes, amíg szerkesztesz, és veszélyes, amikor nem: a kihagyott üzenet egyszerűen hiányzik a POT-ból, tehát soha nem fordítják le, és semmi nem szól róla. Állítsd a leképezés beállításai közé a strict = true értéket mindenütt, ahol a kinyerést nem figyeli ember:

[gettext_tstrings: **.py]
encoding = utf-8
strict = true

[[mappings]]
method = "gettext_tstrings"
pattern = "**.py"
strict = true

Ekkor a fenti figyelmeztetések mindegyike kemény hibává válik. Tekintsd ezt az éles beállításnak, az alapértelmezést pedig a helyinek.

A meglévő eszközláncod validálja ezeket a katalógusokat¶

A Babel minden kinyert üzenetet szabványos jelzővel lát el, és épp ez az egyetlen sor kapcsolja be a helyőrző-ellenőrzést azokban az eszközökben, amelyeket már futtatsz:

#. gettext-tstrings
#: app.py:4
#, python-brace-format
msgid "Hello {name}"
msgstr ""

Fordítsd こんにちは {nombre} alakban, és a hiba mindenféle konfiguráció nélkül fennakad:

$ msgfmt --check-format -o /dev/null locales/ja/LC_MESSAGES/messages.po
locales/ja/LC_MESSAGES/messages.po:25: a format specification for argument
'name' doesn't exist in 'msgstr'
msgfmt: found 1 fatal error

A Weblate ugyanezt az ellenőrzést Python brace format néven dokumentálja, a kereskedelmi platformoknak pedig saját helyőrző-QA-juk van, ugyanerre a jelzőre kötve. Minden platform viselkedése a sajátja; az alábbi két eszköz az, amelyet itt ellenőriztünk.

Ezen felül a csomag regisztrál egy Babel-ellenőrzőt, így a pybabel compile a specifikáció szabályait alkalmazza minden olyan üzenetre, amely a gettext-tstrings jelölőmegjegyzést viseli:

$ pybabel compile -d locales -l ja
error: locales/ja/LC_MESSAGES/messages.po:24: translation does not match the
source placeholders: {name} is missing; {nombre} is not in the source message
1 errors encountered.

Többes számú üzenetnél a mutató megnevezi az alakot, mert a Babel által jelentett sorszám a msgidé, egy orosz blokk alatt pedig három msgstr áll:

error: locales/ru/LC_MESSAGES/messages.po:31: msgstr[1]: translation does not
match the source placeholders: {n} is missing

A két ellenőrzés nem redundáns. A csomag ellenőrzője legalább két esetben szigorúbb:

• Az a msgid, amelyben csak escape-elt kapcsos zárójelek vannak (Config {{raw}} only), soha nem kapja meg a python-brace-format jelzőt, így semmilyen külső eszköz nem validálja.
• A többesszám-alakokat egyenként ellenőrizzük. A msgfmt --check-format ugyanezt a fájlt olvassa, és 0 státusszal lép ki; azt az alakot, amely elhagy egy helyőrzőt, amelyet a testvérei megtartanak, ott elfogadja, itt viszont elutasítjuk.

A msgfmt csak azokat a helyőrzőneveket ellenőrzi, amelyeket Python brace formátumként tud értelmezni, ezért az ASCII nevekkel a lánc minden eszköze képes marad az üzenet validálására. Maga a könyvtár bármilyen str.isidentifier() nevet elfogad.

Sablonok és más eszközök¶

A t-string Python-szintaxis, így ez a könyvtár a Python-forrásokat fedi le. A sablonnyelvek továbbra is a saját i18n-jüket használják — a Jinja2 {% trans %} szerkezetét, a Django sabloncímkéit — és a Babel hozzájuk való kinyerőit. Minden ugyanabba a PO-katalógusba táplál be, így egyetlen fordítási munkafolyamat továbbra is lefed egy vegyes kódbázist.

A pygettext ma nem tudja elemezni a t-stringeket, ezért megy a kinyerés a Babelen keresztül. A konvenciót leírtuk a specifikációban, hogy egy másik kinyerő vagy egy jövőbeli pygettext is megcélozhassa.