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í:

sh
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 en

Extrakce 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:

sh
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link

Potř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:

sh
npx lingo push --backfill-missing --wait

Po 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:

ts
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:

ts
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 #

ExportKontrakt
readLocaleFile(content): LocaleFileZpracuje 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 }.
EntryMetadataNepovinné 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.