react-autolocale 0.1.0 → 0.2.0

package/dist/overrides-ZQ6meLck.js

@@ -0,0 +1,557 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import os from "node:os";
+import { pathToFileURL } from "node:url";
+const byCode = new Map([
+	{
+		code: "en",
+		native: "English",
+		english: "English",
+		nllb: "eng_Latn"
+	},
+	{
+		code: "fr",
+		native: "Français",
+		english: "French",
+		nllb: "fra_Latn",
+		opus: "fr"
+	},
+	{
+		code: "es",
+		native: "Español",
+		english: "Spanish",
+		nllb: "spa_Latn",
+		opus: "es"
+	},
+	{
+		code: "de",
+		native: "Deutsch",
+		english: "German",
+		nllb: "deu_Latn",
+		opus: "de"
+	},
+	{
+		code: "it",
+		native: "Italiano",
+		english: "Italian",
+		nllb: "ita_Latn",
+		opus: "it"
+	},
+	{
+		code: "pt",
+		native: "Português",
+		english: "Portuguese",
+		nllb: "por_Latn"
+	},
+	{
+		code: "nl",
+		native: "Nederlands",
+		english: "Dutch",
+		nllb: "nld_Latn",
+		opus: "nl"
+	},
+	{
+		code: "ru",
+		native: "Русский",
+		english: "Russian",
+		nllb: "rus_Cyrl",
+		opus: "ru"
+	},
+	{
+		code: "zh",
+		native: "中文",
+		english: "Chinese (Simplified)",
+		nllb: "zho_Hans",
+		opus: "zh"
+	},
+	{
+		code: "ja",
+		native: "日本語",
+		english: "Japanese",
+		nllb: "jpn_Jpan"
+	},
+	{
+		code: "ko",
+		native: "한국어",
+		english: "Korean",
+		nllb: "kor_Hang"
+	},
+	{
+		code: "ar",
+		native: "العربية",
+		english: "Arabic",
+		nllb: "arb_Arab",
+		opus: "ar",
+		rtl: true
+	},
+	{
+		code: "hi",
+		native: "हिन्दी",
+		english: "Hindi",
+		nllb: "hin_Deva",
+		opus: "hi"
+	},
+	{
+		code: "tr",
+		native: "Türkçe",
+		english: "Turkish",
+		nllb: "tur_Latn"
+	},
+	{
+		code: "pl",
+		native: "Polski",
+		english: "Polish",
+		nllb: "pol_Latn"
+	},
+	{
+		code: "sv",
+		native: "Svenska",
+		english: "Swedish",
+		nllb: "swe_Latn",
+		opus: "sv"
+	},
+	{
+		code: "da",
+		native: "Dansk",
+		english: "Danish",
+		nllb: "dan_Latn",
+		opus: "da"
+	},
+	{
+		code: "no",
+		native: "Norsk",
+		english: "Norwegian",
+		nllb: "nob_Latn"
+	},
+	{
+		code: "fi",
+		native: "Suomi",
+		english: "Finnish",
+		nllb: "fin_Latn",
+		opus: "fi"
+	},
+	{
+		code: "cs",
+		native: "Čeština",
+		english: "Czech",
+		nllb: "ces_Latn",
+		opus: "cs"
+	},
+	{
+		code: "hu",
+		native: "Magyar",
+		english: "Hungarian",
+		nllb: "hun_Latn",
+		opus: "hu"
+	},
+	{
+		code: "ro",
+		native: "Română",
+		english: "Romanian",
+		nllb: "ron_Latn",
+		opus: "ro"
+	},
+	{
+		code: "uk",
+		native: "Українська",
+		english: "Ukrainian",
+		nllb: "ukr_Cyrl",
+		opus: "uk"
+	},
+	{
+		code: "el",
+		native: "Ελληνικά",
+		english: "Greek",
+		nllb: "ell_Grek"
+	},
+	{
+		code: "he",
+		native: "עברית",
+		english: "Hebrew",
+		nllb: "heb_Hebr",
+		rtl: true
+	},
+	{
+		code: "vi",
+		native: "Tiếng Việt",
+		english: "Vietnamese",
+		nllb: "vie_Latn",
+		opus: "vi"
+	},
+	{
+		code: "id",
+		native: "Bahasa Indonesia",
+		english: "Indonesian",
+		nllb: "ind_Latn",
+		opus: "id"
+	},
+	{
+		code: "th",
+		native: "ไทย",
+		english: "Thai",
+		nllb: "tha_Thai"
+	},
+	{
+		code: "bn",
+		native: "বাংলা",
+		english: "Bengali",
+		nllb: "ben_Beng"
+	},
+	{
+		code: "fa",
+		native: "فارسی",
+		english: "Persian",
+		nllb: "pes_Arab",
+		rtl: true
+	},
+	{
+		code: "ur",
+		native: "اردو",
+		english: "Urdu",
+		nllb: "urd_Arab",
+		rtl: true
+	},
+	{
+		code: "bg",
+		native: "Български",
+		english: "Bulgarian",
+		nllb: "bul_Cyrl"
+	},
+	{
+		code: "hr",
+		native: "Hrvatski",
+		english: "Croatian",
+		nllb: "hrv_Latn"
+	},
+	{
+		code: "sk",
+		native: "Slovenčina",
+		english: "Slovak",
+		nllb: "slk_Latn"
+	},
+	{
+		code: "ca",
+		native: "Català",
+		english: "Catalan",
+		nllb: "cat_Latn"
+	},
+	{
+		code: "ms",
+		native: "Bahasa Melayu",
+		english: "Malay",
+		nllb: "zsm_Latn"
+	},
+	{
+		code: "sw",
+		native: "Kiswahili",
+		english: "Swahili",
+		nllb: "swh_Latn"
+	},
+	{
+		code: "tl",
+		native: "Tagalog",
+		english: "Tagalog",
+		nllb: "tgl_Latn"
+	}
+].map((l) => [l.code, l]));
+function getLanguage(code) {
+	return byCode.get(code);
+}
+//#endregion
+//#region src/core/translate.ts
+function toTranslator(engine) {
+	if (typeof engine !== "function") return engine;
+	return { translate: (texts, from, to, contexts = []) => engine({
+		texts,
+		contexts: texts.map((_, i) => contexts[i] ?? ""),
+		from,
+		to
+	}) };
+}
+/**
+* Uses a local LLM through Ollama (free, runs on your machine). Unlike the default models it is told
+* where each string appears, which fixes most one-word mistakes ("Home" in a nav bar is not "Sommaire").
+*/
+function ollama(options = { model: "llama3.1" }) {
+	const url = (options.url ?? "http://localhost:11434").replace(/\/+$/, "");
+	return { async translate(texts, from, to, contexts = []) {
+		const out = [];
+		for (let i = 0; i < texts.length; i++) {
+			const where = contexts[i] ? ` It appears in a website ${contexts[i]} element.` : "";
+			const res = await fetch(`${url}/api/chat`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					model: options.model,
+					stream: false,
+					options: { temperature: 0 },
+					messages: [{
+						role: "system",
+						content: `You translate website interface text from ${from} to ${to}.${where} Keep tokens like X0X, X1X and {name} exactly as written. Reply with only the translation.`
+					}, {
+						role: "user",
+						content: texts[i]
+					}]
+				})
+			});
+			if (!res.ok) throw new Error(`Ollama request failed (${res.status}). Is it running at ${url}?`);
+			const body = await res.json();
+			out.push((body.message?.content ?? "").trim());
+		}
+		return out;
+	} };
+}
+const ENGINE_PACKAGE = "@huggingface/transformers@^4.3.1";
+const ENGINE_DIR = path.join(os.homedir(), ".cache", "react-autolocale", "engine");
+/**
+* Finds the translation engine. Uses the project's own copy if it has one; otherwise installs it once
+* into ~/.cache/react-autolocale/engine (shared by all projects, never touches the project's node_modules).
+*/
+async function loadEngine(log) {
+	try {
+		return await import("@huggingface/transformers");
+	} catch {}
+	const require = createRequire(path.join(ENGINE_DIR, "package.json"));
+	const find = () => require.resolve("@huggingface/transformers");
+	let entry;
+	try {
+		entry = find();
+	} catch {
+		log("[react-autolocale] Installing the translation engine (one time, about 440 MB)...");
+		fs.mkdirSync(ENGINE_DIR, { recursive: true });
+		const pkg = path.join(ENGINE_DIR, "package.json");
+		if (!fs.existsSync(pkg)) fs.writeFileSync(pkg, JSON.stringify({
+			name: "react-autolocale-engine",
+			private: true
+		}));
+		const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+		const res = spawnSync(npm, [
+			"install",
+			"--prefix",
+			ENGINE_DIR,
+			"--no-audit",
+			"--no-fund",
+			"--loglevel=error",
+			ENGINE_PACKAGE
+		], {
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		try {
+			if (res.status !== 0) throw new Error("npm failed");
+			entry = find();
+		} catch {
+			throw new Error(`Could not install the translation engine automatically. Install it yourself: npm install -D @huggingface/transformers`);
+		}
+	}
+	const mod = await import(pathToFileURL(entry).href);
+	return mod.pipeline ? mod : mod.default;
+}
+const NLLB_MODEL = "Xenova/nllb-200-distilled-600M";
+const BATCH = 1;
+/**
+* Free, offline translation using Transformers.js (ONNX models run on the CPU).
+* Models are downloaded once from Hugging Face and cached in ~/.cache/react-autolocale.
+* English -> X uses small per-language OPUS-MT models where they exist; everything else uses NLLB-200.
+*/
+function createLocalTranslator(log = () => {}) {
+	const pipes = /* @__PURE__ */ new Map();
+	let hf = null;
+	const getPipe = (model) => {
+		let p = pipes.get(model);
+		if (!p) {
+			hf ??= loadEngine(log).then((m) => {
+				m.env.cacheDir = path.join(os.homedir(), ".cache", "react-autolocale", "models");
+				return m;
+			});
+			log(`Loading model ${model} (first run downloads it)...`);
+			let lastPct = -10;
+			p = hf.then((m) => m.pipeline("translation", model, {
+				dtype: "q8",
+				progress_callback: (e) => {
+					if (e.status === "progress" && e.progress - lastPct >= 10) {
+						lastPct = e.progress;
+						log(`  downloading ${e.file}: ${Math.round(e.progress)}%`);
+					}
+				}
+			}));
+			pipes.set(model, p);
+		}
+		return p;
+	};
+	const run = async (model, texts, options) => {
+		const pipe = await getPipe(model);
+		const out = [];
+		for (let i = 0; i < texts.length; i += BATCH) {
+			const res = await pipe(texts.slice(i, i + BATCH), {
+				max_new_tokens: 256,
+				...options
+			});
+			out.push(...res.map((r) => r.translation_text.trim()));
+		}
+		return out;
+	};
+	return { async translate(texts, from, to) {
+		const src = getLanguage(from);
+		const dst = getLanguage(to);
+		if (!src || !dst) throw new Error(`Unsupported language: ${!src ? from : to}`);
+		if (from === "en" && dst.opus) try {
+			return await run(`Xenova/opus-mt-en-${dst.opus}`, texts, {});
+		} catch (err) {
+			log(`  OPUS-MT model for "${to}" unavailable (${err.message}); falling back to NLLB.`);
+		}
+		return run(NLLB_MODEL, texts, {
+			src_lang: src.nllb,
+			tgt_lang: dst.nllb
+		});
+	} };
+}
+const token = (i) => `X${i}X`;
+/** Prices, phone numbers, versions, hours, percentages: kept exactly as written. */
+const NUMBER = /[$€£¥]?\d+(?:[.,:\-/]\d+)*(?:[a-zA-Z]{1,2}\b)?%?/g;
+/** Runtime values like {name} must survive translation untouched. */
+const PLACEHOLDER = /\{\w+\}/g;
+/**
+* Swaps protected pieces for placeholders so the model leaves them alone: excluded phrases and glossary terms
+* (restored as given), {placeholders}, and numbers. `phrases[i]` is what `X{i}X` turns back into.
+*/
+function mask(text, exclude, opts = {}) {
+	const phrases = [];
+	const mark = (restore) => {
+		phrases.push(restore);
+		return String.fromCharCode(57344) + String.fromCharCode(57600 + phrases.length - 1) + String.fromCharCode(57345);
+	};
+	let masked = text;
+	const entries = [...exclude.map((p) => [p, p]), ...Object.entries(opts.glossary ?? {})].sort((a, b) => b[0].length - a[0].length);
+	for (const [from, to] of entries) if (from && masked.includes(from)) masked = masked.split(from).join(mark(to));
+	masked = masked.replace(PLACEHOLDER, (m) => mark(m));
+	if (opts.numbers !== false) masked = masked.replace(NUMBER, (m) => mark(m));
+	return {
+		masked: masked.replace(/\uE000([\uE100-\uE9FF])\uE001/g, (_, c) => token(c.charCodeAt(0) - 57600)),
+		phrases
+	};
+}
+/** Puts protected pieces back. Returns null if the model dropped or mangled a placeholder. */
+function unmask(translated, phrases) {
+	let out = translated;
+	for (let i = 0; i < phrases.length; i++) {
+		if (!out.includes(token(i))) return null;
+		out = out.split(token(i)).join(phrases[i]);
+	}
+	return /X\d+X/.test(out) ? null : out;
+}
+/** True if every run of digits in the source still appears in the translation. */
+function digitsPreserved(source, translated) {
+	const key = (s) => (s.match(/\d+/g) ?? []).sort().join(",");
+	return key(source) === key(translated);
+}
+//#endregion
+//#region src/core/cache.ts
+/** Generated translations live here, outside the source tree. */
+function cacheDir(root) {
+	return path.join(root, "node_modules", ".cache", "react-autolocale");
+}
+function cacheFile(root, lang) {
+	return path.join(cacheDir(root), `${lang}.json`);
+}
+function readDict(file) {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		return {};
+	}
+}
+/** Strings that are entirely an excluded phrase need no translation. */
+function needsTranslation(s, exclude) {
+	return !exclude.includes(s.trim());
+}
+/** Translates only strings missing from the cache, drops unused ones, and returns every language's dictionary. */
+async function ensureTranslations(opts) {
+	const { root, site, strings } = opts;
+	const log = opts.log ?? (() => {});
+	const wanted = strings.filter((s) => needsTranslation(s, site.exclude));
+	const result = {};
+	fs.mkdirSync(cacheDir(root), { recursive: true });
+	for (const lang of site.languages) {
+		const file = cacheFile(root, lang);
+		const existing = readDict(file);
+		const fixed = opts.overrides?.[lang] ?? {};
+		const missing = wanted.filter((s) => !existing[s] && !fixed[s]);
+		const next = {};
+		for (const s of wanted) if (existing[s]) next[s] = existing[s];
+		for (const s of wanted) if (fixed[s]) next[s] = fixed[s];
+		const terms = opts.glossary?.[lang] ?? {};
+		for (const s2 of missing) if (terms[s2]) next[s2] = terms[s2];
+		const toTranslate = missing.filter((s2) => !terms[s2]);
+		if (toTranslate.length) {
+			log(`[react-autolocale] ${lang}: translating ${toTranslate.length} new string${toTranslate.length === 1 ? "" : "s"}...`);
+			const ctx = toTranslate.map((s2) => opts.contexts?.[s2] ?? "");
+			const run = async (items, contextList, numbers) => {
+				const jobs = items.map((s2) => ({
+					source: s2,
+					...mask(s2, site.exclude, {
+						glossary: terms,
+						numbers
+					})
+				}));
+				const out = await opts.getTranslator().translate(jobs.map((j) => j.masked), site.original, lang, contextList);
+				return jobs.map((job, i) => unmask(out[i] ?? "", job.phrases));
+			};
+			const first = await run(toTranslate, ctx, false);
+			const redo = toTranslate.map((source, i) => i).filter((i) => !first[i] || !digitsPreserved(toTranslate[i], first[i]));
+			const second = redo.length ? await run(redo.map((i) => toTranslate[i]), redo.map((i) => ctx[i]), true) : [];
+			toTranslate.forEach((source, i) => {
+				const result = redo.includes(i) ? second[redo.indexOf(i)] : first[i];
+				if (result) next[source] = result;
+				else log(`[react-autolocale] ${lang}: kept "${source}" untranslated (could not preserve its numbers or excluded text)`);
+			});
+		}
+		if (!(JSON.stringify(existing) === JSON.stringify(next))) fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+		result[lang] = next;
+	}
+	return result;
+}
+//#endregion
+//#region src/core/overrides.ts
+/** A committed file the developer edits to correct translations. It always wins over machine translation. */
+const OVERRIDES_FILE = "react-autolocale.overrides.json";
+function readOverrides(root) {
+	const file = path.join(root, OVERRIDES_FILE);
+	if (!fs.existsSync(file)) return {};
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new Error(`${OVERRIDES_FILE} is not valid JSON: ${err.message}`);
+	}
+}
+/** Later arguments win. */
+function mergeOverrides(...all) {
+	const out = {};
+	for (const o of all) for (const [lang, strings] of Object.entries(o ?? {})) out[lang] = {
+		...out[lang],
+		...strings
+	};
+	return out;
+}
+/** Writes every generated translation into the overrides file (keeping entries already there) so it can be edited. */
+function exportTranslations(root) {
+	const dir = cacheDir(root);
+	if (!fs.existsSync(dir)) throw new Error("No generated translations found. Run your build first.");
+	const generated = {};
+	for (const name of fs.readdirSync(dir)) {
+		const m = /^([a-z]{2,3})\.json$/i.exec(name);
+		if (m) generated[m[1].toLowerCase()] = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+	}
+	if (!Object.keys(generated).length) throw new Error("No generated translations found. Run your build first.");
+	const merged = mergeOverrides(generated, readOverrides(root));
+	const file = path.join(root, OVERRIDES_FILE);
+	fs.writeFileSync(file, JSON.stringify(merged, null, 2) + "\n");
+	return {
+		file,
+		languages: Object.fromEntries(Object.entries(merged).map(([l, s]) => [l, Object.keys(s).length]))
+	};
+}
+//#endregion
+export { cacheDir as a, createLocalTranslator as c, toTranslator as d, unmask as f, readOverrides as i, mask as l, exportTranslations as n, cacheFile as o, getLanguage as p, mergeOverrides as r, ensureTranslations as s, OVERRIDES_FILE as t, ollama as u };

package/dist/{redirect-CKNY4ru5.js → suggestion-UZQ8ngd0.js}

@@ -18,9 +18,35 @@ function redirectTarget(opts) {
 	return `/${target}${pathname}${opts.search ?? ""}${opts.hash ?? ""}`;
 }
 const STORAGE_KEY = "react-autolocale:language";
-/** The same logic as a tiny inline script, so the root page redirects before anything paints. */
+/**
+* The same logic as a tiny inline script, so the root page redirects before anything paints. When the visitor stays,
+* the URL is rewritten to the original language's prefix (no reload) so client-side routers see a prefixed path.
+*/
 function redirectScript(codes, original) {
-	return `(function(){try{var C=${JSON.stringify(codes)},O=${JSON.stringify(original)},p=location.pathname,m=/^\\/([a-z]{2,3})(?=\\/|$)/i.exec(p);if(m&&C.indexOf(m[1].toLowerCase())>-1)return;var t=null,s=localStorage.getItem(${JSON.stringify(STORAGE_KEY)});if(s&&C.indexOf(s)>-1)t=s;var l=navigator.languages||[navigator.language];for(var i=0;i<l.length&&!t;i++){var c=String(l[i]).toLowerCase();if(C.indexOf(c)>-1)t=c;else if(C.indexOf(c.split("-")[0])>-1)t=c.split("-")[0]}if(t&&t!==O)location.replace("/"+t+p+location.search+location.hash)}catch(e){}})()`;
+	return `(function(){try{var C=${JSON.stringify(codes)},O=${JSON.stringify(original)},p=location.pathname,m=/^\\/([a-z]{2,3})(?=\\/|$)/i.exec(p);if(m&&C.indexOf(m[1].toLowerCase())>-1)return;var t=null,s=localStorage.getItem(${JSON.stringify(STORAGE_KEY)});if(s&&C.indexOf(s)>-1)t=s;var l=navigator.languages||[navigator.language];for(var i=0;i<l.length&&!t;i++){var c=String(l[i]).toLowerCase();if(C.indexOf(c)>-1)t=c;else if(C.indexOf(c.split("-")[0])>-1)t=c.split("-")[0]}if(t&&t!==O)location.replace("/"+t+p+location.search+location.hash);else history.replaceState(history.state,"","/"+O+p+location.search+location.hash)}catch(e){}})()`;
+}
+//#endregion
+//#region src/core/suggestion.ts
+/**
+* Should we offer the visitor another language? Looks at the first browser language we support:
+* if it is the page's own language, was dismissed, or the visitor already chose a language, offer nothing.
+*/
+function suggestLanguage(opts) {
+	if (opts.chosen) return null;
+	for (const tag of opts.browser) {
+		const lower = String(tag).toLowerCase();
+		const base = lower.split("-")[0];
+		const code = opts.codes.includes(lower) ? lower : opts.codes.includes(base) ? base : null;
+		if (!code) continue;
+		return code === opts.current || opts.dismissed.includes(code) ? null : code;
+	}
+	return null;
 }
+const DISMISSED_KEY = "react-autolocale:banner-dismissed";
+const BANNER_EN = {
+	prompt: "This page is also available in {language}.",
+	switch: "Read in {language}",
+	dismiss: "Not now"
+};
 //#endregion
-export { redirectScript as n, redirectTarget as r, STORAGE_KEY as t };
+export { redirectScript as a, STORAGE_KEY as i, DISMISSED_KEY as n, redirectTarget as o, suggestLanguage as r, BANNER_EN as t };

package/dist/vite.d.ts

@@ -1,16 +1,44 @@
 import { Plugin } from "vite";
+//#region src/core/translate.d.ts
+interface Translator {
+  /** `contexts[i]` says where `texts[i]` appears ("button", "h1", "placeholder", ...). Engines may ignore it. */
+  translate(texts: string[], from: string, to: string, contexts?: string[]): Promise<string[]>;
+}
+/** The simplest way to plug in your own engine (DeepL, an LLM, ...): one function. */
+type TranslateFn = (request: {
+  texts: string[];
+  contexts: string[];
+  from: string;
+  to: string;
+}) => Promise<string[]>;
+/**
+ * Uses a local LLM through Ollama (free, runs on your machine). Unlike the default models it is told
+ * where each string appears, which fixes most one-word mistakes ("Home" in a nav bar is not "Sommaire").
+ */
+export declare function ollama(options?: {
+  model: string;
+  url?: string;
+}): Translator;
+//#endregion
 //#region src/vite/index.d.ts
 export interface ReactAutolocaleOptions {
   /** Folders (relative to the project root) scanned for JSX. Defaults to "src". */
   include?: string[];
-  /** Fix individual translations by hand, e.g. { fr: { Contact: "Contact" } }. */
+  /** Fix individual translations in code, e.g. { fr: { Contact: "Contact" } }. Adds to (and wins over) react-autolocale.overrides.json. */
   overrides?: Record<string, Record<string, string>>;
   /**
    * Extra pages to build, mainly dynamic ones such as "/users/1" (a function can fetch them). Pages reached
    * by links and fixed routes written in your router (<Route path="/thank-you">) are found automatically.
    */
   routes?: string[] | (() => string[] | Promise<string[]>);
+  /**
+   * Replace the built-in free local model. Pass a function, or a ready-made engine such as `ollama({ model })`.
+   * Engines receive where each string appears (button, h1, ...) so they can translate short labels correctly.
+   */
+  engine?: Translator | TranslateFn;
+  /** Terms that must always translate a given way, e.g. { fr: { Roadmap: "Feuille de route" } }. */
+  glossary?: Record<string, Record<string, string>>;
 }
 export default function reactAutolocale(options?: ReactAutolocaleOptions): Plugin;
 //#endregion
-export { reactAutolocale };
+export { type TranslateFn, type Translator, reactAutolocale };