Migrace stávajících zpráv v Reactu

Převeďte malou testovací sadu zpráv v Reactu na explicitně definované zprávy se zdrojovým textem a kontextem. Zachovejte přitom zástupné symboly, chování tvarů množného čísla i schválené překlady.

Ve stávajícím katalogu zpráv v Reactu už je řada užitečných rozhodnutí: identifikátory pro vyhledávání, pravidla interpolace, chování tvarů množného čísla i překlady, které už někdo zkontroloval. Přechod na zprávy se zdrojovým textem a kontextem by měl tuto práci zachovat. Nejprve převeďte jednu celou komponentu, přiřaďte její schválené překlady k novým identifikátorům a před rozšířením migrace porovnejte výsledek vykreslování.

Před změnou identifikátorů zaznamenejte původní chování #

Vyberte komponentu s popiskem, proměnnou, odkazem, počtem a podmíněnou zprávou. Uložte její původní klíče, zdrojové i cílové znění, syntaxi interpolace, jmenný prostor a jazyk poskytovatele. Vykreslete ji s pevně danými hodnotami ve zdrojovém a jednom cílovém jazyce. Získáte tak konkrétní výsledek, který má migrace zachovat.

Stávající volání ve stylu i18next může vypadat například takto:

tsx
t("account.greeting", { name });

Jeho zdrojový katalog může obsahovat Welcome, {{name}}. Tuto syntaxi interpolace nepřebírejte beze změny do nového kontraktu zpráv. Explicitně definovaná zpráva v Reactu používá pojmenovanou proměnnou {name}:

tsx
l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

Zde uvedená změna oddělovačů platí pro konkrétní konfiguraci původní knihovny. Než převedete další zprávy, ověřte nastavení nainstalované knihovny: vlastní oddělovače interpolace a konvence pro množná čísla mohou vyžadovat jiné úpravy.

Mapujte chování zpráv, nejen názvy metod #

Pro prosté zprávy s hodnotami použijte text, pro pojmenované sloty komponent rich, pro tvary závislé na počtu plural a pro alternativy podle přesné hodnoty select se záložní variantou other. Úplný příklad všech čtyř možností najdete v části Interaktivní zprávy s bohatým obsahem.

Původní komponenta pro zprávy s bohatým obsahem může odkazy kódovat pomocí indexů. Nahraďte je smysluplně pojmenovanými sloty a cíl odkazu ponechte v kódu. Zachovejte názvy proměnných, jejich typy i významové role. Původní katalog může ukládat tvary množného čísla pod klíči s příponami; nové běhové prostředí sestavuje zprávu z jednotlivých tvarů. Místo mechanického přejmenovávání klíčů s příponami ověřte chování v cílovém jazyce.

Zvolte kontext, který vysvětluje, k čemu zpráva slouží. Nový identifikátor se odvozuje ze zdrojového znění a kontextu, nikoli z account.greeting. Veďte migrační tabulku s původním klíčem, jazykem, nově extrahovaným klíčem a případným převodem syntaxe. U pozdravu příslušný řádek zaznamenává převod z {{name}} na {name}. Díky tomuto mapování lze při kontrole dohledat schválené znění v novém katalogu a zjistit, které zprávy ještě nejsou namapované.

Pečlivě extrahujte a importujte malý katalog #

Nainstalujte @lingo.dev/react a nakonfigurujte LingoProvider podle stručného průvodce pro React. Pro současnou implementaci poskytovatele použijte React 19; deklarovaný rozsah podporovaných verzí Reactu 18 v partnerských závislostech nenahrazuje otestování starší aplikace. Po převodu komponenty spusťte nainstalované CLI:

sh
lingo extract --src src --source-locale en

Pokud jste nezměnili výchozí cesty, prohlédněte si locales/en.jsonc a lingo.d.ts. Najděte každou zdrojovou zprávu a její kontext a do migrační tabulky zkopírujte skutečně extrahovaný klíč. Pokud byste ponechali původní klíč nebo si vytvořili vlastní hash, cílový překlad by nebyl propojený s vyhledáváním za běhu.

Každý schválený cílový překlad vložte pod nový klíč, ke kterému je přiřazený. Pečlivě převeďte syntaxi zástupných symbolů, slotů pro bohatý obsah a množných čísel a zachovejte přitom význam. Pomocí workflow pro načítání katalogu načtěte mapu hashů na cílové řetězce. Pokud cílová metadata chybí, použijte aktivní klíče z odpovídajícího zdroje. Nenamapované položky ponechte viditelné jako nedokončenou práci, neoznačujte je za zastaralé.

Do LingoProvider předejte požadovaný jazyk společně s jeho cílovými zprávami. Během postupné migrace ponechte původního i nového poskytovatele kolem kódu, který je používá. Kontrakt poskytovatele vysvětluje slučování pro stejný jazyk a izolaci různých jazyků; při migraci vnořené obrazovky toto chování ověřte.

Ověřte chybějící a chybně formátované zprávy #

Vykreslete testovací sadu se stejnými hodnotami jako před migrací. Porovnejte význam zobrazeného textu, umístění proměnných, chování odkazů, výsledné tvary množného čísla a výběr záložní varianty. Zahrňte nulu, jedničku i vyšší počty, dlouhé hodnoty proměnných a neznámou hodnotu pro výběr varianty.

V lokální testovací sadě odstraňte jednu cílovou položku a ověřte, že se jako záložní varianta použije zdrojový text. Chybějící nebo prázdné zprávy se mohou zobrazit ve zdrojovém jazyce, takže použitelná obrazovka sama o sobě nepotvrzuje úplnost cílových překladů. Spusťte kontroly konzistence extrakce a kontroly TypeScriptu se zahrnutými vygenerovanými deklaracemi. Poté spusťte stávající testy vykreslování aplikace. Typy ověřují kompatibilitu volání, nikoli kvalitu překladu.

U chybně formátované značky bohatého textu nebo zprávy ICU zkontrolujte výstup a diagnostiku. Nové běhové prostředí může zobrazit značky doslova nebo ponechat šablonu nezformátovanou. Než odstraníte původní běhové prostředí, porovnejte toto chování s požadavky aplikace. Tato omezení popisuje část Řešení potíží v Reactu.

Využívejte pomoc agenta, ale jeho práci kontrolujte #

Požádejte agenta, aby prozkoumal stávající knihovnu, zachoval mapování klíčů, rozpoznal nepodporované vzory a oddělil úpravy zdrojového kódu od importu katalogu. Než navržené změny zdrojového kódu a katalogu použijete, zkontrolujte je.

Jakmile testovací sada projde kontrolami vykreslování i nativními kontrolami, rozšiřujte migraci po komponentách nebo jmenných prostorech. Oba katalogy ponechte, dokud nebude mít každé volání a každý schválený cílový překlad ověřené místo v nové implementaci. Původního poskytovatele a závislost odstraňte teprve tehdy, když je už žádný kód nepoužívá. Klienti API a adaptéry směrovače plní samostatné úlohy; změna běhového prostředí zpráv je nenahrazuje.