Extrakce a načítání katalogů zpráv
Extrahujte zdrojové zprávy, stáhněte přeložený soubor JSONC a sestavte mapu pro běh aplikace pomocí odpovídajících zdrojových metadat.
Komponenta obsahuje zdrojovou zprávu a její kontext. Extrakce shromáždí tato volání do souboru, který lze přeložit. Načtení pak propojí přeložené hodnoty s klíči komponenty. V tomto návodu projde první pozdrav celým souborovým workflow, jehož výsledkem bude mapa Messages potřebná pro poskytovatele.
Extrahujte zdroj #
Nainstalujte do aplikace CLI a závislosti pro načítání:
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale enExtrakce probíhá lokálně a nevyžaduje klíč API. Ve výchozím nastavení zapisuje locales/en.jsonc a lingo.d.ts. Explicitně zadané přepínače --out a --types mají přednost před nakonfigurovanými hodnotami i18n.messagesPath a i18n.typesPath a ty zase před výchozími hodnotami. U aplikace Pages s voláními mimo src použijte její skutečný adresář, například --src pages.
Prohlédněte si položku pozdravu. Její hodnotou je úplná anglická šablona; klíč vychází ze zdroje a kontextu. Komentáře před položkou zaznamenávají význam pomocí @context, umístění ve zdroji pomocí @src a pomocí @orphan označují dříve extrahovanou položku, která už není aktivní. Než si vyžádáte překlady, tyto změny zkontrolujte.
Přeložte vybraný katalog #
Pokud aplikace nemá konfiguraci Lingo.dev, inicializujte právě tento soubor se španělštinou jako cílovým jazykem, poté proveďte ověření a připojte lokalizační engine:
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo linkPotřebujete přístup k aktivnímu lokalizačnímu engine a dostatečný zbývající limit spotřeby na účtu. Přihlašovací údaje pro bezobslužná spuštění popisuje Ověřování CLI.
Pokud .lingo/config.json už existuje, zachovejte jeho vazbu i ostatní položky souborů. Přidejte nebo aktualizujte položku pro výběr locales/en.jsonc a ověřte, že zdrojovým jazykem projektu je en. Pokud už máte výchozí stav, dokončete běžné aktualizace stávajících cílových jazyků pomocí npx lingo push --wait, vyřešte všechny požadavky na kontrolu i selhání a prohlédněte si stažené změny. Teprve potom přidejte es do targetLocales. Během následného zpětného doplnění neměňte revizi zdroje. Toto pořadí vysvětluje návod Přidání jazyka. K úpravě konfigurace nepoužívejte init --force; znovu sestavuje položky souborů a může zahodit pokročilé možnosti. Úplnou strukturu popisuje Konfigurace.
U nového projektu nebo po dokončení výše uvedené přípravy stávajícího projektu si vyžádejte chybějící cílové soubory a počkejte na jejich stažení. Dokud příkaz čeká, cílové soubory neměňte, protože stahování může přepsat ruční úpravy:
npx lingo push --backfill-missing --waitPo dokončení běhu zkontrolujte locales/es.jsonc. Než budete výstup považovat za úplný, vyřešte všechny nahlášené stavy vyžadující kontrolu i selhání. Při pozdějších změnách zdroje zopakujte extrakci a použijte npx lingo push --wait; zpětné doplnění slouží pro chybějící soubory, nikoli pro běžné aktualizace existujícího cíle.
Uchovávejte zdrojová metadata společně s cílovou revizí #
Obecné workflow překladu JSONC zachovává v cílovém souboru zdrojové značky @orphan, ale odstraňuje komentáře @context a @src. Ze samotného cílového souboru načítací funkce nezjistí, ke které stránce zpráva patřila.
Uchovejte extrahovaný zdrojový soubor ze stejné revize jako cílový soubor. Vyberte z něj aktivní položky a propojte jejich klíče s přeloženými hodnotami v cílovém souboru. Tím vyloučíte odstraněné zprávy a zachováte možnost vybírat podle zdrojové trasy. Chybějící cílové klíče zůstanou vynechané, takže aplikace za běhu může použít zdrojové znění jako náhradní hodnotu.
Zpracujte nezpracovaný katalog #
Vytvořte src/catalog.ts s následující načítací funkcí, která bude součástí aplikace:
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";
function readStringCatalog(raw: string) {
const errors: ParseError[] = [];
const value: unknown = parse(raw, errors, { allowTrailingComma: true });
if (
errors.length > 0 ||
value === null ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.values(value).some((entry) => typeof entry !== "string")
) {
throw new Error("Expected a flat JSONC object with string values");
}
return readLocaleFile(raw);
}
export function loadMatchedMessages(
sourceJsonc: string,
targetJsonc: string,
include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
return Object.fromEntries(
active.filter(include).flatMap((entry) => {
const value = target.get(entry.key);
return value === undefined ? [] : [[entry.key, value]];
}),
);
}readLocaleFile zpracovává syntaxi JSONC a metadata, ale neověřuje strukturu dat za běhu. Navzdory deklarovanému typu položek přijímá pole i neřetězcové hodnoty. Pokud je kořenem primitivní hodnota nebo null, nevrací žádné položky. První z výše uvedených funkcí tyto struktury odmítne dříve, než se hodnoty dostanou do vykreslovací vrstvy. Obě funkce jsou lokální a neprovádějí žádné vstupně-výstupní operace.
V aplikaci Vite načtěte soubory jako prostý text v modulu, který dodává data poskytovateli:
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);Příklad předpokládá, že modul je přímo v src a že jsou zahrnuty klientské typy Vite. Předejte spanishMessages jako messages s locale="es". Pozdrav by teď měl používat staženou španělskou šablonu a nadále nahrazovat {name} hodnotou Ana. Zkontrolujte výsledné znění a otestujte chybějící položky; načtení souboru a posouzení jeho jazykové kvality jsou dvě různé věci.
Vyberte jen zdrojové položky, které trasa potřebuje #
Nepovinný predikát include se vyhodnocuje nad aktivními zdrojovými položkami ještě před propojením. Načítací funkce stránky může pomocí entry.metadata.src zahrnout vlastní volání i sdílené komponenty. Výběr provádějte ve zdroji, kde jsou metadata stále k dispozici. Při nasazení uchovávejte zdroj i cíl společně, aby výběr podle trasy nepoužíval klíče z jiné revize.
Návod pro Next Pages obsahuje úplný predikát pro trasu. Návod pro TanStack používá tuto načítací funkci pro katalog daného požadavku. Jejich vestavěné načítací funkce umějí filtrovat soubory s metadaty, ale ani jedna automaticky nepropojuje cílové soubory bez komentářů se zdrojovými metadaty.
Reference pomocných funkcí Spec #
| Export | Kontrakt |
|---|---|
readLocaleFile(content): LocaleFile | Zpracuje JSONC včetně koncových čárek a předcházejících blokových komentářů s metadaty; při syntaktické chybě vyvolá výjimku. |
getActiveEntries(entries): LocaleEntry[] | Zachová položky, u nichž se metadata.orphan nevyhodnotí jako pravda. |
LocaleFile | { entries: LocaleEntry[] }. |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }. |
EntryMetadata | Nepovinné context, src a orphan. |
computeKey(source, context?) | Sdílená normalizovaná identita zdroje a kontextu, kterou exportuje i React. |
buildIcuPlural(forms) | Vygeneruje známé kategorie základních číslovek v kanonickém pořadí. |
buildIcuSelect(forms) | Vygeneruje alternativy se seřazenými klíči. |
Pomocné funkce pro sestavování ICU přijímají záznamy s řetězcovými hodnotami; typy plural a select v Reactu přidávají povinnou formu other. Výsledný katalog pro běh aplikace je prostá mapa Messages, nikoli LocaleFile.
Existující prostředky s klíči, dokumenty a statické jazykové moduly v TypeScriptu používají místo tohoto postupu extrakce vlastní obslužné funkce formátů. Ukázkové projekty představují tato uspořádání spolu s aplikacemi v Reactu.