@verbaly/compiler 0.23.0 → 0.25.0

package/README.md

@@ -11,7 +11,7 @@
 
 ---
 
-The compiler behind [Verbaly](https://github.com/AronSoto/verbaly): AST extraction of `t\`...\``**and JSX`<Trans>` children** into stable hashed keys (or **readable keys** via `` t.id('inbox.title')`…` `` and `<Trans id="inbox.title">…</Trans>`), flat JSON catalog sync, and typed codegen. It also ships the **`verbaly` CLI**. Extraction covers `.js/.ts/.jsx/.tsx` **and `.svelte`/`.vue` single-file components** (script blocks and markup, including Svelte's `$t` store form).
+The compiler behind [Verbaly](https://github.com/AronSoto/verbaly): AST extraction of `t\`...\``**and JSX`<Trans>` children** into stable hashed keys (or **readable keys** via `` t.id('inbox.title')`…` `` and `<Trans id="inbox.title">…</Trans>`), flat JSON catalog sync, and typed codegen. It also ships the **`verbaly`CLI**. Extraction covers`.js/.ts/.jsx/.tsx`**and`.svelte`/`.vue`single-file components** (script blocks and markup, including Svelte's`$t` store form).
 
 > Most projects don't install this directly: [`@verbaly/vite`](https://www.npmjs.com/package/@verbaly/vite) wraps it with zero config. Reach for it when scripting extraction/checks yourself.
 
@@ -50,11 +50,11 @@ Catalogs are **flat JSON**: most TMS platforms (Crowdin, Lokalise, Phrase, …)
 
 ```bash
 npx verbaly export                    # verbaly-export/<locale>.xlf (XLIFF 2.0, source + target per unit)
-npx verbaly export --format csv       # spreadsheet-friendly: key,source,target
+npx verbaly export --format csv       # spreadsheet-friendly: key,source,target,location
 npx verbaly import verbaly-export/es.xlf   # fill the catalog back
 ```
 
-`export` writes one file per target locale with the source text alongside the current translation (`--missing` exports only the untranslated entries). `import` reads XLIFF 2.0/1.2 or CSV back and **validates every entry like `translate` does**: a translation that drops a `{param}`, a variant block or an `<em>` tag is rejected and reported, so a translator's typo can't break your UI. Existing translations are kept unless `--overwrite`; `--dry-run` previews everything.
+`export` writes one file per target locale with the source text alongside the current translation (`--missing` exports only the untranslated entries). Every entry carries **where the text lives in your source** (XLIFF `location` notes, a `location` column in CSV), so translators and TMS tools see the context instead of guessing it. `import` reads XLIFF 2.0/1.2 or CSV back and **validates every entry like `translate` does**: a translation that drops a `{param}`, a variant block or an `<em>` tag is rejected and reported, so a translator's typo can't break your UI. Existing translations are kept unless `--overwrite`; `--dry-run` previews everything.
 
 ## 📱 Mobile resources
 

package/dist/claude-C-ETlqsW.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-C-ETlqsW.js","names":[],"sources":["../src/providers/claude.ts"],"sourcesContent":["import { isModuleNotFound } from '../config';\nimport type { TranslateProvider, TranslateRequest } from '../translate';\n\nexport interface ClaudeProviderOptions {\n  model?: string;\n  apiKey?: string;\n  maxTokens?: number;\n}\n\n// balanced default for translation\nconst DEFAULT_MODEL = 'claude-sonnet-5';\n\nconst SYSTEM = `You translate UI strings for the Verbaly i18n library.\nRules:\n- Translate only the human-readable text, naturally for the target locale.\n- Preserve verbatim: placeholders like {name}, format specs like {price:currency/EUR}, variant blocks like {count | one: ... | other: # ...} (translate only the text inside each variant, keep keys and # as-is), ICU syntax, named tags like <em>...</em> and escapes {{ }} || ##.\n- Keys are opaque identifiers: return exactly the same keys, never translate or rename them.`;\n\nexport function claudeProvider(options: ClaudeProviderOptions = {}): TranslateProvider {\n  return async (request: TranslateRequest) => {\n    const Anthropic = await loadSdk();\n    const client = new Anthropic(options.apiKey ? { apiKey: options.apiKey } : {});\n    const response = await client.messages.create({\n      model: options.model ?? DEFAULT_MODEL,\n      max_tokens: options.maxTokens ?? 16000,\n      thinking: { type: 'disabled' },\n      system: SYSTEM,\n      messages: [{ role: 'user', content: buildPrompt(request) }],\n      output_config: { format: batchFormat(request) },\n    });\n    const text = response.content.find((block) => block.type === 'text')?.text ?? '{}';\n    return JSON.parse(text) as Record<string, string>;\n  };\n}\n\nexport function buildPrompt(request: TranslateRequest): string {\n  return (\n    `Translate each value from \"${request.sourceLocale}\" to \"${request.targetLocale}\". ` +\n    `Return a JSON object with the same keys and translated values.\\n\\n` +\n    JSON.stringify(request.messages, null, 2)\n  );\n}\n\nexport function batchFormat(request: TranslateRequest) {\n  const keys = Object.keys(request.messages);\n  return {\n    type: 'json_schema' as const,\n    schema: {\n      type: 'object',\n      properties: Object.fromEntries(keys.map((key) => [key, { type: 'string' }])),\n      required: keys,\n      additionalProperties: false,\n    },\n  };\n}\n\ntype SdkModule = { default: typeof import('@anthropic-ai/sdk').default };\n\n// injectable for tests\nexport async function loadSdk(\n  load: () => Promise<SdkModule> = () => import('@anthropic-ai/sdk'),\n): Promise<SdkModule['default']> {\n  try {\n    const mod = await load();\n    return mod.default;\n  } catch (error) {\n    if (isModuleNotFound(error, '@anthropic-ai/sdk')) {\n      throw new Error(\n        '[verbaly] the claude translate provider needs @anthropic-ai/sdk: install it as a dev dependency (e.g. `pnpm add -D @anthropic-ai/sdk` / `npm i -D @anthropic-ai/sdk`) and set ANTHROPIC_API_KEY',\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n\n"],"mappings":";;AAUA,MAAM,gBAAgB;AAEtB,MAAM,SAAS;;;;;AAMf,SAAgB,eAAe,UAAiC,CAAC,GAAsB;CACrF,OAAO,OAAO,YAA8B;EAW1C,MAAM,QAAO,MARU,KADJ,OADK,QAAQ,IACH,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC,CAChD,CAAC,CAAC,SAAS,OAAO;GAC5C,OAAO,QAAQ,SAAS;GACxB,YAAY,QAAQ,aAAa;GACjC,UAAU,EAAE,MAAM,WAAW;GAC7B,QAAQ;GACR,UAAU,CAAC;IAAE,MAAM;IAAQ,SAAS,YAAY,OAAO;GAAE,CAAC;GAC1D,eAAe,EAAE,QAAQ,YAAY,OAAO,EAAE;EAChD,CAAC,EAAA,CACqB,QAAQ,MAAM,UAAU,MAAM,SAAS,MAAM,CAAC,EAAE,QAAQ;EAC9E,OAAO,KAAK,MAAM,IAAI;CACxB;AACF;AAEA,SAAgB,YAAY,SAAmC;CAC7D,OACE,8BAA8B,QAAQ,aAAa,QAAQ,QAAQ,aAAa,yEAEhF,KAAK,UAAU,QAAQ,UAAU,MAAM,CAAC;AAE5C;AAEA,SAAgB,YAAY,SAA2B;CACrD,MAAM,OAAO,OAAO,KAAK,QAAQ,QAAQ;CACzC,OAAO;EACL,MAAM;EACN,QAAQ;GACN,MAAM;GACN,YAAY,OAAO,YAAY,KAAK,KAAK,QAAQ,CAAC,KAAK,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC;GAC3E,UAAU;GACV,sBAAsB;EACxB;CACF;AACF;AAKA,eAAsB,QACpB,aAAuC,OAAO,sBACf;CAC/B,IAAI;EAEF,QAAO,MADW,KAAK,EAAA,CACZ;CACb,SAAS,OAAO;EACd,IAAI,iBAAiB,OAAO,mBAAmB,GAC7C,MAAM,IAAI,MACR,mMACA,EAAE,OAAO,MAAM,CACjB;EAEF,MAAM;CACR;AACF"}
+{"version":3,"file":"claude-C-ETlqsW.js","names":[],"sources":["../src/providers/claude.ts"],"sourcesContent":["import { isModuleNotFound } from '../config';\nimport type { TranslateProvider, TranslateRequest } from '../translate';\n\nexport interface ClaudeProviderOptions {\n  model?: string;\n  apiKey?: string;\n  maxTokens?: number;\n}\n\n// balanced default for translation\nconst DEFAULT_MODEL = 'claude-sonnet-5';\n\nconst SYSTEM = `You translate UI strings for the Verbaly i18n library.\nRules:\n- Translate only the human-readable text, naturally for the target locale.\n- Preserve verbatim: placeholders like {name}, format specs like {price:currency/EUR}, variant blocks like {count | one: ... | other: # ...} (translate only the text inside each variant, keep keys and # as-is), ICU syntax, named tags like <em>...</em> and escapes {{ }} || ##.\n- Keys are opaque identifiers: return exactly the same keys, never translate or rename them.`;\n\nexport function claudeProvider(options: ClaudeProviderOptions = {}): TranslateProvider {\n  return async (request: TranslateRequest) => {\n    const Anthropic = await loadSdk();\n    const client = new Anthropic(options.apiKey ? { apiKey: options.apiKey } : {});\n    const response = await client.messages.create({\n      model: options.model ?? DEFAULT_MODEL,\n      max_tokens: options.maxTokens ?? 16000,\n      thinking: { type: 'disabled' },\n      system: SYSTEM,\n      messages: [{ role: 'user', content: buildPrompt(request) }],\n      output_config: { format: batchFormat(request) },\n    });\n    const text = response.content.find((block) => block.type === 'text')?.text ?? '{}';\n    return JSON.parse(text) as Record<string, string>;\n  };\n}\n\nexport function buildPrompt(request: TranslateRequest): string {\n  return (\n    `Translate each value from \"${request.sourceLocale}\" to \"${request.targetLocale}\". ` +\n    `Return a JSON object with the same keys and translated values.\\n\\n` +\n    JSON.stringify(request.messages, null, 2)\n  );\n}\n\nexport function batchFormat(request: TranslateRequest) {\n  const keys = Object.keys(request.messages);\n  return {\n    type: 'json_schema' as const,\n    schema: {\n      type: 'object',\n      properties: Object.fromEntries(keys.map((key) => [key, { type: 'string' }])),\n      required: keys,\n      additionalProperties: false,\n    },\n  };\n}\n\ntype SdkModule = { default: typeof import('@anthropic-ai/sdk').default };\n\n// injectable for tests\nexport async function loadSdk(\n  load: () => Promise<SdkModule> = () => import('@anthropic-ai/sdk'),\n): Promise<SdkModule['default']> {\n  try {\n    const mod = await load();\n    return mod.default;\n  } catch (error) {\n    if (isModuleNotFound(error, '@anthropic-ai/sdk')) {\n      throw new Error(\n        '[verbaly] the claude translate provider needs @anthropic-ai/sdk: install it as a dev dependency (e.g. `pnpm add -D @anthropic-ai/sdk` / `npm i -D @anthropic-ai/sdk`) and set ANTHROPIC_API_KEY',\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n"],"mappings":";;AAUA,MAAM,gBAAgB;AAEtB,MAAM,SAAS;;;;;AAMf,SAAgB,eAAe,UAAiC,CAAC,GAAsB;CACrF,OAAO,OAAO,YAA8B;EAW1C,MAAM,QAAO,MARU,KADJ,OADK,QAAQ,IACH,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC,CAChD,CAAC,CAAC,SAAS,OAAO;GAC5C,OAAO,QAAQ,SAAS;GACxB,YAAY,QAAQ,aAAa;GACjC,UAAU,EAAE,MAAM,WAAW;GAC7B,QAAQ;GACR,UAAU,CAAC;IAAE,MAAM;IAAQ,SAAS,YAAY,OAAO;GAAE,CAAC;GAC1D,eAAe,EAAE,QAAQ,YAAY,OAAO,EAAE;EAChD,CAAC,EAAA,CACqB,QAAQ,MAAM,UAAU,MAAM,SAAS,MAAM,CAAC,EAAE,QAAQ;EAC9E,OAAO,KAAK,MAAM,IAAI;CACxB;AACF;AAEA,SAAgB,YAAY,SAAmC;CAC7D,OACE,8BAA8B,QAAQ,aAAa,QAAQ,QAAQ,aAAa,yEAEhF,KAAK,UAAU,QAAQ,UAAU,MAAM,CAAC;AAE5C;AAEA,SAAgB,YAAY,SAA2B;CACrD,MAAM,OAAO,OAAO,KAAK,QAAQ,QAAQ;CACzC,OAAO;EACL,MAAM;EACN,QAAQ;GACN,MAAM;GACN,YAAY,OAAO,YAAY,KAAK,KAAK,QAAQ,CAAC,KAAK,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC;GAC3E,UAAU;GACV,sBAAsB;EACxB;CACF;AACF;AAKA,eAAsB,QACpB,aAAuC,OAAO,sBACf;CAC/B,IAAI;EAEF,QAAO,MADW,KAAK,EAAA,CACZ;CACb,SAAS,OAAO;EACd,IAAI,iBAAiB,OAAO,mBAAmB,GAC7C,MAAM,IAAI,MACR,mMACA,EAAE,OAAO,MAAM,CACjB;EAEF,MAAM;CACR;AACF"}

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, watch, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import { RICH_TAGS, createVerbaly, parse, parseTags, safeHref } from "verbaly";
+import { RICH_TAGS, createVerbaly, localeDirection, normalizeLink, parse, parseTags, safeAttribute } from "verbaly";
 import { pathToFileURL } from "node:url";
 import { glob } from "tinyglobby";
 import { parse as parse$1 } from "@babel/parser";
@@ -427,6 +427,15 @@ var MessageRegistry = class {
 		}
 		return out;
 	}
+	origins() {
+		const out = this.usedKeys();
+		for (const analysis of this.files.values()) for (const msg of analysis.tagged) {
+			const files = out.get(msg.key) ?? [];
+			if (!files.includes(msg.file)) files.push(msg.file);
+			out.set(msg.key, files);
+		}
+		return out;
+	}
 };
 //#endregion
 //#region src/key.ts
@@ -1128,7 +1137,8 @@ function exportCatalogs(cfg, catalogs, options = {}) {
 		const all = Object.keys(source).filter((key) => source[key]).sort().map((key) => ({
 			key,
 			source: source[key],
-			target: catalog[key] ?? ""
+			target: catalog[key] ?? "",
+			location: options.origins?.[key]
 		}));
 		const untranslated = all.filter((entry) => !entry.target);
 		const entries = options.missing ? untranslated : all;
@@ -1224,8 +1234,13 @@ function parseExchangeFile(file, localeOverride) {
 	throw new Error(`[verbaly] ${file}: unsupported format, expected .xlf, .xliff or .csv.`);
 }
 function toXliff(sourceLocale, locale, entries) {
-	const units = entries.map(({ key, source, target }) => [
+	const units = entries.map(({ key, source, target, location }) => [
 		`    <unit id="${escapeXml(key)}">`,
+		...location?.length ? [
+			"      <notes>",
+			...location.map((file) => `        <note category="location">${escapeXml(file)}</note>`),
+			"      </notes>"
+		] : [],
 		`      <segment state="${target ? "translated" : "initial"}">`,
 		`        <source>${escapeXml(source)}</source>`,
 		`        <target>${escapeXml(target)}</target>`,
@@ -1275,8 +1290,8 @@ function unescapeXml(text) {
 }
 function toCsv(entries) {
 	return [
-		"key,source,target",
-		...entries.map(({ key, source, target }) => `${csvField(key)},${csvField(source)},${csvField(target)}`),
+		"key,source,target,location",
+		...entries.map(({ key, source, target, location }) => `${csvField(key)},${csvField(source)},${csvField(target)},${csvField(location?.join("; ") ?? "")}`),
 		""
 	].join("\r\n");
 }
@@ -1378,6 +1393,7 @@ function renderHtml(html, options) {
 		const chunkStart = m.index + 1 + rawName.length;
 		if (tagName === "html" && options.setLang !== false) {
 			setAttribute(ms, html, chunkStart, openEnd, attrChunk, "lang", options.locale);
+			setAttribute(ms, html, chunkStart, openEnd, attrChunk, "dir", localeDirection(options.locale));
 			continue;
 		}
 		const attrs = parseAttrs(attrChunk);
@@ -1407,12 +1423,13 @@ function renderHtml(html, options) {
 		if (attrMapRaw !== void 0) {
 			const map = parseArgs$1(attrMapRaw);
 			if (map) for (const [name, attrKey] of Object.entries(map)) {
-				if (typeof attrKey !== "string" || name.toLowerCase().startsWith("on")) continue;
+				if (typeof attrKey !== "string") continue;
 				if (!v.has(attrKey)) {
 					missing.add(attrKey);
 					continue;
 				}
-				setAttribute(ms, html, chunkStart, openEnd, attrChunk, name, t(attrKey, args));
+				const value = safeAttribute(name, t(attrKey, args));
+				if (value !== void 0) setAttribute(ms, html, chunkStart, openEnd, attrChunk, name, value);
 			}
 		}
 	}
@@ -1574,10 +1591,8 @@ function richToHtml(nodes, allowed, links) {
 	let out = "";
 	for (const node of nodes) if (typeof node === "string") out += escapeHtml(node);
 	else if (links?.[node.name] !== void 0) {
-		const link = links[node.name];
-		const { href, target, rel } = typeof link === "string" ? { href: link } : link;
-		const safe = safeHref(href);
-		let attrs = safe !== void 0 ? ` href="${escapeAttr(safe)}"` : "";
+		const { href, target, rel } = normalizeLink(links[node.name]);
+		let attrs = href !== void 0 ? ` href="${escapeAttr(href)}"` : "";
 		if (target) attrs += ` target="${escapeAttr(target)}"`;
 		if (rel) attrs += ` rel="${escapeAttr(rel)}"`;
 		out += `<a${attrs}>${richToHtml(node.children, allowed, links)}</a>`;
@@ -1877,7 +1892,8 @@ async function runCli(args = process.argv.slice(2)) {
 			locales: values.locales?.split(","),
 			format,
 			out: values.out,
-			missing: values.missing
+			missing: values.missing,
+			origins: isMobileFormat(format) ? void 0 : await collectOrigins(cfg)
 		});
 		if (result.files.length === 0) {
 			console.log("[verbaly] no target locales to export (add locales to your config)");
@@ -1983,6 +1999,12 @@ function rejectStrayFlags(command, values) {
 	process.exitCode = 1;
 	return true;
 }
+async function collectOrigins(cfg) {
+	const registry = await extractProject(cfg);
+	const origins = {};
+	for (const [key, files] of registry.origins()) origins[key] = files.map((file) => relative(cfg.root, file).replaceAll("\\", "/"));
+	return origins;
+}
 async function resolveProvider(cfg, model) {
 	const configured = cfg.translate.provider;
 	if (typeof configured === "function") return configured;