Jak vytvořit soubor .pot pro šablonu nebo plugin
Právě jste dokončili WordPress plugin, který chcete sdílet se světem. Kód funguje, funkce jsou spolehlivé a někdo z Německa vám pošle e-mail s dotazem, jak jej přeložit do němčiny. Ukážete jim složku languages a uvědomíte si, že tam nic není. Žádná šablona, žádné řetězce, žádný způsob, jak by překladatel vůbec věděl, co je potřeba přeložit. Váš plugin je technicky "připraven k překladu" jen podle názvu.
Každý přeložitelný WordPress projekt začíná jedním souborem: šablonou .pot. Než kdokoli může vytvořit německou, francouzskou nebo japonskou verzi, musíte vytvořit soubor POT, který obsahuje seznam všech řetězců určených pro uživatele ve vašem kódu. Přeskočte tento krok a překladatelé budou nuceni číst váš zdrojový kód řádek po řádku a hádat, které řetězce mají být vůbec viditelné.
Tento průvodce prochází dvěma částmi práce: přípravou vašeho zdrojového kódu tak, aby byly řetězce zjistitelné, a následným generováním samotného .pot pomocí tří různých nástrojů. Použijeme WP-CLI, Poedit a starší přístup makepot/grunt, s reálnými příkazy, které můžete zkopírovat. Na konci budete mít čistou šablonu připravenou pro jakéhokoli překladatele.
Krok první: Označte své řetězce jako přeložitelné
Než budete moci vytvořit soubor POT, každý řetězec, který uživatel může vidět, musí být zabalen do funkce Gettext. Skener může extrahovat pouze řetězce, které rozpozná, a rozpozná je pomocí těchto volání funkcí – obyčejné řetězcové literály jsou pro něj neviditelné.
WordPress poskytuje rodinu lokalizačních funkcí, každou pro mírně odlišný kontext:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
Druhý argument v každém volání — 'my-plugin' — je textová doména. Sdružuje všechny řetězce pluginu nebo šablony pod jeden jmenný prostor, takže WordPress ví, který soubor .mo má pro ně načíst. Každý přeložitelný řetězec ve vašem projektu musí sdílet přesně stejnou textovou doménu, jinak některé řetězce nikdy nebudou přeloženy.
Použijte _x() vždy, když je slovo nejednoznačné. Anglické „Post“ může být podstatné jméno nebo sloveso a mnoho jazyků je překládá odlišně. Kontextové řetězce umožňují překladatelům je rozlišit. A sáhněte po variantách esc_html__() a esc_attr__() vždy, když je přeložený řetězec vytištěn do HTML, abyste zůstali v bezpečí a zároveň lokalizováni.
Existuje několik návyků, které udržují vaše řetězce extrahovatelné. Jako první argument vždy předejte obyčejný řetězcový literál — nikdy ne proměnnou nebo zřetězení jako __( 'Hello ' . $name, 'my-plugin' ), protože skener čte zdrojový text staticky a nemůže rozlišovat hodnoty za běhu. Pro věty s číslem použijte _n(), aby byly správně zachyceny množné tvary, a pro věty s dynamickou hodnotou použijte sprintf() kolem zástupného symbolu, jako je %s, namísto spojování řetězců. Důslednost zde je to, co zajišťuje, že další krok – generování šablony – povede ke kompletnímu a použitelnému výsledku.
Krok druhý: Deklarujte textovou doménu v záhlaví
WordPress potřebuje dvě pole v záhlaví, aby věděl, kde se nachází vaše překlady: Text Domain a Domain Path. Nastavte je v hlavním souboru vašeho pluginu nebo v style.css vaší šablony a WordPress automaticky načte správný soubor .mo za běhu.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Text Domain musí odpovídat řetězci, který jste předali každému volání __() a _e() — zde my-plugin. Domain Path říká WordPressu, která podsložka obsahuje soubory překladů, vztaženo k rootu pluginu nebo šablony. Konvencí je /languages, a přesně tam by měl být váš vygenerovaný soubor .pot umístěn.
S zabalenými řetězci a deklarovaným záhlavím je váš kód připraven ke skenování. Širší obrázek přípravy projektu na překlad — včetně šablon, které nejsou vaše vlastní — je pokryt v článku jak lokalizovat jakoukoli WordPress šablonu, i když nejste vývojář.
Jak vygenerovat soubor .pot? Tři metody
Soubor .pot vygenerujete spuštěním skeneru nad vaším zdrojovým kódem, který najde každé volání Gettext a zapíše řetězce do šablony. Zde jsou tři spolehlivé způsoby, jak to udělat, od moderního výchozího až po starší přístup.
Metoda 1: WP-CLI (doporučeno)
Oficiální a moderní způsob, jak vytvořit soubor POT, je WP-CLI s příkazem i18n. Je součástí základních nástrojů WordPressu, rozumí PHP a JavaScript řetězcům a vytvoří šablonu vyhovující standardům v jediném řádku.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
Prvním argumentem je zdrojový adresář (. pro aktuální složku) a druhým je výstupní cesta. WP-CLI prochází vaše soubory, extrahuje každý zabalený řetězec, zaznamená zdrojový soubor a číslo řádku jako komentář a zapíše .pot. Je rychlý, skriptovatelný a správná volba pro jakýkoli seriózní projekt.
Vygenerovaná šablona obsahuje užitečná metadata, která můžete doladit pomocí dalších příznaků. Předejte --headers k nastavení názvu projektu, verze a kontaktní adresy překladatelů, aby byl blok záhlaví .pot správně vyplněn, namísto ponechání zástupných symbolů. WP-CLI také automaticky extrahuje JavaScriptové řetězce z volání wp_set_script_translations(), což je důležité pro moderní blokové šablony a Gutenberg pluginy, kde polovina textu určeného pro uživatele žije v JavaScriptu spíše než v PHP. Jeden příkaz pokrývá oba světy.
Metoda 2: Poedit (grafická)
Pokud dáváte přednost desktopové aplikaci, Poedit může skenovat váš zdrojový kód a generovat šablonu prostřednictvím svého rozhraní. Otevřete Poedit, zvolte vytvoření nového překladu z POT nebo přímé skenování zdrojů, nasměrujte jej na složku vašeho projektu a nakonfigurujte zdrojová klíčová slova (__, _e, _x, esc_html__) v rámci vlastností katalogu.
Funkce Poeditu pro skenování zdrojů a generování .pot jsou dostupné v jeho Pro edici, ale pracovní postup je přátelský pro vývojáře, kteří raději klikají než píší příkazy. Je to také spolehlivý editor pro následnou fázi překladu. Poedit a několik dalších desktopových možností jsou porovnány v top 5 bezplatných nástrojů pro úpravu a překlad souborů PO na Macu a Windows.
Metoda 3: makepot / grunt (starší)
Před WP-CLI byl standardním nástrojem skript makepot.php z repozitáře WordPress i18n-tools, často zapojený do Grunt build úlohy s grunt-wp-i18n. Stále se s ním setkáte ve starších pluginech a šablonách.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Funguje, ale je neudržovaný ve srovnání s WP-CLI a jeho nastavení je pomalejší. Použijte jej pouze v případě, že udržujete starší projekt, který na něm již závisí; pro cokoli nového upřednostněte wp i18n make-pot.
Udržujte šablonu aktualizovanou s každou změnou kódu
Soubor .pot je snímek vašich řetězců v jednom okamžiku. Pokaždé, když přidáte funkci, změníte popisek nebo opravíte překlep ve viditelném řetězci, šablona zastará a překladatelé zmeškají nové znění.
Udělejte z regenerace součást vaší rutiny vydávání. Spusťte znovu wp i18n make-pot před každou aktualizací verze, poté sloučte obnovenou šablonu do stávajících překladů pomocí wp i18n update-po nebo msgmerge, aby si překladatelé ponechali svou dokončenou práci a viděli pouze nové mezery. Zacházejte s .pot jako s artefaktem sestavení, který regenerujete, nikoli jako se souborem, který ručně upravujete.
Zastaralá šablona způsobuje nenápadnou, frustrující chybu: nové řetězce se objevují v angličtině i na „plně přeloženém“ webu, protože nikdy nebyly v souboru .pot, ze kterého překladatel pracoval. Zamezit tomu je stejně jednoduché jako zautomatizovat regeneraci do vašeho build procesu, takže šablona nikdy nemůže zaostávat za kódem. Některé týmy přidávají kontrolu v CI, která selže, pokud regenerace .pot vytvoří rozdíl, čímž zaručují, že odevzdaná šablona vždy odpovídá aktuálnímu zdroji.
Jakmile překladatelé vrátí dokončené soubory .po, ty je stále třeba zkompilovat do binárního .mo souboru, který WordPress skutečně načítá — a pokud byste raději přeskočili celý cyklus stahování-překladu-rekompilace, cloudový nástroj to zvládne od začátku do konce. SimplePoTranslate přijímá váš .pot přímo, překládá ho pomocí Context-Aware AI, která rozumí, co každý řetězec znamená ve vašem rozhraní, a vrátí jediný ZIP se soubory .po, .mo a dalšími, již vytvořenými a pojmenovanými. Jeho Syntax Locking zmrazí zástupné symboly jako %s a %1$s, takže se vaše proměnné v překladu nikdy nerozbijí.
Shrnutí
Chcete-li vytvořit soubor POT správným způsobem, nejprve zajistěte, aby byl váš kód zjistitelný — zabalte každý viditelný řetězec do __(), _e(), _x() nebo varianty s escapováním, přičemž všechny sdílí jednu textovou doménu, a deklarujte tuto doménu a Domain Path ve svém záhlaví. Poté vygenerujte šablonu pomocí WP-CLI pro nové projekty, Poedit, pokud preferujete GUI, nebo makepot pouze při údržbě staršího kódu.
Generujte brzy, regenerujte často a nikdy nedovolte, aby vaše šablona zaostávala za vaším kódem. Aktuální .pot je rozdílem mezi pluginem, který je skutečně připraven pro svět, a tím, který to jen tvrdí.
Jste připraveni proměnit svou šablonu
.potv hotové překlady bez ručního kompilování? Vyzkoušejte SimplePoTranslate zdarma — není vyžadována kreditní karta. Nahrajte svou šablonu v bezplatné verzi a stáhněte si hotové překladové soubory během několika minut.