LingoProvider

LingoProvider je React context, který drží aktivní jazyk a mapu zpráv. Obalte ho jednou kolem kořene aplikace — a vše uvnitř pak může volat useLingo() pro překlad řetězců nebo čtení metadat jazyka.

Základní použití#

import { LingoProvider } from "@lingo.dev/react";
import messages from "./locales/es.json";

<LingoProvider locale="es" messages={messages}>
  <App />
</LingoProvider>

Props#

Messages je jen Record<string, string> — stejný tvar, který CLI zapisuje do locales/<locale>.json.

Vnořené providery#

Providery můžete vnořovat. Pravidla se liší podle toho, jestli má vnořený provider stejný jazyk jako rodič, nebo jiný.

Stejný jazyk — zprávy se sloučí#

<LingoProvider locale="es" messages={sharedMessages}>
  {/* Route-scoped messages override shared on collision; missing keys fall through to shared. */}
  <LingoProvider locale="es" messages={dashboardMessages}>
    <Dashboard />
  </LingoProvider>
</LingoProvider>

Tohle se hodí, když chcete rozdělit bundly podle route a zároveň mít u kořene společnou „shell“ sadu překladů.

Různé jazyky — samostatně#

<LingoProvider locale="es" messages={esMessages}>
  <Header />
  <LingoProvider locale="ar-SA" messages={arMessages}>
    {/* This subtree is entirely Arabic; the parent's es messages are NOT visible. */}
    <ArabicEmbed />
  </LingoProvider>
</LingoProvider>

Praktické, když potřebujete vykreslit jednu komponentu v pevném jazyce (citaci, embed, panel náhledu) uvnitř jinak odlišné aplikace.

Přepínání jazyka za běhu#

Berte locale jako React state — změňte ho a každý konzument useLingo() níže se znovu vykreslí s novým jazykem a sadou zpráv.

function AppRoot() {
  const [locale, setLocale] = useState("en");
  const [messages, setMessages] = useState({});

  async function switchTo(next: string) {
    const next_messages = await import(`./locales/${next}.json`);
    setLocale(next);
    setMessages(next_messages.default);
  }

  return (
    <LingoProvider locale={locale} messages={messages}>
      <LocaleSwitcher current={locale} onSelect={switchTo} />
      <App />
    </LingoProvider>
  );
}

Co můžete z contextu číst#

useLingo() vrací aktivní objekt Lingo. Kromě text() a rich() obsahuje také:

• locale — BCP-47 řetězec, který jste předali
• direction — "ltr" nebo "rtl", vypočtené pomocí Intl.Locale.textInfo se záložním seznamem známých RTL jazyků
• script — např. "Latn", "Cyrl", "Arab"
• region — např. "US", "DE", "SA"

To se hodí pro podmíněné rozvržení (třeba zrcadlení ikon v RTL) nebo tagování v analytice — bez nutnosti cokoli dál parsovat.

Časté chyby#

• Zapomenutý <LingoProvider>. useLingo() mimo něj vyhodí chybu. Chybová zpráva vám napoví, že máte přidat provider; pokud to vidíte v testech, obalte render providerem v testovacím režimu s prázdným messages, aby byla assertions stabilní.
• Přímé předávání asynchronně načtených zpráv. messages musí být synchronní hodnota. Promise vyřešte v rodiči (pomocí Suspense nebo stavu) a pak předejte výsledek dál.
• Přepnutí locale bez aktualizace messages. Provider předpokládá, že obě props patří k sobě — změňte je v rámci stejné aktualizace useState, jinak se na chvíli vykreslí nový jazyk se starými překlady.