Quickstart

npm install @lingo.dev/react

If you're on Next.js, also install @lingo.dev/react-next — it adds router-aware helpers on top of the same runtime.

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

export function App() {
  return (
    <LingoProvider locale="es" messages={esMessages}>
      <Page />
    </LingoProvider>
  );
}

messages is an object keyed by content hash — exactly what the CLI emits to locales/<locale>.json. On first run it's empty, and that's fine: untranslated strings fall back to their source text.

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

function Page() {
  const l = useLingo();
  return <h1>{l.text("Hello", { context: "Hero heading" })}</h1>;
}

l.text(source, { context }) is the canonical call. context is required — it lets translators disambiguate strings that read the same in English but differ across languages ("Save" the verb vs. "Save" the noun).

lingo extract

This scans your source, computes a stable hash for "Hello" + the context, and writes it to your source locale file (locales/en.jsonc by default). Re-run after any change — extraction is idempotent.

lingo push --backfill-missing

The CLI uploads the source file, asks the engine to translate into your configured target locales, and downloads the result back into locales/<locale>.json. From now on, every push only sends what changed.

Import the JSON file for the locale your app is rendering in (or pick it dynamically based on the user) and pass it to LingoProvider. The hook call from step 3 stays the same — l.text("Hello", ...) now returns the translated value because the hash matches what was downloaded.