Provider a hooky

Předejte jazyk a katalog, propojte sdílené zprávy se zprávami stránky a přepínejte jazyky bez nechtěného kombinování vstupů pro vykreslování.

LingoProvider zpřístupňuje podstromu komponent jeden jazyk a katalog. useLingo() načte nejbližší provider a vrátí metody pro práci se zprávami a formátováním pro tyto vstupy.

Tyto příklady vykreslování vyžadují React 19. Než začnete provider používat, proveďte instalaci podle průvodce rychlým startem pro React.

tsx
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";

function SaveButton() {
  const l = useLingo();
  return (
    <button type="submit">
      {l.text("Save", { context: "Submit changes to account settings" })}
    </button>
  );
}

export function Settings({ messages }: { messages: Messages }) {
  return (
    <LingoProvider locale="fr" messages={messages}>
      <SaveButton />
    </LingoProvider>
  );
}

Před vykreslením Settings načtěte francouzské zprávy. Provider přijímá Messages, tedy Record<string, string>, nikoli cestu k souboru, promise ani seznam položek z parsovaného JSONC. Tuto mapu získáte postupem popsaným v části Načítání katalogu.

Vstupy provideru #

VlastnostSpecifikace
localePovinný řetězec pro diagnostiku vyhledávání zpráv, gramatiku a formátování.
messagesNepovinná mapa řetězců s hashi jako klíči; výchozí hodnota je {}.
childrenPovinný podstrom ReactNode.

I s prázdným katalogem má podstrom k dispozici formátování podle jazyka; při volání zpráv se použijí jejich zdrojové šablony. Samotný provider nenastavuje jazyk dokumentu ani směr textu.

Volejte useLingo v komponentě pod providerem. Volání mimo provider vyvolá výjimku. Pokud komponenta vrací provider, její vlastní hook se tím pod něj nezařadí. Oddělte proto obal s providerem od komponenty, která hook používá.

Kombinujte sdílené zprávy se zprávami stránky #

Vnořené providery se stejným řetězcem jazyka slučují své mapy. Položky potomka přepisují položky rodiče se shodnými klíči, ostatní položky rodiče zůstávají dostupné. Trasa tak může přidat zprávy stránky, aniž by musela opakovat sdílené zprávy navigace.

tsx
<LingoProvider locale="fr" messages={sharedMessages}>
  <LingoProvider locale="fr" messages={pageMessages}>
    <SettingsPage />
  </LingoProvider>
</LingoProvider>

Zde jsou sharedMessages a pageMessages již načtené francouzské mapy. Pokud se jazyk vnitřního provideru změní na es, provider se stane nezávislým: u chybějících španělských zpráv se místo francouzského textu použije zdrojový text. Porovnává se přesné znění řetězce jazyka, proto v celé aplikaci dodržujte jednotný zápis.

Přepínejte jazyk a katalog společně #

Vstup pro vykreslování ukládejte jako dvojici, například { locale: "fr", messages: frenchMessages }. Načtěte novou mapu a pak celou dvojici nahraďte jedinou aktualizací stavu. Pokud změníte pouze jazyk, může na obrazovce zůstat francouzský text se španělským formátováním čísel.

Během načítání nového katalogu ponechte zobrazený obsah pro předchozí dvojici nebo zobrazte stav načítání podle toho, jak jsou navržené interakce v aplikaci. V aplikacích se směrováním použijte odpovídající postup pro Next Pages nebo TanStack; jejich přepínače načítají nové vstupy odlišně.

Vytvořte objekt Lingo bez hooku #

Pokud funkce potřebuje řetězec mimo komponentu Reactu, použijte createLingo(locale: string, messages?: Messages): Lingo:

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });

Toto volání vrátí Account settings a poměr v daném jazyce naformátuje jako 12.5%. Neodesílá požadavek na překlad ani se nepřihlašuje k odběru změn z provideru. Při změně jazyka nebo zpráv vytvořte nový objekt.

createLingo i useLingo zpřístupňují locale, direction, script a region. K nastavení atributů dokumentu použijte metadata jazyka a během hydratace zachovejte stejné vstupy.