Propojte svůj Payload CMS s lokalizačním enginem, vyberte kolekce a globals, které chcete zahrnout, a Lingo.dev přeloží jejich lokalizovaná pole do cílových jazyků a zapíše je zpět do Payloadu pod příslušný jazyk.
Funguje v projektech Payload 3 s aktivní lokalizací, které používají editor formátovaného textu Lexical. Starší editor Slate podporovaný není. Překládají se lokalizovaná pole text, textarea a richText. Všechno ostatní v dokumentu zůstává beze změny.
Integrace s Payload se zapíná pro každou organizaci zvlášť. Pokud ji nevidíte v Settings -> Integrations, ozvěte se nám a aktivujeme ji pro vás.
Než začnete#
Potřebujete tři věci:
- Payload 3 s nastavenou lokalizací. Ujistěte se, že váš zdrojový a cílový jazyk odpovídají jazykům v konfiguraci Payload.
- Servisní uživatel s API klíčem. Ve své auth kolekci (obvykle
useAPIKey: true) nastavteusers, vytvořte uživatele pro Lingo.dev a v administraci Payloadu mu vygenerujte API klíč. Uživatel potřebuje oprávnění read a update ke každé kolekci a každému globalu, které chcete překládat. - Lokalizační engine. Jeho glosář, hlas značky a pravidla určují výslednou podobu překladů.
Kódy jazyků musí odpovídat konfiguraci Payload
Jazyky, které vyberete v Lingo.dev, se musí přesně shodovat s kódy pod localization.locales. Pokud má Payload en a de, vyberte angličtinu a němčinu, ne angličtinu (Spojené státy): en-US a en jsou různé jazyky. Jako zdrojový jazyk použijte svůj Payload defaultLocale, protože právě tento jazyk plugin sleduje kvůli změnám.
Připojte svou instanci Payload#
Otevřete integraci
Přejděte do Settings -> Integrations a pod Payload CMS klikněte na Connect.
Zadejte údaje o své instanci
| Pole | Co zadat |
|---|---|
| Název připojení | Štítek, například Production nebo Staging |
| Payload Base URL | Kořenová URL vaší instance, např. https://cms.example.com. Pouze HTTPS |
| Auth Collection Slug | Collection, ke které patří API klíč vašeho servisního uživatele, obvykle users |
| API Key | API klíč servisního uživatele |
| Vlastní hlavičky | nepovinné. Odesílá se s každým požadavkem do vaší instance |
Lingo.dev před pokračováním ověří klíč vůči vaší instanci.
Vyberte, co chcete překládat
| Nastavení | Co dělá |
|---|---|
| Collections and Globals | Zaškrtněte ty, které chcete překládat. Řádek označený No read + update zůstane neaktivní, dokud k němu servisní uživatel nedostane přístup |
| Source Locale | Jazyk, ve kterém vaši editoři píšou. Použijte svůj Payload defaultLocale |
| Target Locales | Jazyky, do kterých se má překládat |
| Engine | Lokalizační engine, který překládá tento obsah |
| Translate draft saves | Vypnuto překládá jen publikované změny. Zapnuto překládá i uložení konceptů a ponechává překlady jako koncepty |
Nainstalujte plugin
V posledním kroku se zobrazí vaše webhook URL. Zkopírujte si ji hned. Zobrazí se pouze jednou. Uložte ji jako LINGO_WEBHOOK_URL do prostředí Payloadu, potom nainstalujte plugin a přidejte ho do konfigurace:
pnpm add @lingo.dev/payloadcmsimport { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
// ...your collections, globals, and localization config
plugins: [
lingo({
webhookUrl: process.env.LINGO_WEBHOOK_URL,
}),
],
});Znovu nasaďte Payload. Od této chvíle se každá změna publikovaná ve zdrojovém jazyce odešle do Lingo.dev k překladu.
Co plugin dělá
Přidá endpoint GET /api/lingo/schema, který Lingo.dev řekne, která vaše pole jsou lokalizovaný text, a hook, který upozorní Lingo.dev při změně dokumentu nebo globalu. Rozsah, jazyky a engine nastavujete v dashboardu, takže je můžete měnit bez nového nasazení. Když vynecháte webhookUrl, hook se přeskočí a každý překlad budete spouštět z dashboardu.
Vyberte, co se bude překládat#
Stránka připojení má tři záložky: Collections, Globals a Runs.
Rozsah se nastavuje pro každou kolekci i každý global zvlášť. Zahrnutý je každý dokument ve vybrané kolekci. Pokud chcete změnit rozsah, jazyky, engine nebo nastavení konceptů, klikněte v záhlaví stránky na Edit configuration. Změny se projeví při dalším běhu bez nového nasazení.
Uvnitř dokumentu určuje, co se přeloží, konfigurace polí v Payload:
| Pole | Překládá se |
|---|---|
Pole text, textarea a richText označená jako localized: true | Ano |
Stejné typy polí uvnitř lokalizovaného group, array, blocks nebo tabs | Ano |
| Blocks a inline blocks vložené do rich textu | Ano, jejich textová pole podle stejných pravidel |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | Ne |
| Pole, která nejsou lokalizovaná a nemají žádný lokalizovaný nadřazený prvek | Ne |
id, blockType, blockName | Ne |
Formátovaný text se překládá jako strom Lexical. Zachová se formátování, odkazy, nahrané soubory i struktura bloků a nahradí se pouze text uvnitř. Věta rozdělená tučným písmem nebo odkazem se přeloží jako jedna věta.
Chcete-li pole zahrnout do rozsahu, označte ho v Payloadu jako localized: true a znovu nasaďte aplikaci. Při dalším běhu se zahrne.
Synchronizace a nový překlad#
Automatická spuštění. Když v pluginu nastavíte webhookUrl, každé uložení dokumentu nebo globálu ve zdrojovém jazyce odešle oznámení do Lingo.dev. Uložení provedená v krátkém časovém rozmezí se sloučí do jednoho spuštění. Uložení v jiných jazycích, uložení konceptů (pokud není zapnutá možnost Překládat uložení konceptů) a obsah mimo váš rozsah se ignorují.
Ruční běhy. Každý řádek kolekce, globalu i dokumentu má dvě tlačítka:
| Tlačítko | Co dělá | Kdy ho použít |
|---|---|---|
| Sync | Přeloží jen to, co se od posledního běhu změnilo | Doplnění obsahu po připojení nebo opakování po chybě |
| Retranslate | Znovu přeloží vše v řádku od začátku | Po změně glosáře, hlasu značky nebo pravidel vašeho enginu |
Otevřete kolekci a dostanete se k jejím dokumentům, které můžete synchronizovat po jednom. Obě karty ukazují, kdy byla každá položka naposledy synchronizovaná.
Při připojení se nic nepřekládá. Pokud chcete přeložit obsah, který už máte, klikněte u každé kolekce a globalu na Sync. Stejně funguje i pozdější přidání cílového jazyka: vyplní se při příštím Sync.
Na jedno připojení může právě probíhat jen jeden běh. Další požadavky se zařadí do fronty a spouštějí se postupně. Dokud je řádek zahrnutý v čekajícím nebo běžícím běhu, jeho tlačítka zobrazují Syncing....
Retranslate přepíše ruční úpravy
Retranslate znovu vygeneruje každé přeložené pole ve svém rozsahu, včetně překladů, které váš tým v Payloadu upravil ručně. Sync znovu vygeneruje jen pole, jejichž zdrojový text se změnil, takže ruční úpravy jinde zůstanou zachované.
Sledujte běh#
Karta Runs uvádí každý běh s jeho stavem, spouštěčem (Webhook nebo Manual, sync nebo retranslate), časem spuštění a délkou trvání. Čekající nebo běžící běh můžete ze seznamu zrušit.
Otevřete běh a uvidíte, v jaké je fázi (čtení z Payloadu, překlad, zápis zpět), celkový průběh, průběh podle cílového jazyka i dokumenty, kolekce a globals, které zahrnuje. Každá položka odkazuje do administrace Payloadu.
| Stav | Význam |
|---|---|
| Ve frontě | Čeká na běh před sebou |
| Probíhá | Zpracovává se |
| Dokončeno | Všechny překlady byly zapsány zpět |
| Aktuální | Od posledního běhu se v rozsahu nic nezměnilo. Nejde o chybu |
| Nezdařilo se | Běh se zastavil. Důvod je zobrazený nahoře v detailu běhu |
| Zrušeno | Zastavil ho někdo z vašeho týmu |
Neúspěšné spuštění zachová vše, co už se stihlo zapsat. Chybová zpráva vypíše dokumenty, které se nezapsaly, a při dalším Sync se jejich zápis zkusí znovu. Dokument, který editor během běhu uložil, se přeskočí a zpracuje při dalším spuštění.
Kam se překlady zapisují#
Každý překlad se zapisuje do stejného dokumentu nebo globálu pod svým cílovým jazykem podle vlastního lokalizačního modelu Payload. Zapisují se jen přeložená pole. Všechna ostatní pole zůstávají beze změny. Zápis probíhá pod servisním uživatelem a nespustí nové spuštění.
Existující překlady se zachovávají. Při první synchronizaci dokumentu zůstane vše, co už cílový jazyk obsahuje, na místě, a přeloží se jen chybějící pole. Pole, které stále obsahuje výchozí hodnotu Payloadu, se považuje za chybějící. Pomocí Retranslate nahradíte existující překlady.
Koncepty vs. publikované#
Když je možnost Translate draft saves vypnutá (což je výchozí nastavení), spustí běh jen publikované změny a překlady se publikují hned po zapsání. Payload publikuje celý dokument, takže se spolu s překladem zveřejní i všechny nepublikované úpravy konceptu v něm.
Když je zapnuté, běhy spouští i uložení konceptů. Lingo.dev načte nejnovější koncept zdroje a každý překlad zapíše jako koncept. Pro vaše čtenáře se nic nezmění, dokud někdo překlad v Payloadu nepublikuje. To se hodí při vyhodnocování kvality překladů nebo když překlady procházejí kontrolou.
Správa připojení#
Obnovení webhook URL#
V záhlaví stránky připojení otevřete nabídku a zvolte Znovu vygenerovat URL webhooku. Původní adresa URL okamžitě přestane fungovat. Aktualizujte LINGO_WEBHOOK_URL a znovu nasaďte. Při úpravě připojení zůstává URL stejná.
Odpojení#
Odpojte se v Settings -> Integrations -> Payload CMS. Tím se odstraní připojení, jeho historie běhů i záznam o tom, co už bylo přeloženo. Překlady už zapsané v Payloadu zůstanou zachované. Potom odeberte LINGO_WEBHOOK_URL nebo plugin ze své konfigurace.
Po opětovném připojení dostanete novou webhook URL
Nové připojení dostane novou webhook URL, takže než budou automatické běhy znovu fungovat, aktualizujte LINGO_WEBHOOK_URL a proveďte nové nasazení. První synchronizace znovu načte každý dokument v rozsahu, ponechá překlady, které už Payload má, a doplní chybějící místa.
Omezení#
| Limit | Detail |
|---|---|
| Verze Payloadu | Payload 3 s nakonfigurovanou lokalizací |
| Typy polí | Pole text, textarea a richText (pouze Lexical) označená jako localized |
| Rozsah | Celé kolekce a globály. Bez možnosti výběru jednotlivých polí |
| Připojení | Několik na organizaci, jedna pro každou Payload instanci |
| Souběžné běhy | Jedna na připojení |
| Base URL | Pouze HTTPS |
Řešení potíží#
Připojení selže se zprávou „Payload rejected the API key“. Zkontrolujte klíč, slug auth kolekce a také to, že je na této kolekci zapnuté useAPIKey.
Kolekce nebo global zobrazuje „No read + update“. Udělte servisnímu uživateli oprávnění read a update v access konfiguraci dané kolekce a potom konfiguraci znovu otevřete.
První běh selže se zprávou „The Lingo plugin isn't installed“. Přidejte @lingo.dev/payloadcms do plugins ve své Payload konfiguraci a znovu nasaďte aplikaci. Připojení funguje i bez pluginu, synchronizace ale ne.
Publikování v Payloadu nespustí běh. Zkontrolujte, že je nastavené LINGO_WEBHOOK_URL, že je nakonfigurované localization, že kolekce nebo global spadá do rozsahu, že uložení proběhlo ve zdrojovém jazyce a že šlo o publikování, ne o koncept.
Pole se nepřekládá. Není u něj ani u žádného nadřazeného prvku nastavené localized: true, nebo nejde o pole typu text, textarea nebo richText.
Připojení zobrazuje „Couldn't reach this Payload instance“. Zkontrolujte, že instance běží, klíč je stále platný a všechny hlavičky gateway pořád fungují. Připojení aktualizujte v Settings -> Integrations.
