Lokalizace webové aplikace

Propojte přeložené katalogy s výběrem jazyka, načítáním prostředků a kontrolami vykreslování ve svém frameworku.

Pokud vaše webová aplikace už vykresluje zprávy z jazykových souborů, ponechte toto funkční řešení. Lingo.dev může překládat zdrojové katalogy, zatímco stávající knihovna bude dál vybírat jazyk, načítat zprávy a vykreslovat je. Než začnete překládat zbytek aplikace, projděte celý tento cyklus na jedné obrazovce.

Tento průvodce se věnuje stávajícím katalogům s klíči v různých frameworcích. Pro zprávy definované zdrojovým textem a kontextem pomocí @lingo.dev/react použijte rychlý start pro React nebo průvodce migrací. Identifikátory získané touto extrakcí se liší od klíčů ve stávajícím katalogu i18next nebo next-intl.

Připravte jeden testovací scénář pro celý proces #

Vyberte obrazovku s popiskem, zprávou obsahující proměnnou a zprávou s množným číslem nebo podmínkou. Vykreslete ji ve zdrojovém jazyce pomocí stávající knihovny. Zachovejte její jmenné prostory, syntaxi interpolace a vyhledávací klíče; obecný překlad JSON nepřevádí syntaxi zpráv jedné knihovny na syntaxi jiné.

Pokud máte stávající zdroj react-i18next v public/locales/en/translation.json, inicializujte CLI z kořenového adresáře projektu:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo link

Propojený soubor .lingo/config.json by měl vypadat takto:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [{ "pattern": "public/locales/en/translation.json" }]
}

Ponechte skutečná ID organizace a lokalizačního engine získaná při propojení. U jiného frameworku použijte odpovídající zdrojovou cestu z níže uvedených částí. Vyberte pouze zdrojové katalogy a nastavte cílovou cestu tak, aby odpovídala načítači. U struktur bez jazykového segmentu použijte explicitní cílové cesty.

Chybějící cílové překlady vytvoříte příkazem:

sh
lingo push --backfill-missing --wait

Po dokončení zkontrolujte vygenerovaný katalog a načtěte obrazovku ve španělštině. V obou jazycích porovnejte stejné hodnoty proměnných a varianty množného čísla. Níže uvedený krok pro konkrétní framework propojí tento soubor se skutečným požadavkem nebo sestavením. Prvním běžným příkazem push můžete uložit výchozí stav, aniž byste vyžádali chybějící překlady.

Během čekání na zpětný zápis cílové soubory neměňte. Pokud potřebujete chránit stávající ruční opravy před konflikty, odešlete bez --wait, zkontrolujte lingo pull --dry-run a poté výsledek stáhněte ve stejném checkout, ze kterého jste odesílali. Viz Zachování zkontrolovaných překladů.

React s react-i18next #

Při práci s react-i18next zachovejte stávající jmenné prostory a volání pro vyhledávání zpráv. Zdroj public/locales/en/translation.json odpovídá cíli public/locales/es/translation.json. Pokud aplikace používá více jmenných prostorů, nakonfigurujte každý anglický zdroj zvlášť místo vzoru glob, který by zahrnul i vygenerované španělské soubory.

Zajistěte, aby načítač prostředků i18next požadoval cílový jazyk a jmenný prostor. Poté vykreslete testovací obrazovku pomocí stávajících volání useTranslation. Zkontrolujte dosazování proměnných a konvenci klíčů pro množné číslo, kterou používá nainstalovaná verze i18next. Obecný překladač JSON nepřevádí schéma množného čísla jedné knihovny na schéma jiné. V klientské aplikaci zkontrolujte kromě viditelného textu také síťový požadavek na prostředek; náhradní anglický text může skrýt chybějící španělský soubor.

Next.js App Router s next-intl #

U next-intl je běžným zdrojem messages/en.json, ze kterého vznikne messages/es.json. V nastavení next-intl nakonfigurujte určení jazyka při zpracování požadavku a načtení odpovídajících zpráv. Této volbě musí odpovídat i jazykové trasy a navigace.

Vykreslete testovací obrazovku jak přímým požadavkem v cílovém jazyce, tak přechodem z jiného jazyka. Zkontrolujte obsah vykreslený na serveru, hydrataci na klientovi a proměnné či tvary množného čísla ICU. Samotný překlad souboru se zprávami nepřidá do App Router jazykový segment ani přepínač jazyků. Pro delší dokumenty vedle těchto katalogů uživatelského rozhraní použijte Markdoc s Next.js.

Next.js Pages Router s next-i18next #

Při práci s next-i18next nastavte vzor zdrojových souborů tak, aby odpovídal stávajícímu adresáři jazyků a jmenným prostorům. Pokud jde o public/locales/en/common.json a public/locales/en/checkout.json, přeložte oba do odpovídajících španělských souborů. Pokud používáte messages/en.json, ponechte vlastní načítač, který tento soubor skutečně používá.

Načtěte potřebné jmenné prostory stávajícím mechanismem stránky pro načítání dat na serveru nebo při statickém generování. Ověřte přímý požadavek na lokalizovanou stránku i změnu trasy na klientovi. Zkontrolujte, že počáteční data stránky a klientské běhové prostředí používají stejný jazyk a jmenný prostor; přeložený soubor na disku nestačí, pokud ho stránka vůbec nezahrne.

Vue s vue-i18n #

vue-i18n umí načítat slovníky jako src/locales/en.json a src/locales/es.json. Přeložte anglický zdroj a ve stávající instanci i18n zaregistrujte nebo dynamicky načtěte španělský slovník. Vybraný jazyk nastavte tam, kde ho vaše aplikace už spravuje.

Na testovací obrazovce vyzkoušejte volání $t nebo useI18n. Zkontrolujte vnořené klíče, interpolaci a syntaxi zpráv s množným číslem v nainstalované knihovně. Otestujte přepnutí jazyka bez opětovného načtení i nové načtení stránky. Pokud se slovníky zahrnují do balíčku pomocí importů, ověřte, že je přeložený soubor součástí sestavení.

Nuxt s modulem i18n #

Pro Nuxt i18n přeložte zdroj, například locales/en.json, do locales/es.json. Zaregistrujte jazyk a soubor v konfiguraci modulu podle nainstalované verze. Slaďte nastavený adresář jazyků s výstupní cestou CLI.

Držte se strategie jazykových tras, kterou projekt používá, a nevytvářejte v překladové úloze druhou. Na testovací stránce ověřte vykreslování na serveru, odložené načítání, lokalizovanou navigaci a metadata. Přidání cílového jazyka do konfigurace překladu ho samo o sobě nepřidá do seznamu jazyků v Nuxt.

Slovníky ve Svelte a SvelteKit #

Pro svelte-i18n přeložte slovník, například src/lib/locales/en.json. Zaregistrujte cílový slovník nebo funkci pro jeho odložené načtení a inicializujte vybraný jazyk dříve, než ho komponenta bude potřebovat.

Vykreslete testovací obrazovku prostřednictvím stávajícího úložiště překladů aplikace. Pokud aplikace používá SSR, otestujte nový požadavek s vykreslením na serveru a poté změnu jazyka na klientovi. Zkontrolujte, že se stav jazyka nesdílí mezi serverovými požadavky a že se cílový slovník načte celý. Náhradní výstup nepovažujte za důkaz dokončeného překladu.

Angular XLIFF #

Nejprve pomocí workflow i18n v Angularu označte a extrahujte zprávy. Obsluha formátu XLIFF podporuje XLIFF 1.2 a 2.x včetně prostého textu a vložených kódů. Text uvnitř párových kódů, jako jsou <g> a <pc>, se překládá při zachování jejich struktury; samostatné kódy jako <ph> zůstávají chráněné. Identifikátory zpráv a vložených kódů neměňte a před importem cílového katalogu zkontrolujte vrácené zástupné symboly.

U podporovaného vstupu odpovídá src/locale/en/messages.xlf cíli src/locale/es/messages.xlf. XLIFF nepoužívá nahrazování přípony z messages.en.xlf na messages.es.xlf; použijte adresář jazyka nebo explicitní cílovou šablonu. Při vracení překladů do Angularu zachovejte identifikátory zpráv.

Zaregistrujte cílový soubor v konfiguraci lokalizačního sestavení Angularu, sestavte balíček pro cílový jazyk a zpřístupněte ho na serveru, abyste mohli obrazovku zkontrolovat. Lokalizace Angularu při kompilaci se liší od načítání JSON za běhu: změna jazyka prohlížeče nesestaví chybějící lokalizovaný balíček. Před schválením balíčku zkontrolujte pokrytí zpráv a vykreslování zástupných symbolů.

Astro #

Pro popisky uživatelského rozhraní přeložte src/i18n/en.json do odpovídajícího cílového souboru a zajistěte, aby ho váš načítač slovníků vybral. U kolekcí obsahu přeložte zdrojové soubory Markdown nebo MDX pro jednotlivé jazyky a použijte workflow pro statický obsah.

Nakonfigurujte jazykové směrování v Astro nezávisle na překladu. Sestavte aplikaci a navštivte vygenerované cílové trasy. Zkontrolujte odkazy mezi jazykovými verzemi i všechny klientské ostrůvky, které načítají vlastní zprávy. Kolekce obsahu a slovník uživatelského rozhraní ostrůvku mohou vyžadovat samostatné vstupy.

Laravel #

Při lokalizaci ve frameworku Laravel odpovídá zdroj PHP, například lang/en/messages.php, cíli lang/es/messages.php. Zachovejte klíče polí a názvy proměnných dosazovaných za běhu. Než vyberete soubory obsahující spustitelný kód nad rámec podporované struktury katalogu, prostudujte si referenci formátu PHP.

Nastavte jazyk požadavku prostřednictvím stávajícího middlewaru nebo pravidel řadiče aplikace a vykreslujte zprávy pomocí překladových pomocných funkcí frameworku Laravel. Vyzkoušejte dosazované hodnoty a výběr tvarů množného čísla. Otestujte požadavek v každém podporovaném jazyce i případ s náhradním jazykem; přeložené soubory samy jazyk požadavku nevybírají.

Django #

Pomocí extrakčního workflow Djanga vytvořte locale/en/LC_MESSAGES/django.po a poté tento zdrojový soubor PO přeložte do adresáře cílového jazyka. Zachovejte identifikátory zpráv gettext, kontext a interpolaci. Stávajícím krokem sestavení gettext v projektu zkompilujte přeložený soubor PO do prostředku, který Django skutečně načítá.

Nakonfigurujte výběr jazyka v Djangu a seznam jazyků. Ověřte lokalizovaný požadavek přes překladový middleware a vykreslete zprávy pomocí volání pro jednotné i množné číslo. Samotná existence souboru PO na disku nedokazuje, že je jeho zkompilovaný katalog aktuální. Požadavky na soubor najdete v části Gettext.

Rails #

Rails rozpoznává soubory YAML s jazykem na kořenové úrovni podle kořenového klíče. Vyberte yaml-root-key a poté ověřte konfiguraci jazyků v Rails, pomocné funkce a interpolaci. Úplný postup včetně souborů členěných podle oblastí, přepínání jazyka požadavku a cílených aktualizací najdete v průvodci Lokalizace aplikace Rails.

Zajistěte výstup vhodný ke kontrole i při opakovaných překladech #

Jakmile obrazovka funguje, přidejte zbývající zdrojové katalogy a jejich načítače. Schválené cílové překlady uchovávejte spolu s revizí zdroje a souborem Lockfile pro CLI. Při pozdějších změnách zdroje použijte lingo push --wait pro běžné zpracování rozdílů; zadáním vzoru souborů jako pozičního argumentu místo toho vyberete plánování s omezeným rozsahem.

Nastavte spouštění při změnách zdroje a zpětný zápis prostřednictvím GitHub App nebo postupů pro CI. Postupy pro GitLab, Bitbucket a GitHub Actions spouštějí CLI a potřebují vlastní mechanismus zpětného zápisu do repozitáře. S výstupem spusťte sestavení nebo kontroly prostředků daného frameworku a poté zkontrolujte význam překladu. lingo check neověřuje všechny frameworky ani nezaručuje úplnost PHP, PO nebo XLIFF.

Agent může pomoci zkontrolovat načítače a navrhnout změny konfigurace. Než workflow rozšíříte, proveďte i u těchto úprav stejné kontroly výběru zdrojů, sestavení a vykreslené obrazovky.