Jak přeložit WordPress plugin (krok za krokem)

Našli jste perfektní WordPress plugin pro váš projekt. Dělá přesně to, co potřebujete, recenze jsou zářivé, a pak jej aktivujete a uvědomíte si, že každé tlačítko, popisek a chybová zpráva jsou v angličtině. Vaši německy, francouzsky nebo japonsky mluvící návštěvníci narazí na zeď textu, který si nemohou přečíst.

Dobrou zprávou je, že většina dobře vytvořených pluginů je připravena k překladu (translation-ready), což znamená, že vývojář obalil své řetězce funkcemi Gettext speciálně proto, aby je lidé jako vy mohli přeložit. Výzvou je vědět, kde se soubory nacházejí, jak pojmenovat váš překlad a kam jej umístit, aby další aktualizace pluginu nepřepsala vaši práci.

Tento průvodce vám ukáže, jak přeložit WordPress plugin od začátku do konce: nalezení textové domény a složky pro jazyky, získání nebo vygenerování šablony .pot, vytvoření správně pojmenovaných souborů .po a .mo a jejich umístění tam, kde je WordPress spolehlivě načte. Probereme také jeden typ pluginu, který tento přístup nemůže plně přeložit, abyste neztráceli hodiny bojem s nemožným případem.

Jak najít soubory pro překlad pluginu?

Před jakýmkoli překladem potřebujete z pluginu dvě informace: jeho textovou doménu a jeho složku pro jazyky. Textová doména je jedinečný řetězec, který plugin používá k identifikaci vlastních překladů, a složka pro jazyky je místo, kde se nachází zdrojová šablona.

Nalezení složky pro jazyky a textové domény

Otevřete adresář pluginu na wp-content/plugins/your-plugin/ a vyhledejte podsložku /languages. Uvnitř obvykle najdete soubor .pot, prázdnou šablonu obsahující všechny přeložitelné řetězce.

Pro potvrzení textové domény otevřete hlavní PHP soubor pluginu a podívejte se na jeho hlavičkový blok:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Zde je textová doména awesome-plugin. Tato hodnota je kritická, protože vaše překladové soubory ji musí obsahovat ve svých názvech, jinak je WordPress nikdy nespáruje s pluginem. Uvidíte ji také v každém volání řetězce v celém kódu:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Druhý argument, awesome-plugin, je opět textová doména. Každý řetězec, který ji používá, může být přeložen vaším katalogem. Pokud řetězci v rozhraní pluginu chybí tento obal, například vývojář, který napevno zakódoval echo 'Save' bez __(), pak tento řetězec vůbec není přeložitelný a žádný soubor .po k němu nemůže dosáhnout. Většina renomovaných pluginů obaluje vše správně, ale pokud si všimnete jednoho nebo dvou tvrdohlavých řetězců, které se odmítají přeložit, pravděpodobnou příčinou je chybějící obal Gettext ve zdroji.

Rychlý způsob, jak zjistit, zda je plugin skutečně připraven k překladu, je zkontrolovat jeho záznam v adresáři WordPress.org, který zobrazuje procento překladů a odkazuje na šablonu /languages. Plugin s aktivním překladovým projektem má mnohem větší pravděpodobnost, že bude mít čisté, plně obalené řetězce než ten opuštěný.

Co když plugin nemá soubor POT?

Některé pluginy se dodávají bez šablony .pot. Pokud je složka /languages prázdná nebo chybí, musíte šablonu vygenerovat sami prohledáním zdrojového kódu pro přeložitelné řetězce.

Standardním nástrojem pro to je WP-CLI, které extrahuje každé volání Gettext do nové .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Tento příkaz prochází PHP a JavaScript soubory pluginu, najde každé volání __(), _e(), _n() a související volání a zapíše kompletní šablonu. Pokud preferujete grafickou cestu, Poedit Pro dokáže skenovat zdrojový kód stejným způsobem. Ať tak či onak, výsledkem je .pot obsahující všechny zdrojové řetězce s prázdnými překlady, připravené k přeměně na skutečný jazykový soubor.

Generování vlastní šablony má skrytou výhodu: zachycuje řetězce, které původní vývojář možná zapomněl zahrnout do dodaného .pot. Pluginy se rychle vyvíjejí a šablona, která přišla s verzí 2.1, může postrádat řetězce přidané ve verzi 2.4. Opětovné generování z aktuálního zdroje zaručuje, že váš katalog odráží to, co plugin skutečně zobrazuje dnes, nikoli to, co zobrazoval před dvěma verzemi. Pokud dlouhodobě udržujete překlady pro plugin, spolehlivým zvykem je spouštět make-pot po každé větší aktualizaci.

Vytvoření souborů PO a MO se správným názvem

Nejčastější chybou při překladu pluginu je název souboru. WordPress hledá překlady pluginů podle velmi specifického vzoru a jeden špatný znak znamená, že váš překlad bude zcela ignorován.

Vzorec pro název souboru

Pro překlady pluginů je vzor text-domain-locale. Takže pro textovou doménu awesome-plugin přeloženou do němčiny musí být soubory pojmenovány:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Kód lokality je kód jazyka WordPress webu: de_DE pro němčinu, fr_FR pro francouzštinu, es_ES pro španělštinu, pt_BR pro brazilskou portugalštinu. Zadejte špatný kód lokality a WordPress váš soubor tiše přeskočí. Tyto soubory vytváříte ze šablony .pot v editoru jako je Poedit, který automaticky zkompiluje binární .mo při uložení. Pokud s tímto editorem začínáte, kompletní průvodce Poedit vás provede vytvořením překladu ze šablony krok za krokem.

Kam umístit soubory, aby je aktualizace nevymazaly

Existují dvě možná umístění a výběr toho správného je důležitý.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Vždy používejte wp-content/languages/plugins/. WordPress nejprve kontroluje tento přepisující adresář, a protože se nachází mimo složku pluginu, aktualizace pluginu se nikdy nedotkne vašich překladů. Soubory umístěné uvnitř vlastní složky pluginu se přepíšou v okamžiku instalace nové verze.

Toto chování přepisu je jednou z nejužitečnějších a nejméně známých funkcí lokalizace WordPressu. Znamená to, že můžete dodávat vlastní nebo opravené překlady pro jakýkoli plugin třetí strany, aniž byste jej kdy forkovali, a vaše změny jsou zcela bezpečné proti aktualizacím. Pokud spravujete několik klientských webů se stejným pluginem, můžete dokonce udržovat jedinou sadu souborů .mo pro přepsání a nasadit je na všechny, s vědomím, že každý web je automaticky převezme, pokud se lokalita shoduje.

Jak WordPress načítá váš překlad

Plugin připravený k překladu říká WordPressu, aby načetl svůj katalog voláním load_plugin_textdomain() během inicializace:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

U většiny moderních pluginů na WordPressu 4.6 a novějších se toho nemusíte dotýkat. WordPress automaticky načítá překlady z wp-content/languages/plugins/, pokud se shoduje název vašeho souboru a lokalita webu. Pokud se váš dokončený překlad stále neobjeví, příčinou je téměř vždy neshoda názvu souboru, zastaralý .mo soubor nebo jazyk webu nastavený na nesprávnou lokalitu. Náš průvodce řešením problémů s nezobrazujícími se překlady prochází každý z těchto bodů selhání.

Pluginy, které ukládají řetězce do databáze

Zde je důležité omezení. Přístup Gettext překládá pouze řetězce, které se nacházejí v kódu pluginu. Některé pluginy, zejména tvůrci formulářů, tvůrci stránek a rozšíření pro e-commerce, vám umožňují vytvářet obsah (popisky formulářů, atributy produktů, vlastní zprávy), který se ukládá do databáze WordPressu. Tyto řetězce jsou uživatelsky generovaná data, nikoli součást .pot, takže soubor .po k nim nemůže dosáhnout. Pro obsah databáze potřebujete vícejazyčný plugin jako WPML nebo Polylang, nebo vlastní funkci pluginu pro překlad řetězců. Vždy testujte, zda daný řetězec žije v kódu nebo v databázi, než předpokládáte, že soubor .po to může opravit.

Jednoduchý test vám řekne, s jakým typem řetězce máte co do činění. Pokud je text něco, co jste napsali do pole nastavení, popisek formuláře, který jste vytvořili, vlastní zpráva poděkování, název produktu, jedná se o obsah databáze a soubor .po se ho nemůže dotknout. Pokud je text součástí vestavěného rozhraní pluginu, popisky tlačítek, chyby ověření, administrátorské oznámení, které se dodává se samotným pluginem, žije v kódu a soubor .po je přesně ten správný nástroj. Jasné vymezení této hranice včas ušetří hodiny frustrace, protože žádné množství perfektního úpravy .po nikdy nepřeloží řetězec, který plugin načítá z databáze za běhu.

Hromadný překlad bez ruční práce

Přeložit jeden plugin do jednoho jazyka ručně je zvládnutelné. Přeložit jej do deseti jazyků, nebo přeložit celou sadu pluginů pro klientský web, se změní v dny opakované práce, a každá ruční úprava riskuje zamíchání zástupného symbolu jako %s nebo %1$s a rozbití výstupu.

Zde cloudový pracovní postup mění celou rovnici. Nahrajte soubor .po nebo .pot pluginu na SimplePoTranslate, vyberte cílové jazyky, a AI s kontextovým povědomím přeloží celý katalog, zatímco Syntax Locking zmrazí každý zástupný symbol, HTML tag a kódový token, aby se nic nerozbilo. Smart Batching zpracovává velké katalogy v jediném průchodu a vy si stáhnete ZIP obsahující .po, .mo, .json, .php a .xliff dohromady, správně naformátované a připravené k vložení do wp-content/languages/plugins/. Běží to kompletně v cloudu, takže není třeba žádná desktopová instalace a žádné zatížení vašeho webu.

Všimněte si, že překlad pluginu se liší od překladu šablony (theme), která používá mírně odlišnou konvenci složek a funkci načítání. Pokud je vaším cílem šablona, místo toho se řiďte naším specializovaným průvodcem lokalizací jakékoli WordPress šablony, i když nejste vývojář.

Použijte ruční cestu, když máte jeden plugin a jeden jazyk. Použijte cloud, když potřebujete mnoho jazyků, rychle a bez obětování bezpečnosti zástupných symbolů.

Jste připraveni přeložit váš WordPress plugin do každého jazyka, kterým mluví vaše publikum, aniž byste rozbili jedinou proměnnou? Vyzkoušejte SimplePoTranslate zdarma — není vyžadována žádná platební karta. Bezplatná úroveň vám umožní přeložit váš první soubor .po pluginu během několika minut, s funkcí Syntax Locking na každém řetězci.