react-autolocale 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Williams Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# react-autolocale
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Wrap your React + Vite app in one component. `vite build` produces a fully translated static page for every language (`/en/`, `/fr/`, `/es/`, ...) using a free local translation model. No `t()`, no keys, no translation files in your repo, and your source code stays untouched.
+
+## Quick start
+
+**1. Install** (npm, yarn or pnpm)
+
+```bash
+npm install react-autolocale     # or: yarn add react-autolocale   |   pnpm add react-autolocale
+```
+
+**2. Add the plugin to your Vite config**
+
+```bash
+npx react-autolocale init        # or: yarn react-autolocale init   |   pnpm exec react-autolocale init
+```
+
+**3. Wrap your app once**
+
+```tsx
+// main.tsx
+import { AutoScale } from "react-autolocale";
+
+createRoot(document.getElementById("root")!).render(
+  <AutoScale original="en" languages={["fr", "es", "de", "pt"]} exclude={["Acme Cloud"]}>
+    <App />
+  </AutoScale>,
+);
+```
+
+**4. Build**
+
+```bash
+npm run build                    # or: yarn build   |   pnpm build
+npm run preview                  # optional: check the built site locally
+```
+
+The output folder has one page per language and route (`dist/fr/`, `dist/fr/about/`, ...), deployable anywhere that serves static files. The first build takes a few minutes: it installs the free local translation engine (about 440 MB, once, into `~/.cache/react-autolocale/engine`, shared by all your projects) and downloads the models. Later builds reuse the cache. Prefer to manage the engine yourself? `npm install -D @huggingface/transformers` and it will be used instead.
+
+Optional: `npx react-autolocale add switcher` copies an editable language switcher into your project (see below).
+
+Write normal JSX; there is no `t()` to call and no translation file to maintain.
+
+## Multi-page apps (React Router)
+
+Every page is generated, with nothing to configure. The build finds pages two ways: by following the links in each page, and by reading the fixed routes in your router code (`<Route path="/thank-you">`, nested routes, and `createBrowserRouter` objects). Pages written as `/fr/about/index.html` etc. are created for each language.
+
+Dynamic routes (`/users/:id`) can't be known from code, so list the real pages you want with the `routes` option, which can also be a function that fetches them:
+
+```ts
+reactAutolocale({ routes: async () => (await getUsers()).map((u) => `/users/${u.id}`) })
+```
+
+Give your router the language as its basename, and remount it when the language changes:
+
+```tsx
+function Shell() {
+  const { basePath, language } = useLanguage();
+  return (
+    <BrowserRouter basename={basePath} key={language}>
+      <Routes>...</Routes>
+    </BrowserRouter>
+  );
+}
+
+<AutoScale original="en" languages={["fr", "es"]}><Shell /></AutoScale>
+```
+
+Your host must serve `/fr/about/index.html` for `/fr/about`, which static hosts do by default.
+
+## Fixing a translation
+
+The quickest way is the overrides file. Run `npx react-autolocale export` after a build: it writes every generated translation into `react-autolocale.overrides.json` in your project root. Edit any value, commit the file and rebuild. Entries in it always win over machine translation and survive rebuilds (edits made inside `dist/` or the cache do not).
+
+You can also fix a few strings in code:
+
+Machine translation sometimes gets short UI words wrong (a nav link "Home" may come back as "Sommaire"). Correct any string in the plugin options; overrides always win:
+
+```ts
+reactAutolocale({ overrides: { fr: { Home: "Accueil" }, es: { Home: "Inicio" } } })
+```
+
+## Different values per language (prices, links, and more)
+
+Some things should differ by language, not just be translated: a price, a link to a localized page, a phone number.
+
+```tsx
+import { useLocalized, Localized, ForLanguages, useFormat } from "react-autolocale";
+
+// A value: falls back to `default`, then to the original language
+const href = useLocalized({ en: "/pricing", fr: "/tarifs", es: "/precios", default: "/pricing" });
+<a href={href}>Pricing</a>                        // "Pricing" itself is still translated for you
+
+// A block of UI
+<Localized en={<UsPhone />} fr={<FrPhone />} default={<UsPhone />} />
+
+// Content for some languages only (local offers, legal notices)
+<ForLanguages only={["fr", "es"]}>Free shipping in Europe</ForLanguages>
+<ForLanguages except={["ja"]}><CookieNotice /></ForLanguages>
+
+// Numbers, prices and dates in the visitor's format
+const format = useFormat();
+format.currency(1234.5, "EUR");   // "€1,234.50" in English, "1 234,50 €" in French
+format.number(1250000);           // "1,250,000" / "1 250 000"
+format.percent(0.15);             // "15%" / "15 %"
+format.date(new Date());          // "Oct 9, 2026" / "9 oct. 2026"
+```
+
+All of these are part of the prerendered pages, so `/fr/` and `/en/` ship with their own values in the HTML. Values you pick in code are your own data and are never machine-translated. `basePath` from `useLanguage()` is the current prefix (`/fr`) for building internal links. With React Router, the page you link to must be a route you define (here `/tarifs`); the build does not rename routes by language.
+
+## Better translations: glossary and choosing the engine
+
+The built-in model is free and runs on your machine, but it translates each string without knowing where it appears. You can improve it:
+
+```ts
+import reactAutolocale, { ollama } from "react-autolocale/vite";
+
+reactAutolocale({
+  // Terms that must always translate a given way (applied before the model sees the text)
+  glossary: { fr: { Roadmap: "Feuille de route" }, es: { Roadmap: "Hoja de ruta" } },
+
+  // Swap the engine. Free and local, through Ollama (https://ollama.com):
+  engine: ollama({ model: "llama3.1" }),
+
+  // ...or your own function: DeepL, an LLM API, anything. It is told where each string appears.
+  // engine: async ({ texts, contexts, from, to }) => texts.map((t, i) => myTranslate(t, from, to, contexts[i])),
+});
+```
+
+`contexts[i]` is the element or attribute the string sits in (`"button"`, `"a"`, `"h1"`, `"placeholder"`, ...), which is what lets a language model translate a lone "Home" in a nav bar correctly. The built-in model ignores it. Translations are cached, so you only pay for (or wait for) new and changed text.
+
+## Language switcher
+
+Switching is just navigation to `/fr/` (instant, no reload; a page load when `seo` is on). You choose the UI:
+
+```bash
+npx react-autolocale add switcher   # copies an editable LanguageSwitcher into src/components
+```
+
+or import the ready-made dropdown: `import { LanguageSwitcher } from "react-autolocale"`.
+
+Build your own with the hook:
+
+```tsx
+const { language, languages, setLanguage, basePath } = useLanguage();
+```
+
+## What gets translated
+
+- Static JSX text, plus `placeholder`, `title`, `alt` and `aria-label` on HTML elements.
+- **Text with variables**: `<p>Welcome, {user.name}. You have {count} new messages</p>` is translated as one sentence (`Welcome, {name}. You have {count} new messages`) and your values are filled in at runtime. Variables must be plain names or property paths (`name`, `user.name`, `props.count`). Text mixed with function calls, conditions or nested elements is left as written. There is no plural handling, so write `{count} message(s)` or branch in your code.
+- **Not translated**: anything with `translate="no"` (the standard HTML attribute, inherited by children), `exclude` phrases, `<code>` / `<pre>` / `<script>` / `<style>`, text made only of numbers and symbols, and data that arrives at runtime (API responses, user content).
+- **Numbers** are kept exactly as written. The build checks that every digit (prices, phone numbers, hours, versions) survives translation and re-translates with the number locked if not. If that still fails, the original text is kept instead of shipping a wrong number. Use `useFormat()` (below) for numbers you compute.
+
+```tsx
+<p translate="no">Acme Cloud</p>                       // never translated
+<section translate="no"><Terminal /></section>          // nothing inside is translated
+```
+
+## Supported languages
+
+Use these codes in `languages={[...]}`. The source (`original`) language can be any of them.
+
+| Code | Language | Model |
+| --- | --- | --- |
+| `fr` | French | OPUS-MT |
+| `es` | Spanish | OPUS-MT |
+| `de` | German | OPUS-MT |
+| `it` | Italian | OPUS-MT |
+| `nl` | Dutch | OPUS-MT |
+| `ru` | Russian | OPUS-MT |
+| `zh` | Chinese (Simplified) | OPUS-MT |
+| `ar` | Arabic (RTL) | OPUS-MT |
+| `hi` | Hindi | OPUS-MT |
+| `sv` | Swedish | OPUS-MT |
+| `da` | Danish | OPUS-MT |
+| `fi` | Finnish | OPUS-MT |
+| `cs` | Czech | OPUS-MT |
+| `hu` | Hungarian | OPUS-MT |
+| `ro` | Romanian | OPUS-MT |
+| `uk` | Ukrainian | OPUS-MT |
+| `vi` | Vietnamese | OPUS-MT |
+| `id` | Indonesian | OPUS-MT |
+| `pt` | Portuguese | NLLB |
+| `ja` | Japanese | NLLB |
+| `ko` | Korean | NLLB |
+| `tr` | Turkish | NLLB |
+| `pl` | Polish | NLLB |
+| `no` | Norwegian | NLLB |
+| `el` | Greek | NLLB |
+| `he` | Hebrew (RTL) | NLLB |
+| `th` | Thai | NLLB |
+| `bn` | Bengali | NLLB |
+| `fa` | Persian (RTL) | NLLB |
+| `ur` | Urdu (RTL) | NLLB |
+| `bg` | Bulgarian | NLLB |
+| `hr` | Croatian | NLLB |
+| `sk` | Slovak | NLLB |
+| `ca` | Catalan | NLLB |
+| `ms` | Malay | NLLB |
+| `sw` | Swahili | NLLB |
+| `tl` | Tagalog | NLLB |
+| `en` | English (default source) | NLLB when used as a target |
+
+OPUS-MT models are small (about 75 MB each) and are used when the source language is English. NLLB-200 is one larger download (about 600 MB) shared by all the languages marked NLLB, and is also used for any non-English source. Right-to-left languages automatically get `dir="rtl"` on the page.
+
+### Quality by language
+
+Every supported language was run through the real models on sample UI sentences: all 37 produce output in the right writing system, with no runaway or repeated text. How good that output is varies. French, Spanish, German, Italian, Dutch, Swedish, Danish, Japanese and Korean read naturally on ordinary sentences. Short imperative labels are the weak spot in many languages: "Save 20%" comes back as "save a file" in Russian, Ukrainian, Hungarian, Hindi and Romanian, "Sign in" comes back wrong in Russian, Chinese, Arabic and Vietnamese, and Arabic and Vietnamese could not keep the number in "Save 20% on your first order" (the original English is kept for such strings rather than risking a wrong number). Treat these as drafts: review the languages you ship in `react-autolocale.overrides.json`, add a `glossary` for key terms, or use an `engine` that gets context (see below). You can re-run the check yourself with `RUN_MODELS=1 pnpm exec vitest run test/models.test.ts`.
+
+## Translations and caching
+
+Translations are generated on first build into `node_modules/.cache/react-autolocale/` and reused; only new or changed strings are translated afterwards. Cache that folder in CI. Models download once into `~/.cache/react-autolocale` (about 75 MB per OPUS-MT language, about 600 MB for NLLB: Japanese, Korean, Portuguese and others). The dev server translates text you add while it runs and reloads.
+
+## Automatic language navigation
+
+Whether a visitor is moved depends on the URL they land on:
+
+| Where they land | What happens |
+| --- | --- |
+| `/` or `/about` (no language in the URL) | Sent to their saved language, otherwise their browser language, if you support it (a French browser lands on `/fr/about`). |
+| `/en/about` or `/fr/about` (explicit language URL) | Never redirected. The page they asked for is the page they get. |
+
+- A language chosen in the switcher is remembered and wins on later visits. The browser language itself is not saved; it is checked each time.
+- The browser's language setting is used, not the visitor's physical location. Unsupported browser languages stay on the original.
+- The root page redirects before it paints, so visitors don't see a flash of the wrong language.
+
+This follows common practice. Redirecting the bare root by browser language is widespread, while forcing visitors off an explicit language URL is avoided: shared links and search results should open the page they point to, redirect loops are avoided, and it respects someone who chose a language on purpose. Search engines are told which URL belongs to which language through `hreflang` tags (see SEO below), so a French searcher is normally shown the `/fr/` URL in the first place. Visitors who land on another language's URL can use the language switcher.
+
+## Suggesting the visitor's language (optional banner)
+
+Instead of forcing a redirect on an explicit URL, you can offer the visitor their browser language: a French visitor on `/en/about` sees "Cette page est également disponible en Français." with a button to switch and one to dismiss. It appears only when the browser language is supported and differs from the page, is shown after the page loads (so it never changes the HTML search engines see), remembers a dismissal, and stays hidden once the visitor has picked a language. The text is shown in the visitor's own language.
+
+It is off unless you add it, and you decide how it looks:
+
+```tsx
+import { LanguageBanner } from "react-autolocale";
+
+<LanguageBanner />                                   // ready-made bar, style it with className / style
+<LanguageBanner className="my-bar" />                // your own CSS replaces the default look
+
+<LanguageBanner>                                     // or build the markup yourself
+  {(s) => (
+    <aside>
+      {s.text} <button onClick={s.accept}>{s.switchLabel}</button>
+      <button onClick={s.dismiss}>{s.dismissLabel}</button>
+    </aside>
+  )}
+</LanguageBanner>
+```
+
+Prefer to own the component? `npx react-autolocale add banner` copies an editable `LanguageBanner` into your project. For full control use the hook, `useLanguageSuggestion()`, which returns `null` or `{ language, native, text, switchLabel, dismissLabel, accept, dismiss }`.
+
+## SEO (opt-in)
+
+By default react-autolocale does not touch your SEO: the only changes to `<head>` are one inline script holding that page's translations, plus `lang` and `dir` on `<html>`.
+
+Turn it on with `seo` on the provider:
+
+```tsx
+<AutoScale original="en" languages={["fr", "es"]} seo siteUrl="https://example.com">
+  <App />
+</AutoScale>
+```
+
+With `seo` the build also:
+- translates `<title>` and the description / Open Graph / Twitter meta tags,
+- adds `<link rel="canonical">` and `hreflang` alternates (plus `x-default`) to every page,
+- writes `sitemap.xml` with the alternates (needs `siteUrl`; reference it from your `robots.txt`).
+
+With `seo`, switching language navigates to the real page (so its head tags are correct) instead of swapping in place. Brand names in the title are translated like any text, so add them to `exclude`.
+
+## Limits
+
+- Data that arrives at runtime (API responses, user-written content) is not translated: it does not exist at build time. Text you write in JSX around those values is.
+- Variables in text must be plain names or property paths; no plural rules.
+- Dynamic routes (`/users/:id`) only get pages you list in `routes`, or that are linked.
+- `<AutoScale>` props must be literals so the plugin can read them at build time.
+- Use Vite's default `base: "/"`.
+- Machine translation is draft quality. Short labels, long sentences with variables and less common languages need a human look: use the overrides file.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { n as exportTranslations, t as OVERRIDES_FILE } from "./overrides-ZQ6meLck.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/cli/viteConfig.ts
+const IMPORT_LINE = `import reactAutolocale from "react-autolocale/vite";`;
+/** Adds the react-autolocale plugin to a vite.config source string. Returns null if it can't be done safely. */
+function patchViteConfig(source) {
+	if (source.includes("react-autolocale/vite")) return {
+		code: source,
+		changed: false
+	};
+	let code = source;
+	if (/plugins\s*:\s*\[/.test(code)) code = code.replace(/plugins\s*:\s*\[/, "plugins: [reactAutolocale(), ");
+	else if (/defineConfig\(\s*\{/.test(code)) code = code.replace(/defineConfig\(\s*\{/, "defineConfig({\n  plugins: [reactAutolocale()],");
+	else if (/export\s+default\s*\{/.test(code)) code = code.replace(/export\s+default\s*\{/, "export default {\n  plugins: [reactAutolocale()],");
+	else return null;
+	const imports = [...code.matchAll(/^import[^\n]*$/gm)];
+	const last = imports[imports.length - 1];
+	if (last) {
+		const at = last.index + last[0].length;
+		code = code.slice(0, at) + "\n" + IMPORT_LINE + code.slice(at);
+	} else code = IMPORT_LINE + "\n" + code;
+	return {
+		code,
+		changed: true
+	};
+}
+//#endregion
+//#region src/cli/index.ts
+const HELP = `react-autolocale
+
+Usage:
+  react-autolocale export
+      Writes the generated translations to ${OVERRIDES_FILE} so you can edit them.
+      Anything in that file always wins over machine translation. Run a build first.
+  react-autolocale init
+      Adds the plugin to your vite.config for you.
+  react-autolocale add switcher [--dir src/components]
+      Copies an editable <LanguageSwitcher /> into your project.
+  react-autolocale add banner [--dir src/components]
+      Copies an editable <LanguageBanner /> (suggests the visitor's browser language) into your project.
+`;
+const TSX = `import { useLanguage } from "react-autolocale";
+
+// This file is yours: change the markup, style it, or replace it entirely.
+export function LanguageSwitcher() {
+  const { language, languages, setLanguage } = useLanguage();
+  return (
+    <div role="group" aria-label="Language">
+      {languages.map((l) => (
+        <button
+          key={l.code}
+          lang={l.code}
+          aria-pressed={l.code === language}
+          onClick={() => setLanguage(l.code)}
+        >
+          {l.native}
+        </button>
+      ))}
+    </div>
+  );
+}
+`;
+const JSX = TSX;
+const BANNER_TSX = `import { useLanguageSuggestion } from "react-autolocale";
+
+// This file is yours: change the markup, style it, or replace it entirely.
+// It renders nothing unless the visitor's browser language differs from this page's language.
+export function LanguageBanner() {
+  const suggestion = useLanguageSuggestion();
+  if (!suggestion) return null;
+  return (
+    <div role="region" aria-label={suggestion.native}>
+      <span>{suggestion.text}</span>
+      <button onClick={suggestion.accept}>{suggestion.switchLabel}</button>
+      <button onClick={suggestion.dismiss}>{suggestion.dismissLabel}</button>
+    </div>
+  );
+}
+`;
+function flag(args, name) {
+	const i = args.indexOf(name);
+	return i >= 0 ? args[i + 1] : void 0;
+}
+const VITE_CONFIGS = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs"
+];
+const NEXT_STEP = `
+Next, wrap your app once (for example in main.tsx):
+
+  import { AutoScale } from "react-autolocale";
+
+  <AutoScale original="en" languages={["fr", "es"]}>
+    <App />
+  </AutoScale>
+
+Then run your build.`;
+function init(root) {
+	const file = VITE_CONFIGS.map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
+	if (!file) throw new Error("No vite.config found. This package works with Vite projects.");
+	const name = path.basename(file);
+	const patched = patchViteConfig(fs.readFileSync(file, "utf8"));
+	if (!patched) throw new Error(`Could not edit ${name} automatically. Add this yourself:\n  import reactAutolocale from "react-autolocale/vite";\n  plugins: [reactAutolocale(), ...]`);
+	if (patched.changed) fs.writeFileSync(file, patched.code);
+	console.log(patched.changed ? `Added the react-autolocale plugin to ${name}.` : `${name} already uses react-autolocale.`);
+	console.log(NEXT_STEP);
+}
+function addComponent(root, args, name) {
+	const dir = path.resolve(root, flag(args, "--dir") ?? (fs.existsSync(path.join(root, "src")) ? "src/components" : "components"));
+	const ts = fs.existsSync(path.join(root, "tsconfig.json"));
+	const file = path.join(dir, ts ? `${name}.tsx` : `${name}.jsx`);
+	if (fs.existsSync(file)) throw new Error(`${path.relative(root, file)} already exists.`);
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(file, name === "LanguageBanner" ? BANNER_TSX : ts ? TSX : JSX);
+	console.log(`Created ${path.relative(root, file)}\nImport it anywhere: import { ${name} } from "./components/${name}";`);
+}
+try {
+	const [cmd, what, ...rest] = process.argv.slice(2);
+	if (cmd === "init") init(process.cwd());
+	else if (cmd === "export") {
+		const { file, languages } = exportTranslations(process.cwd());
+		console.log(`Wrote ${path.relative(process.cwd(), file)}: ${Object.entries(languages).map(([l, n]) => `${l} ${n}`).join(", ")} strings.`);
+		console.log("Edit any value, commit the file, and rebuild. Your edits always win over machine translation.");
+	} else if (cmd === "add" && what === "switcher") addComponent(process.cwd(), rest, "LanguageSwitcher");
+	else if (cmd === "add" && what === "banner") addComponent(process.cwd(), rest, "LanguageBanner");
+	else {
+		console.log(HELP);
+		if (cmd) process.exitCode = 1;
+	}
+} catch (err) {
+	console.error(`react-autolocale: ${err.message}`);
+	process.exit(1);
+}
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { CSSProperties, ReactElement, ReactNode } from "react";
+//#region src/runtime/index.d.ts
+type Dict = Record<string, string>;
+declare global {
+  interface Window {
+    /** Written into every generated page so the first render already has its translations. */
+    __AUTOSCALE__?: {
+      lang: string;
+      dict: Dict;
+    };
+  }
+}
+export interface AutoScaleProps {
+  /** Language the app is written in, e.g. "en". Must be a literal so the build can read it. */
+  original: string;
+  /** Languages to generate, e.g. ["fr", "es"]. Must be a literal. */
+  languages: string[];
+  /** Phrases that must never be translated, such as brand names. Must be a literal. */
+  exclude?: string[];
+  /**
+   * Opt in to SEO changes at build time: translated title/meta tags, canonical and hreflang links,
+   * and a sitemap. Off by default: nothing in <head> is touched. Must be a literal.
+   */
+  seo?: boolean | "true";
+  /** Public site URL (e.g. "https://example.com"); used by `seo` for absolute links and the sitemap. */
+  siteUrl?: string;
+  children?: ReactNode;
+}
+/**
+ * Wrap your app once. Language comes from the URL (/fr/...), so every language is a real, static page.
+ * The props are read at build time by the Vite plugin.
+ */
+export declare function AutoScale({ children }: AutoScaleProps): ReactElement;
+/** @internal Inserted by the Vite plugin in place of static JSX text. */
+export declare function __T({ s }: {
+  s: string;
+}): ReactElement;
+/** @internal Inserted by the Vite plugin for translated attributes (placeholder, alt, ...). */
+export declare function __useT(): (s: string) => string;
+/** @internal Inserted by the Vite plugin for text with variables, e.g. `Hello {name}`. */
+export declare function __TD({ s, v }: {
+  s: string;
+  v: Record<string, unknown>;
+}): ReactElement;
+/**
+ * Pick a value by language: `useLocalized({ en: "/pricing", fr: "/tarifs", default: "/pricing" })`.
+ * Falls back to `default`, then to the original language's value.
+ */
+export declare function useLocalized<T>(values: Record<string, T | undefined> & {
+  default?: T;
+}): T;
+/** Component form of `useLocalized`: `<Localized en={<A />} fr={<B />} default={<A />} />`. */
+export declare function Localized(props: Record<string, ReactNode>): ReactElement;
+export interface ForLanguagesProps {
+  /** Show only for these languages. */
+  only?: string[];
+  /** Show for every language except these. */
+  except?: string[];
+  children?: ReactNode;
+}
+/** Content that appears for some languages only, such as a local offer or legal notice. */
+export declare function ForLanguages({ only, except, children }: ForLanguagesProps): ReactElement | null;
+export interface Format {
+  language: string;
+  number: (value: number, options?: Intl.NumberFormatOptions) => string;
+  currency: (value: number, currency: string, options?: Intl.NumberFormatOptions) => string;
+  percent: (value: number, options?: Intl.NumberFormatOptions) => string;
+  date: (value: Date | number | string, options?: Intl.DateTimeFormatOptions) => string;
+}
+/** Numbers, prices and dates formatted for the current language: `format.currency(19.99, "EUR")`. */
+export declare function useFormat(): Format;
+export interface LanguageSuggestion {
+  /** Code of the suggested language, e.g. "fr". */
+  language: string;
+  /** The suggested language's own name, e.g. "Français". */
+  native: string;
+  /** Full sentence in the visitor's language, e.g. "This page is also available in Français. Switch?" */
+  text: string;
+  switchLabel: string;
+  dismissLabel: string;
+  /** Go to this page in the suggested language. */
+  accept: () => void;
+  /** Hide the suggestion and don't offer this language again. */
+  dismiss: () => void;
+}
+/**
+ * For building your own banner. Returns null when there is nothing to suggest: the visitor's browser language
+ * is the page's language, is not supported, was dismissed, or they already picked a language.
+ */
+export declare function useLanguageSuggestion(): LanguageSuggestion | null;
+export interface LanguageBannerProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Replace the markup entirely: `{(s) => <MyBar>{s.text}</MyBar>}`. */
+  children?: (suggestion: LanguageSuggestion) => ReactNode;
+}
+/** A ready-made suggestion bar. Style it with `className`/`style`, or pass a render function to build your own. */
+export declare function LanguageBanner({ className, style, children }: LanguageBannerProps): ReactElement | null;
+export interface LanguageApi {
+  language: string;
+  /** Switches language and updates the URL; resolves once translations are loaded. */
+  setLanguage: (code: string) => Promise<void>;
+  /** All languages, original first. */
+  languages: {
+    code: string;
+    native: string;
+  }[];
+  /** "/fr" - pass to your router's basename if you use client-side routing. */
+  basePath: string;
+}
+export declare function useLanguage(): LanguageApi;
+export interface LanguageSwitcherProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Accessible label for the dropdown. */
+  label?: string;
+}
+/** A dropdown that switches the whole app's language instantly, without a reload. */
+export declare function LanguageSwitcher({ className, style, label }: LanguageSwitcherProps): ReactElement;
+//#endregion