react-autolocale 0.3.0-beta.1 → 0.4.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
@@ -398,8 +442,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.

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/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 { 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-4C7cUxzd.js";
+import { n as DEFAULT_MODELS, t as DEFAULT_KEY_ENV } from "./config-ChdN65Rg.js";
 import path from "node:path";
 import fs from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -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/{project-BazDFtnp.js → project-4C7cUxzd.js}

@@ -1,5 +1,5 @@
 import { t as BANNER_EN } from "./suggestion-CkZQqMvZ.js";
-import { r as PROVIDER_NAMES } from "./config-U-SpTtCW.js";
+import { r as PROVIDER_NAMES } from "./config-ChdN65Rg.js";
 import path from "node:path";
 import fs from "node:fs";
 import { spawnSync } from "node:child_process";

package/dist/vite.js

@@ -1,5 +1,5 @@
 import { n as redirectScript } from "./redirect-pDFblLdm.js";
-import { A as readBanner, C as isSourceFile, D as translateHead, E as transformJsx, I as getLanguage, O as messageId, P as ollama, T as parserPlugins, _ as loadDicts, d as OVERRIDES_FILE, m as readOverrides, p as mergeOverrides, r as loadProject, w as walk } from "./project-BazDFtnp.js";
+import { A as readBanner, C as isSourceFile, D as translateHead, E as transformJsx, I as getLanguage, O as messageId, P as ollama, T as parserPlugins, _ as loadDicts, d as OVERRIDES_FILE, m as readOverrides, p as mergeOverrides, r as loadProject, w as walk } from "./project-4C7cUxzd.js";
 import path from "node:path";
 import fs from "node:fs";
 import { JSDOM, VirtualConsole } from "jsdom";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-autolocale",
-  "version": "0.3.0-beta.1",
+  "version": "0.4.0",
   "description": "Wrap your React + Vite app in <AutoScale> and get fully translated static pages (/fr, /es, ...). Translations are generated by an explicit CLI step with a local model, OpenAI or Anthropic; builds never translate.",
   "license": "MIT",
   "keywords": [