react-autolocale 0.3.0-beta.1 → 0.5.0

package/README.md

@@ -1,52 +1,86 @@
 # react-autolocale
 
-Write your React + Vite app in one language. react-autolocale extracts the text, translates it with the engine you choose (a free local model, OpenAI, Anthropic Claude or Google Gemini), and `vite build` produces a static page for every language (`/en/`, `/fr/`, `/es/`, ...). You don't call `t()` or manage keys, and your source files are never modified.
+Write your React + Vite app in one language. react-autolocale extracts the text, translates it with the engine you choose (Google Gemini, OpenAI, Anthropic Claude, or as a last option a free local model), and `vite build` produces a static page for every language (`/en/`, `/fr/`, `/es/`, ...). You don't call `t()` or manage keys, and your source files are never modified.
 
 Translation is a separate, explicit command. Builds only read the generated catalogs. They never download a model, call an API or wait for a translation job.
 
 ## Quick start
 
+You need a React + Vite project and an API key from the engine you choose: [Google Gemini](https://aistudio.google.com/apikey), [OpenAI](https://platform.openai.com/api-keys) or [Anthropic](https://console.anthropic.com/settings/keys). A free local model is also available, but it is the last option, not the recommended one (see [Choosing a translation engine](#choosing-a-translation-engine)).
+
 **1. Install** (npm, yarn or pnpm)
 
 ```bash
-npm install react-autolocale     # or: yarn add react-autolocale   |   pnpm add react-autolocale
+npm install react-autolocale          # or: yarn add react-autolocale   |   pnpm add react-autolocale
 ```
 
-**2. Set it up**
+**2. Run the setup wizard**
 
 ```bash
-npx react-autolocale init        # or: yarn react-autolocale init   |   pnpm exec react-autolocale init
+npx react-autolocale init             # or: yarn react-autolocale init   |   pnpm exec react-autolocale init
 ```
 
-The wizard detects your project and asks for:
-- your source language and target languages
-- a translation engine: a local model or a cloud provider (see [Choosing a translation engine](#choosing-a-translation-engine))
-- where the catalogs go
+It asks these questions, in this order:
+
+| Question | What to answer |
+| --- | --- |
+| **Source language** | The language your code's text is written in. Press **Enter** for English (`en`), or type **one** code such as `fr`. Not a list. |
+| **Target languages** | The languages to add, comma-separated, for example `fr,es,de`. Pressing Enter on an empty line just asks again. |
+| **How would you like to translate?** | Type the **number** of a cloud provider (OpenAI, Anthropic Claude or Google Gemini). Nothing is chosen for you. The local model is the last option. |
+| **Catalog folder** | Press **Enter** to keep the default. |
+| **API key** | Paste your key; what you type is hidden. It is saved to `.env`, and `.env` is added to `.gitignore`. Press Enter to skip and add `GEMINI_API_KEY=...` (or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`) to `.env` yourself later. |
 
-It then writes `auto-locale.config.ts` and adds the plugin to `vite.config`. It downloads and translates nothing.
+It writes `auto-locale.config.ts` and adds the plugin to your `vite.config`. It translates and downloads nothing. To skip the questions: `npx react-autolocale init --provider gemini --source en --locales fr,es`.
 
-**3. Wrap your app once**
+**3. Wrap your app once.** Open the file that renders `<App />` (usually `src/main.tsx` or `src/main.jsx`) and add the import and the wrapper. Keep `<StrictMode>` on the outside if you have it:
 
 ```tsx
-// main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
 import { AutoScale } from "react-autolocale";
+import App from "./App";
 
 createRoot(document.getElementById("root")!).render(
-  <AutoScale exclude={["Acme Cloud"]}>
-    <App />
-  </AutoScale>,
+  <StrictMode>
+    <AutoScale>
+      <App />
+    </AutoScale>
+  </StrictMode>,
 );
 ```
 
-**4. Generate translations, then develop and build as usual**
+No props are needed: the languages come from `auto-locale.config.ts`. Without this wrapper the translations exist, but the site stays in the original language.
+
+**4. Generate the translations**
+
+```bash
+npx react-autolocale generate
+```
+
+You should see which engine is used and a count, for example `Using gemini:gemini-3.8-flash.` and `Translated 314 strings (fr 157, es 157)`. The translations are saved in `src/generated/auto-locale/`.
+
+**This is the only step that uses your API key.** You run it on your own computer, once, and again only when your text changes. Nothing after this step needs the key or the internet.
+
+**5. Run it and check it**
 
 ```bash
-npx react-autolocale generate    # extract strings, translate new ones, write the catalogs
-npm run dev
-npm run build                    # one static page per language and route: dist/fr/, dist/fr/about/, ...
+npm run dev                           # open http://localhost:5173/fr/ and /es/ (use the port it prints)
+npm run build && npm run preview      # the finished pages: dist/fr/, dist/es/, ...
 ```
 
-After changing text in your components, run `npx react-autolocale sync`. Only new strings are translated, and a running dev server reloads when the command finishes.
+You do **not** need the API key for this step, or for deploying: `build` and `preview` only read the translations you already generated. Put the key in `.env` on your own computer and nowhere else, so you never add it to Vercel, Netlify or your CI.
+
+Read the translated pages. Machine translation can get short labels or brand names wrong: fix them as described in [Fixing a translation](#fixing-a-translation), and list brand names in `<AutoScale exclude={["Acme Cloud"]}>`.
+
+**6. Commit the translations**
+
+```bash
+git add src/generated/auto-locale
+```
+
+Commit that folder so builds and deploys never need an API key or a model. Never commit `.env`.
+
+**Whenever you change text in your components**, run `npx react-autolocale sync`. Only new strings are translated, and a running dev server reloads when it finishes.
 
 Optional: `npx react-autolocale add switcher` copies an editable language switcher into your project (see below).
 
@@ -104,13 +138,13 @@ When the config sets `sourceLocale` and `locales`, `<AutoScale>` needs no langua
 
 ## Choosing a translation engine
 
-The engine only matters to `translate`/`generate`/`sync`. Extraction, the catalogs, the build and the runtime work the same with every engine.
+The engine only matters to `translate`/`generate`/`sync`. Extraction, the catalogs, the build and the runtime work the same with every engine. `init` never picks one for you.
 
-**Local model** (`{ name: "local" }`, the default). It is free and runs on your machine with no API key: OPUS-MT for English sources and NLLB-200 for everything else, through Transformers.js. The cost is disk, RAM and CPU time:
-- **Downloads**: on the first `translate`, about 110 MB per English→X language and 870 MB for NLLB-200 (non-English sources, and Portuguese, Japanese, Korean and the other NLLB languages below). If your project doesn't have `@huggingface/transformers`, a 470 MB engine is also installed once into `~/.cache/react-autolocale/engine`.
-- **Reuse**: models are cached in `~/.cache/react-autolocale` and shared by every project. A loaded model is kept for the whole run.
-- **Speed**: OPUS-MT translates 8 strings per call; on an Apple-silicon Mac that measured about 5× faster than one at a time (32 UI strings in about 0.65 s per language once the model was loaded). NLLB runs one string at a time, because batching produced garbage, so it is much slower.
-- **Progress and interruption**: progress is printed per language, and work is saved after every batch, so Ctrl+C or a crash loses at most one batch.
+| Engine | Quality | What you need | Cost |
+| --- | --- | --- | --- |
+| **Google Gemini**, **OpenAI**, **Anthropic Claude** | Best. Each string is sent with the element it appears in. | An API key | Billed by the provider (Gemini has a free tier with low limits) |
+| **Ollama** | Good, depends on the model. | Ollama installed, with a model | Free |
+| **Local model** (last option) | **May not match the cloud models**, especially short labels and less common languages. | A **large download** on first use and a fast-enough CPU | Free |
 
 **OpenAI** (`{ name: "openai", model?, apiKeyEnv?, baseURL? }`) and **Anthropic Claude** (`{ name: "anthropic", model?, apiKeyEnv?, effort? }`) avoid the downloads and are usually quicker for large jobs. You need an API key, and usage is billed by the provider.
 - **Setup**: install the official SDK in your project (`npm install -D openai` or `npm install -D @anthropic-ai/sdk`; `init` offers to do it). Only the CLI loads it; it never reaches the browser bundle.
@@ -120,7 +154,7 @@ The engine only matters to `translate`/`generate`/`sync`. Extraction, the catalo
 
 **Google Gemini** (`{ name: "gemini", model?, apiKeyEnv?, baseURL? }`) works the same way, with nothing to install: it calls Gemini's REST API directly, so there is no SDK.
 - **Key**: create one in [Google AI Studio](https://aistudio.google.com/apikey) and put `GEMINI_API_KEY=...` in `.env` (or let `init` save it for you). Change the variable name with `apiKeyEnv`.
-- **Model**: `gemini-2.5-flash` by default. Set `model` to any model id shown in AI Studio, for example a newer Flash or a Pro model for harder text.
+- **Model**: `gemini-3.8-flash` by default. Set `model` to any model id shown in AI Studio, for example a newer Flash or a Pro model for harder text.
 - **Behavior**: the same batching and context as the other cloud providers, with structured JSON replies. Rate limits (429) and server errors are retried with backoff, honoring `Retry-After`. A rejected key, a wrong model name or an exhausted quota stops the run with a clear message before anything is stored. Free-tier keys have low rate limits, so large first runs may need to be repeated; finished work is saved after every batch.
 - **Choose it**: `npx react-autolocale init --provider gemini`, or in the config: `provider: { name: "gemini" }`.
 - **Errors**: a rejected key, an unknown model or a used-up quota stops the run instead of failing every batch. A failing provider is never swapped for another one.
@@ -133,6 +167,16 @@ The engine only matters to `translate`/`generate`/`sync`. Extraction, the catalo
 provider: async ({ texts, contexts, from, to }) => texts.map((t, i) => myTranslate(t, from, to, contexts[i])),
 ```
 
+**Local model** (`{ name: "local" }`) is the last option, not the recommended one. It is free and works offline with no API key, but you should know what you are choosing:
+- **You must download models first.** `init` and builds download nothing; the first `translate`/`generate` does.
+- **The quality may be lower than the cloud models above.** Short labels such as "Home" or "Save" and less common languages are the usual weak spots. Review the result, and fix strings in the overrides file.
+
+It runs on your machine through Transformers.js, using OPUS-MT for English sources and NLLB-200 for everything else. The cost is disk, RAM and CPU time:
+- **Downloads**: on the first `translate`, about 110 MB per English→X language and 870 MB for NLLB-200 (non-English sources, and Portuguese, Japanese, Korean and the other NLLB languages below). If your project doesn't have `@huggingface/transformers`, a 470 MB engine is also installed once into `~/.cache/react-autolocale/engine`.
+- **Reuse**: models are cached in `~/.cache/react-autolocale` and shared by every project. A loaded model is kept for the whole run.
+- **Speed**: OPUS-MT translates 8 strings per call; on an Apple-silicon Mac that measured about 5× faster than one at a time (32 UI strings in about 0.65 s per language once the model was loaded). NLLB runs one string at a time, because batching produced garbage, so it is much slower.
+- **Progress and interruption**: progress is printed per language, and work is saved after every batch, so Ctrl+C or a crash loses at most one batch.
+
 Engines receive text with protected pieces replaced by tokens (`X0X`, `{name}`) and must return them unchanged. Whatever the engine, the results are checked: a translation that drops a token or changes a number is retried once with numbers locked, and is otherwise reported as failed. It is never stored.
 
 ## Generated files and Git
@@ -277,16 +321,45 @@ const { language, languages, setLanguage, basePath } = useLanguage();
 
 ## What gets translated
 
-- Static JSX text, plus `placeholder`, `title`, `alt`, `aria-label`, `aria-placeholder` and `aria-description` on HTML elements. Other attributes (class names, styles, URLs, ids, event handlers) and props on your own components are never touched. JSX whitespace is collapsed the way React renders it.
-- **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. `translate` 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.
+You write normal code and nothing in your files changes. The scanner finds text wherever people usually put it, not only in JSX:
+
+| Where the text is written | Example |
+| --- | --- |
+| JSX text | `<h1>Welcome</h1>` |
+| Sentences with variables, links or bold words | `<p>Hello {user.name}</p>`, `<p>Read the <a href="/terms">terms</a> now</p>` (one message: `Read the {1} now`, so word order can change per language) |
+| Attributes | `placeholder`, `title`, `alt`, `aria-label` (and `aria-description`, `aria-placeholder`, ...), `<input type="submit" value="Send">`, `<meta name="description" content="...">`, `data-tooltip` |
+| Props on your own components | `<Hero title="Welcome" subtitle="Build it" />`, `<Chart text="VEHICLE · VAN" />` (not code-like props such as `variant`, `size`, `className`, `to`, `href`, `icon`) |
+| Expressions in JSX | `{open ? "Close menu" : "Open menu"}`, `{error && "Something went wrong"}`, `{name \|\| "Guest"}`, `` {`Hello, ${name}!`} ``, `{"Page " + n + " of " + total}` |
+| Data in arrays and objects, in the same file or a shared content file | `const nav = ["Home", "Pricing"]`, `{ title: "Fast", body: "Ships in seconds." }`, `[["Weight", "1.56 kg"]]`, `export const specs = {...}` in `site.js` |
+| JSON files your code imports | `import faq from "./faq.json"` (keys such as `id`, `url`, `type`, `href` are skipped) |
+| Text inside logic | `useState("Loading...")`, `setError("Invalid email")`, `alert("Saved!")`, `toast.success("Done")`, `document.title = "Dashboard"`, default props, functions that return labels |
+| Hand-written elements | `React.createElement("h1", null, "Hello")` |
+
+Numbers are kept exactly as written: `translate` checks that every digit (prices, phone numbers, hours, versions) survives translation, re-translates with the number locked if not, and otherwise keeps the original text. Use `useFormat()` (below) for numbers you compute.
+
+### How it tells text from code
+
+A string is translated when it reads like text a person sees. URLs, file names, class names (`"flex items-center"`), CSS values, colors, SVG paths, ids, lowercase code words (`"primary"`, `"submit"`), date formats and similar are left alone. Whole categories of code are never touched: object keys, `import` paths, TypeScript types and enums, `className`/`style`/`href`/`id` and other code attributes, selectors, storage keys, `fetch` and `console` calls, analytics events, class helpers (`clsx`, `cn`), and `throw new Error(...)`.
+
+**A string your code depends on is never translated, anywhere in the project.** If the code compares it (`status === "Active"`, `case "Open":`), looks it up (`icons["Home"]`, `{ Home: ... }`), checks it (`.includes("Pending")`) or names it in a type (`type S = "Open" | "Closed"`), that exact text is left as written everywhere, so nothing breaks.
+
+### When it gets one wrong
+
+- `// i18n-ignore` on or above a string (or its statement) leaves it alone; `translate="no"` on an element leaves it and everything inside it alone; `exclude` lists phrases such as brand names that are never translated.
+- `msg("text")` forces a string to be translated wherever the automatic rules can't see it, such as a lowercase word: `import { msg } from "react-autolocale"` then `msg("open")`, `msg("Hello {name}", { name })`. It returns the text, so it is safe without the plugin.
 
 ```tsx
 <p translate="no">Acme Cloud</p>                       // never translated
-<section translate="no"><Terminal /></section>          // nothing inside is translated
+const DEBUG_LABEL = "Internal build"; // i18n-ignore
 ```
 
+### Good to know
+
+- **Switching language reloads the page** when your app has text outside React components (data in a `site.js`, `useState` starting values, JSON): that text is translated when the page loads, so the new language needs a fresh page. Apps that only use text in components switch in place without a reload. Either way each language has its own URL.
+- **Compare ids, not labels.** A tab labelled `"All"` that your code checks with `=== "All"` stays in English (the code needs that exact text). To translate the label, compare something else: `{ id: "all", label: "All" }` and `filter === "all"`.
+- Text passed through your own function (`t(...)`-style helpers) and data that arrives at runtime (API responses, user-written content) is not translated: it does not exist at build time. Text you write in code around those values is.
+- Not translated yet: Markdown/MDX files, HTML inside strings (`dangerouslySetInnerHTML`), and CSS `content:`.
+
 ## Supported languages
 
 Use these codes in `languages={[...]}`. The source (`original`) language can be any of them.
@@ -398,8 +471,12 @@ With `seo`, switching language navigates to the real page (so its head tags are
 
 ## Troubleshooting
 
+- **`init` says `"fr, es" is not a supported code` at "Source language"**: that question takes one code (your code's language, usually `en`). The list of languages to add comes at the next question.
+- **The site is still in English after `generate`**: wrap your app in `<AutoScale>` (step 3 of the quick start), restart `npm run dev`, and open `/fr/` or `/es/`.
+- **`init` printed instructions with `original="en" languages={...}`**: you have the older 0.2.0, which works differently. Upgrade: `npm install react-autolocale@latest` (see [Upgrading from earlier versions](#upgrading-from-earlier-versions)).
 - **"No translations in src/generated/auto-locale/ yet" during a build**: run `npx react-autolocale generate`, then commit the folder.
 - **"OPENAI_API_KEY is not set"**: add it to `.env` in the project root or export it in your shell, then rerun `translate`. No request was made.
+- **Gemini says "model not found" or "no longer available"**: Google retires models over time. Set `model` in the provider to a current id from [AI Studio](https://aistudio.google.com) (`provider: { name: "gemini", model: "<id>" }`) and run `generate` again; strings that already succeeded are kept.
 - **"This provider needs the openai package"** (or `@anthropic-ai/sdk`): install it as a dev dependency of your app.
 - **Some strings failed**: the report lists them by id, language and reason. Rerun `npx react-autolocale translate`, or write the value into the catalog or the overrides file yourself.
 - **The local model is slow**: NLLB languages run one string at a time on the CPU. Translate a subset with `--lang`, or switch `provider` to OpenAI or Claude for big jobs. Existing translations are kept either way.
@@ -409,7 +486,8 @@ With `seo`, switching language navigates to the real page (so its head tags are
 ## 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.
+- No plural rules: write `{count} message(s)` or branch in your code (`count === 1 ? "1 message" : `${count} messages``; both branches are translated).
+- Strings your code compares, uses as keys or names in types are left as written (see "How it tells text from code"). Lowercase single words in data (`["red", "green"]`) look like code and are skipped; wrap them with `msg()`.
 - 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.
 - The CLI reads `auto-locale.config.ts`, not `vite.config`. Set `include` there if you change the plugin's `include`.

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { F as toTranslator, I as getLanguage, M as TranslationError, N as createLocalTranslator, P as ollama, S as scanProject, a as findSite, b as manifestFile, c as hasRootSrc, d as OVERRIDES_FILE, f as exportTranslations, g as importLegacyCache, h as catalogFile, i as defaultInclude, j as writeJson, k as ensureBanner, l as resolveOutput, m as readOverrides, n as loadConfigFile, o as META_DIR, r as loadProject, s as defaultOutput, t as findConfigFile, u as toProjectPath, v as removeFromCatalogs, x as readManifest, y as translateMissing } from "./project-BazDFtnp.js";
-import { n as DEFAULT_MODELS, t as DEFAULT_KEY_ENV } from "./config-U-SpTtCW.js";
-import path from "node:path";
+import { B as getLanguage, F as writeJson, I as TranslationError, L as createLocalTranslator, N as ensureBanner, R as ollama, S as scanProject, a as findSite, b as manifestFile, c as hasRootSrc, d as OVERRIDES_FILE, f as exportTranslations, g as importLegacyCache, h as catalogFile, i as defaultInclude, l as resolveOutput, m as readOverrides, n as loadConfigFile, o as META_DIR, r as loadProject, s as defaultOutput, t as findConfigFile, u as toProjectPath, v as removeFromCatalogs, x as readManifest, y as translateMissing, z as toTranslator } from "./project-DcYRIvym.js";
+import { n as DEFAULT_MODELS, t as DEFAULT_KEY_ENV } from "./config-ChdN65Rg.js";
 import fs from "node:fs";
+import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
@@ -622,11 +622,6 @@ async function runInit(root, flags, prompt, out) {
 			if (bad.length) throw new Error(`Unsupported language code${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}.`);
 		}
 		const name = flags.provider ?? await prompt.choose("How would you like to translate your application?", [
-			{
-				value: "local",
-				label: "Local model (OPUS-MT / NLLB-200)",
-				help: "Free and runs on your machine; no API key. Models are large (about 110 MB per English->X language, 870 MB for\nother pairs) and translating on the CPU uses RAM and time, so big apps or many languages can be slow.\nModels are cached in ~/.cache/react-autolocale and downloaded only when you run `translate` or `generate`,\nnever during init or builds."
-			},
 			{
 				value: "openai",
 				label: "Cloud AI: OpenAI",
@@ -641,8 +636,14 @@ async function runInit(root, flags, prompt, out) {
 				value: "gemini",
 				label: "Cloud AI: Google Gemini",
 				help: "Uses a hosted AI model. No large downloads, and usually faster for big translation jobs. Needs an API key;\nprovider usage may be billed to your account."
+			},
+			{
+				value: "local",
+				label: "Local model (OPUS-MT / NLLB-200): free, but a large download and lower quality",
+				help: "Free and works offline, with no API key, but it needs a large download the first time (about 110 MB per\nEnglish->X language, 870 MB for other pairs) and translating on your CPU is slow for big apps. The quality may\nnot match the cloud models, especially for short labels and less common languages, so review the result.\nModels are cached in ~/.cache/react-autolocale and downloaded only when you run `translate` or `generate`,\nnever during init or builds."
 			}
-		], "local");
+		]);
+		if (!name) throw new Error("Choose a translation engine: --provider openai|anthropic|gemini|local|ollama (add --model for ollama).");
 		let provider;
 		if (name === "openai" || name === "anthropic" || name === "gemini") provider = {
 			name,
@@ -796,7 +797,8 @@ function createPrompter(interactive) {
 				console.log(`  ${i + 1}) ${o.label}`);
 				if (o.help) console.log(o.help.replace(/^/gm, "     ") + "\n");
 			});
-			const def = String(options.findIndex((o) => o.value === fallback) + 1);
+			const index = options.findIndex((o) => o.value === fallback);
+			const def = index >= 0 ? String(index + 1) : "";
 			for (;;) {
 				const answer = await ask("Choose a number", def);
 				const picked = options[Number(answer) - 1];

package/dist/{config-U-SpTtCW.js → config-ChdN65Rg.js}

@@ -13,7 +13,7 @@ const PROVIDER_NAMES = [
 const DEFAULT_MODELS = {
 	openai: "gpt-6-astra",
 	anthropic: "claude-opus-5-5",
-	gemini: "gemini-2.5-flash"
+	gemini: "gemini-3.8-flash"
 };
 const DEFAULT_KEY_ENV = {
 	openai: "OPENAI_API_KEY",

package/dist/config.d.ts

@@ -33,7 +33,7 @@ interface AnthropicProvider {
 /** Google Gemini through its REST API. No SDK needed. Get a key at https://aistudio.google.com/apikey. */
 interface GeminiProvider {
   name: "gemini";
-  /** Defaults to "gemini-2.5-flash". Use any model id listed in Google AI Studio. */
+  /** Defaults to "gemini-3.8-flash". Use any model id listed in Google AI Studio. */
   model?: string;
   /** Environment variable holding the key. Defaults to GEMINI_API_KEY. */
   apiKeyEnv?: string;

package/dist/config.js

@@ -1 +1 @@
-export { i as defineConfig } from "./config-U-SpTtCW.js";
+export { i as defineConfig } from "./config-ChdN65Rg.js";

package/dist/index.d.ts

@@ -10,6 +10,16 @@ declare global {
     };
   }
 }
+/**
+ * Marks any string for translation, wherever the automatic rules cannot see it (a lowercase word, text built in an
+ * unusual way): `msg("Open")`, `msg("Hello {name}", { name })`. The build looks the text up in the catalogs; without
+ * the plugin it simply returns the text.
+ */
+export declare function msg(text: string, vars?: Record<string, unknown>): string;
+/** @internal Used by the Vite plugin for a string outside any component. */
+export declare function __rlText(i: string, s: string): string;
+/** @internal Same, for a string with variables: `Hello, ${name}` becomes ("Hello, {name}", { name }). */
+export declare function __rlFmt(i: string, s: string, vars: Record<string, unknown>): string;
 export interface AutoScaleProps {
   /** Language the app is written in, e.g. "en". Must be a literal so the build can read it. */
   original: string;
@@ -37,7 +47,9 @@ export declare function __T({ i, s }: {
   s: string;
 }): ReactElement;
 /** @internal Inserted by the Vite plugin for translated attributes (placeholder, alt, ...). */
-export declare function __useT(): (i: string, s: string) => string;
+export declare function __useT(): ((i: string, s: string) => string) & {
+  f: (i: string, s: string, vars: Record<string, unknown>) => string;
+};
 /** @internal Inserted by the Vite plugin for text with variables, e.g. `Hello {name}`. */
 export declare function __TD({ i, s, v }: {
   i: string;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { r as redirectTarget, t as STORAGE_KEY } from "./redirect-pDFblLdm.js";
 import { n as DISMISSED_KEY, r as suggestLanguage, t as BANNER_EN } from "./suggestion-CkZQqMvZ.js";
 import { Fragment, createContext, createElement, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { banner, languages, loaders, original, originalNative, seo } from "virtual:react-autolocale";
+import { banner, eager, languages, loaders, original, originalNative, seo } from "virtual:react-autolocale";
 //#region src/runtime/index.ts
 const hasDom = typeof window !== "undefined" && typeof document !== "undefined";
 const codes = /* @__PURE__ */ new Set([original, ...languages.map((l) => l.code)]);
@@ -22,6 +22,43 @@ function load(code) {
 	if (!loader) return Promise.resolve({});
 	return loader().then((m) => m.default).catch(() => ({})).then((dict) => (cache.set(code, dict), dict));
 }
+/**
+* Strings written outside React components (data in a content file, helpers, class components) are looked up
+* here, at the moment the code runs. The dictionary is the one for the language in the URL, taken from the page
+* itself (production, prerendering) or from the catalogs the dev server inlines.
+*/
+let currentDict = null;
+/** Set once such a string has been used: it cannot follow an in-place language change, so switching reloads. */
+let staticUsed = false;
+function dictNow() {
+	if (currentDict) return currentDict;
+	const boot = hasDom ? window.__AUTOSCALE__ : void 0;
+	const lang = (hasDom ? prefixOf(window.location.pathname) : null) ?? boot?.lang ?? original;
+	if (boot && boot.lang === lang) currentDict = boot.dict;
+	else currentDict = lang === original ? {} : eager[lang] ?? cache.get(lang) ?? {};
+	return currentDict;
+}
+function fill(template, vars) {
+	return template.replace(/\{(\w+)\}/g, (match, name) => name in vars ? String(vars[name] ?? "") : match);
+}
+/**
+* Marks any string for translation, wherever the automatic rules cannot see it (a lowercase word, text built in an
+* unusual way): `msg("Open")`, `msg("Hello {name}", { name })`. The build looks the text up in the catalogs; without
+* the plugin it simply returns the text.
+*/
+function msg(text, vars) {
+	return vars ? fill(text, vars) : text;
+}
+/** @internal Used by the Vite plugin for a string outside any component. */
+function __rlText(i, s) {
+	staticUsed = true;
+	return dictNow()[i] || s;
+}
+/** @internal Same, for a string with variables: `Hello, ${name}` becomes ("Hello, {name}", { name }). */
+function __rlFmt(i, s, vars) {
+	staticUsed = true;
+	return fill(dictNow()[i] || s, vars);
+}
 const Context = createContext({
 	language: original,
 	dict: {},
@@ -34,6 +71,7 @@ function initialState() {
 	};
 	const boot = window.__AUTOSCALE__;
 	if (boot) cache.set(boot.lang, boot.dict);
+	for (const [code, dict] of Object.entries(eager)) if (!cache.has(code)) cache.set(code, dict);
 	const { pathname, search, hash } = window.location;
 	const fromUrl = prefixOf(pathname);
 	if (fromUrl === null) {
@@ -65,13 +103,14 @@ function initialState() {
 */
 function AutoScale({ children }) {
 	const [state, setState] = useState(initialState);
+	currentDict = state.dict;
 	const apply = useCallback(async (code, push) => {
 		if (!codes.has(code)) return;
 		if (push && hasDom) {
 			try {
 				window.localStorage.setItem(STORAGE_KEY, code);
 			} catch {}
-			if (seo) {
+			if (seo || staticUsed) {
 				window.location.assign(pathFor(code));
 				return;
 			}
@@ -108,7 +147,11 @@ function __T({ i, s }) {
 /** @internal Inserted by the Vite plugin for translated attributes (placeholder, alt, ...). */
 function __useT() {
 	const { dict } = useContext(Context);
-	return useCallback((i, s) => dict[i] || s, [dict]);
+	return useMemo(() => {
+		const lookup = ((i, s) => dict[i] || s);
+		lookup.f = (i, s, vars) => fill(dict[i] || s, vars);
+		return lookup;
+	}, [dict]);
 }
 /** @internal Inserted by the Vite plugin for text with variables, e.g. `Hello {name}`. */
 function __TD({ i, s, v }) {
@@ -263,4 +306,4 @@ function LanguageSwitcher({ className, style, label = "Language" }) {
 	}, l.native)));
 }
 //#endregion
-export { AutoScale, ForLanguages, LanguageBanner, LanguageSwitcher, Localized, __T, __TD, __useT, useFormat, useLanguage, useLanguageSuggestion, useLocalized };
+export { AutoScale, ForLanguages, LanguageBanner, LanguageSwitcher, Localized, __T, __TD, __rlFmt, __rlText, __useT, msg, useFormat, useLanguage, useLanguageSuggestion, useLocalized };