@linguanahq/compiler 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@linguanahq/compiler",
+	"version": "0.1.0",
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"check-types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@babel/generator": "^7.28.5",
+		"@babel/parser": "^7.28.5",
+		"@babel/traverse": "^7.28.5",
+		"@babel/types": "^7.28.5",
+		"@linguanahq/catalog": "0.1.0"
+	},
+	"devDependencies": {
+		"@linguana/config": "0.0.0",
+		"@types/babel__generator": "^7.27.0",
+		"@types/babel__traverse": "^7.28.0",
+		"@types/bun": "^1.3.14",
+		"typescript": "^6",
+		"vite": "^8.1.3"
+	},
+	"peerDependencies": {
+		"vite": ">=7 <9"
+	}
+}

package/src/index.ts

@@ -0,0 +1,984 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+import generateImport from "@babel/generator";
+import { parse } from "@babel/parser";
+import traverseImport, { type NodePath } from "@babel/traverse";
+import * as t from "@babel/types";
+import {
+	contentHash,
+	type Diagnostic,
+	type Manifest,
+	type ManifestMessage,
+	manifestHash,
+	manifestSchema,
+	normalizeSource,
+	parseMessagePlaceholders,
+	SCHEMA_VERSION,
+	stableMessageId,
+} from "@linguanahq/catalog";
+import { createFilter, type Plugin } from "vite";
+
+const COMPILER_VERSION = "0.1.1";
+const generate =
+	(generateImport as unknown as { default?: typeof generateImport }).default ??
+	generateImport;
+const traverse =
+	(traverseImport as unknown as { default?: typeof traverseImport }).default ??
+	traverseImport;
+const EXCLUDED_ELEMENTS = new Set(["script", "style", "code", "pre"]);
+const ALLOWED_ATTRIBUTES = new Set([
+	"title",
+	"placeholder",
+	"aria-label",
+	"alt",
+	"label",
+	"value",
+]);
+const MACHINE_ATTRIBUTES = new Set([
+	"id",
+	"class",
+	"className",
+	"name",
+	"role",
+	"href",
+	"src",
+	"action",
+	"method",
+	"data-testid",
+	"data-test-id",
+	"data-analytics",
+	"data-event",
+]);
+
+export type StrictPolicy =
+	| boolean
+	| { ambiguous?: boolean; unsafe?: boolean; duplicate?: boolean };
+
+export type LinguanaPluginOptions = {
+	projectId: string;
+	environment: string;
+	sourceLocale: string;
+	apiUrl?: string;
+	token?: string;
+	include?: string | string[];
+	exclude?: string | string[];
+	output?: string;
+	upload?: boolean;
+	strict?: StrictPolicy;
+	translation?: {
+		targetLocales: string[];
+		maxChargeMicros: number;
+		waitTimeoutMs?: number;
+		publish: "development";
+	};
+};
+
+export type TransformResult = {
+	code: string;
+	map: ReturnType<typeof generate>["map"];
+	messages: ManifestMessage[];
+	diagnostics: Diagnostic[];
+};
+
+function jsxName(
+	node: t.JSXIdentifier | t.JSXMemberExpression | t.JSXNamespacedName,
+) {
+	if (t.isJSXIdentifier(node)) return node.name;
+	if (t.isJSXMemberExpression(node)) return jsxName(node.property);
+	return `${node.namespace.name}:${node.name.name}`;
+}
+
+function renderedJsxText(value: string): string {
+	const lines = value.replace(/\r\n?/g, "\n").split("\n");
+	let result = "";
+	for (let index = 0; index < lines.length; index += 1) {
+		let line = lines[index]?.replace(/\t/g, " ") ?? "";
+		if (index !== 0) line = line.replace(/^\s+/, "");
+		if (index !== lines.length - 1) line = line.replace(/\s+$/, "");
+		if (!line) continue;
+		if (result && !result.endsWith(" ")) result += " ";
+		result += line;
+	}
+	return result;
+}
+
+function location(path: NodePath, root: string, filename: string) {
+	const start = path.node.loc?.start;
+	return {
+		file: relative(root, filename).replaceAll("\\", "/"),
+		line: start?.line ?? 1,
+		column: start?.column ?? 0,
+	};
+}
+
+function getLiteralAttribute(
+	opening: t.JSXOpeningElement,
+	name: string,
+): string | undefined {
+	for (const attribute of opening.attributes) {
+		if (
+			t.isJSXAttribute(attribute) &&
+			t.isJSXIdentifier(attribute.name) &&
+			attribute.name.name === name &&
+			t.isStringLiteral(attribute.value)
+		) {
+			return attribute.value.value;
+		}
+	}
+	return undefined;
+}
+
+function hasAttribute(opening: t.JSXOpeningElement, name: string): boolean {
+	return opening.attributes.some(
+		(attribute) =>
+			t.isJSXAttribute(attribute) &&
+			t.isJSXIdentifier(attribute.name) &&
+			attribute.name.name === name,
+	);
+}
+
+function attributeValue(
+	opening: t.JSXOpeningElement,
+	name: string,
+): string | true | undefined {
+	for (const attribute of opening.attributes) {
+		if (
+			!t.isJSXAttribute(attribute) ||
+			!t.isJSXIdentifier(attribute.name, { name })
+		)
+			continue;
+		if (attribute.value === null) return true;
+		if (t.isStringLiteral(attribute.value)) return attribute.value.value;
+	}
+}
+
+function isUnsafeStaticCopy(source: string): boolean {
+	const normalized = normalizeSource(source);
+	return (
+		/^(?:https?:\/\/|mailto:|tel:|www\.)/i.test(normalized) ||
+		/^\/?[\w.-]+(?:\/[\w./-]+)+(?:\?\S*)?$/.test(normalized) ||
+		/^[a-z0-9]+(?:[_:.][a-z0-9-]+)+$/i.test(normalized)
+	);
+}
+
+function isExcluded(path: NodePath): boolean {
+	return Boolean(
+		path.findParent((parent) => {
+			if (!parent.isJSXElement()) return false;
+			const opening = parent.node.openingElement;
+			const tag = jsxName(opening.name);
+			return (
+				tag === "T" ||
+				EXCLUDED_ELEMENTS.has(tag.toLowerCase()) ||
+				hasAttribute(opening, "data-no-translate") ||
+				hasAttribute(opening, "hidden") ||
+				attributeValue(opening, "aria-hidden") === "true" ||
+				(tag.toLowerCase() === "input" &&
+					attributeValue(opening, "type") === "hidden")
+			);
+		}),
+	);
+}
+
+function isExcludedElement(opening: t.JSXOpeningElement): boolean {
+	const tag = jsxName(opening.name);
+	return (
+		EXCLUDED_ELEMENTS.has(tag.toLowerCase()) ||
+		hasAttribute(opening, "data-no-translate") ||
+		hasAttribute(opening, "hidden") ||
+		attributeValue(opening, "aria-hidden") === "true" ||
+		(tag.toLowerCase() === "input" &&
+			attributeValue(opening, "type") === "hidden")
+	);
+}
+
+function hasMixedRichChildren(path: NodePath): boolean {
+	return Boolean(
+		path.findParent((parent) => {
+			if (!parent.isJSXElement()) return false;
+			const children = parent.node.children;
+			const hasElement = children.some(
+				(child) =>
+					t.isJSXElement(child) ||
+					(t.isJSXExpressionContainer(child) &&
+						!t.isJSXEmptyExpression(child.expression)),
+			);
+			const hasText = children.some(
+				(child) => t.isJSXText(child) && Boolean(renderedJsxText(child.value)),
+			);
+			return hasElement && hasText;
+		}),
+	);
+}
+
+function placeholders(source: string) {
+	try {
+		return parseMessagePlaceholders(source);
+	} catch {
+		return [];
+	}
+}
+
+function stringProperty(
+	object: t.ObjectExpression,
+	name: string,
+): string | undefined {
+	for (const property of object.properties) {
+		if (!t.isObjectProperty(property)) continue;
+		const key = t.isIdentifier(property.key)
+			? property.key.name
+			: t.isStringLiteral(property.key)
+				? property.key.value
+				: undefined;
+		if (key === name && t.isStringLiteral(property.value))
+			return property.value.value;
+	}
+	return undefined;
+}
+
+function isTranslationCall(
+	path: NodePath<t.CallExpression>,
+	runtimePackage = "@linguanahq/react",
+) {
+	if (!t.isIdentifier(path.node.callee)) return false;
+	const name = path.node.callee.name;
+	const binding = path.scope.getBinding(name);
+	if (!binding) return false;
+	if (binding.path.isImportSpecifier()) {
+		const declaration = binding.path.parentPath;
+		return (
+			declaration.isImportDeclaration() &&
+			declaration.node.source.value === runtimePackage &&
+			t.isIdentifier(binding.path.node.imported, { name: "t" })
+		);
+	}
+	const declarator = binding.path.isVariableDeclarator()
+		? binding.path
+		: binding.path.findParent((candidate) => candidate.isVariableDeclarator());
+	if (!declarator?.isVariableDeclarator()) return false;
+	if (
+		!t.isCallExpression(declarator.node.init) ||
+		!t.isIdentifier(declarator.node.init.callee, { name: "useTranslation" }) ||
+		!t.isObjectPattern(declarator.node.id)
+	)
+		return false;
+	return declarator.node.id.properties.some(
+		(property) =>
+			t.isObjectProperty(property) &&
+			t.isIdentifier(property.key, { name: "t" }) &&
+			t.isIdentifier(property.value, { name }),
+	);
+}
+
+export function transformSource(
+	code: string,
+	filename: string,
+	options: Pick<LinguanaPluginOptions, "sourceLocale"> & {
+		root?: string;
+		runtimePackage?: string;
+		compilerRuntime?: string;
+	},
+): TransformResult {
+	const root = options.root ?? process.cwd();
+	const ast = parse(code, {
+		sourceType: "module",
+		sourceFilename: filename,
+		plugins: ["jsx", "typescript"],
+	});
+	const messages = new Map<string, ManifestMessage>();
+	const diagnostics: Diagnostic[] = [];
+	let needsRuntime = false;
+	const richDiagnosticLocations = new Set<string>();
+
+	const addMessage = (message: ManifestMessage) => {
+		const existing = messages.get(message.id);
+		if (existing && existing.contentHash !== message.contentHash) {
+			diagnostics.push({
+				code: "duplicate-id",
+				severity: "error",
+				message: `Message ID ${message.id} refers to incompatible source content`,
+				location: message.locations[0],
+				remediation:
+					"Choose a unique explicit ID or make the source messages identical.",
+			});
+			return;
+		}
+		if (existing) {
+			existing.locations.push(...message.locations);
+			return;
+		}
+		messages.set(message.id, message);
+	};
+
+	traverse(ast, {
+		JSXText(path) {
+			const source = renderedJsxText(path.node.value);
+			if (!source || isExcluded(path)) return;
+			if (isUnsafeStaticCopy(source)) {
+				diagnostics.push({
+					code: "unsafe-static-copy",
+					severity: "info",
+					message:
+						"URL-like or machine-readable text was excluded from extraction.",
+					location: location(path, root, filename),
+				});
+				return;
+			}
+			if (hasMixedRichChildren(path)) {
+				const itemLocation = location(path, root, filename);
+				const key = `${itemLocation.file}:${itemLocation.line}:${itemLocation.column}`;
+				if (!richDiagnosticLocations.has(key)) {
+					richDiagnosticLocations.add(key);
+					diagnostics.push({
+						code: "ambiguous-rich-text",
+						severity: "warning",
+						message:
+							"Mixed text and JSX elements require an explicit <T> message.",
+						location: itemLocation,
+						remediation:
+							"Use <T defaultMessage components> or data-no-translate.",
+					});
+				}
+				return;
+			}
+			const parent = path.findParent((candidate) => candidate.isJSXElement());
+			if (!parent?.isJSXElement()) return;
+			const element = jsxName(parent.node.openingElement.name);
+			const context = { kind: "text" as const, element };
+			const id = stableMessageId({
+				sourceLocale: options.sourceLocale,
+				source,
+				context,
+			});
+			addMessage({
+				id,
+				source,
+				normalized: normalizeSource(source),
+				contentHash: contentHash(source),
+				context,
+				placeholders: placeholders(source),
+				confidence: "high",
+				locations: [location(path, root, filename)],
+			});
+			needsRuntime = true;
+			path.replaceWith(
+				t.jsxExpressionContainer(
+					t.jsxElement(
+						t.jsxOpeningElement(
+							t.jsxIdentifier("__LinguanaMessage"),
+							[
+								t.jsxAttribute(t.jsxIdentifier("id"), t.stringLiteral(id)),
+								t.jsxAttribute(
+									t.jsxIdentifier("defaultMessage"),
+									t.stringLiteral(source),
+								),
+							],
+							true,
+						),
+						null,
+						[],
+						true,
+					),
+				),
+			);
+		},
+		JSXExpressionContainer(path) {
+			if (
+				isExcluded(path) ||
+				t.isJSXEmptyExpression(path.node.expression) ||
+				!path.parentPath.isJSXElement()
+			)
+				return;
+			if (
+				t.isConditionalExpression(path.node.expression) ||
+				t.isBinaryExpression(path.node.expression) ||
+				t.isTemplateLiteral(path.node.expression)
+			) {
+				diagnostics.push({
+					code: "dynamic-candidate",
+					severity: "warning",
+					message: "Dynamic JSX copy was not automatically extracted.",
+					location: location(path, root, filename),
+					remediation:
+						"Use t(), <T>, data-no-translate, or an explicit annotation.",
+				});
+			}
+		},
+		CallExpression(path) {
+			if (!isTranslationCall(path, options.runtimePackage)) return;
+			const [sourceNode, , optionsNode] = path.node.arguments;
+			if (!t.isStringLiteral(sourceNode)) return;
+			const explicitId = t.isObjectExpression(optionsNode)
+				? stringProperty(optionsNode, "id")
+				: undefined;
+			const developer = t.isObjectExpression(optionsNode)
+				? stringProperty(optionsNode, "context")
+				: undefined;
+			const context = { kind: "explicit" as const, developer };
+			const id = stableMessageId({
+				sourceLocale: options.sourceLocale,
+				source: sourceNode.value,
+				context,
+				explicitId,
+			});
+			addMessage({
+				id,
+				source: sourceNode.value,
+				normalized: normalizeSource(sourceNode.value),
+				contentHash: contentHash(sourceNode.value),
+				context,
+				placeholders: placeholders(sourceNode.value),
+				confidence: "explicit",
+				locations: [location(path, root, filename)],
+			});
+		},
+		JSXElement: {
+			exit(path) {
+				if (isExcluded(path) || isExcludedElement(path.node.openingElement))
+					return;
+				const opening = path.node.openingElement;
+				const tag = jsxName(opening.name);
+				if (tag === "T") {
+					const source = getLiteralAttribute(opening, "defaultMessage");
+					if (!source) return;
+					const explicitId = getLiteralAttribute(opening, "id");
+					const developer = getLiteralAttribute(opening, "context");
+					const context = { kind: "explicit" as const, developer };
+					const id = stableMessageId({
+						sourceLocale: options.sourceLocale,
+						source,
+						context,
+						explicitId,
+					});
+					addMessage({
+						id,
+						source,
+						normalized: normalizeSource(source),
+						contentHash: contentHash(source),
+						context,
+						placeholders: placeholders(source),
+						confidence: "explicit",
+						locations: [location(path, root, filename)],
+					});
+					return;
+				}
+
+				const descriptors: t.ObjectExpression[] = [];
+				const localizedNames: string[] = [];
+				for (const attribute of opening.attributes) {
+					if (
+						!t.isJSXAttribute(attribute) ||
+						!t.isJSXIdentifier(attribute.name) ||
+						!t.isStringLiteral(attribute.value)
+					)
+						continue;
+					const name = attribute.name.name;
+					if (
+						MACHINE_ATTRIBUTES.has(name) ||
+						name.startsWith("on") ||
+						name === "data-translate"
+					)
+						continue;
+					const optInValue = attributeValue(opening, "data-translate");
+					const optedIn =
+						typeof optInValue === "string" &&
+						optInValue.split(/[\s,]+/).includes(name);
+					if (!ALLOWED_ATTRIBUTES.has(name) && !optedIn) continue;
+					if (name === "value" && tag.toLowerCase() !== "button") continue;
+					const source = attribute.value.value;
+					if (!source || isUnsafeStaticCopy(source)) continue;
+					const context = {
+						kind: "attribute" as const,
+						element: tag,
+						attribute: name,
+					};
+					const id = stableMessageId({
+						sourceLocale: options.sourceLocale,
+						source,
+						context,
+					});
+					addMessage({
+						id,
+						source,
+						normalized: normalizeSource(source),
+						contentHash: contentHash(source),
+						context,
+						placeholders: placeholders(source),
+						confidence: "high",
+						locations: [location(path, root, filename)],
+					});
+					localizedNames.push(name);
+					descriptors.push(
+						t.objectExpression([
+							t.objectProperty(t.identifier("name"), t.stringLiteral(name)),
+							t.objectProperty(t.identifier("id"), t.stringLiteral(id)),
+							t.objectProperty(
+								t.identifier("defaultMessage"),
+								t.stringLiteral(source),
+							),
+						]),
+					);
+				}
+				if (!descriptors.length) return;
+				needsRuntime = true;
+				const original = t.cloneNode(path.node, true);
+				for (const attribute of original.openingElement.attributes) {
+					if (
+						t.isJSXAttribute(attribute) &&
+						t.isJSXIdentifier(attribute.name) &&
+						localizedNames.includes(attribute.name.name)
+					) {
+						attribute.value = t.jsxExpressionContainer(
+							t.memberExpression(
+								t.identifier("__localized"),
+								t.stringLiteral(attribute.name.name),
+								true,
+							),
+						);
+					}
+				}
+				const wrapper = t.jsxElement(
+					t.jsxOpeningElement(
+						t.jsxIdentifier("__LinguanaAttributes"),
+						[
+							t.jsxAttribute(
+								t.jsxIdentifier("descriptors"),
+								t.jsxExpressionContainer(t.arrayExpression(descriptors)),
+							),
+						],
+						false,
+					),
+					t.jsxClosingElement(t.jsxIdentifier("__LinguanaAttributes")),
+					[
+						t.jsxExpressionContainer(
+							t.arrowFunctionExpression(
+								[t.identifier("__localized")],
+								original,
+							),
+						),
+					],
+				);
+				path.replaceWith(wrapper);
+				path.skip();
+			},
+		},
+		Program: {
+			exit(path) {
+				if (!needsRuntime) return;
+				path.unshiftContainer(
+					"body",
+					t.importDeclaration(
+						[
+							t.importSpecifier(
+								t.identifier("__LinguanaMessage"),
+								t.identifier("LinguanaMessage"),
+							),
+							t.importSpecifier(
+								t.identifier("__LinguanaAttributes"),
+								t.identifier("LinguanaAttributes"),
+							),
+						],
+						t.stringLiteral(
+							options.compilerRuntime ?? "@linguanahq/react/compiler-runtime",
+						),
+					),
+				);
+			},
+		},
+	});
+
+	const output = generate(
+		ast,
+		{ sourceMaps: true, sourceFileName: filename },
+		code,
+	);
+	return {
+		code: output.code,
+		map: output.map,
+		messages: [...messages.values()].sort((left, right) =>
+			left.id.localeCompare(right.id),
+		),
+		diagnostics,
+	};
+}
+
+function shouldFail(
+	strict: StrictPolicy | undefined,
+	diagnostics: Diagnostic[],
+) {
+	if (!strict) return false;
+	if (strict === true)
+		return diagnostics.some((item) => item.severity !== "info");
+	return diagnostics.some((item) => {
+		if (item.code === "duplicate-id") return strict.duplicate ?? true;
+		if (item.code.startsWith("unsafe")) return strict.unsafe ?? false;
+		return strict.ambiguous ?? false;
+	});
+}
+
+async function uploadManifest(
+	options: LinguanaPluginOptions,
+	manifest: Manifest,
+	hash: string,
+) {
+	if (!options.apiUrl || !options.token) {
+		throw new Error("Manifest upload requires apiUrl and token");
+	}
+	const body = JSON.stringify(manifest);
+	const response = await fetch(
+		`${options.apiUrl.replace(/\/$/, "")}/api/v1/manifests`,
+		{
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${options.token}`,
+				"idempotency-key": hash,
+			},
+			body: JSON.stringify({
+				schemaVersion: SCHEMA_VERSION,
+				contentHash: hash,
+				byteLength: new TextEncoder().encode(body).byteLength,
+				messageCount: manifest.messages.length,
+				sourceRevision: manifest.sourceRevision,
+			}),
+		},
+	);
+	if (!response.ok)
+		throw new Error(`Manifest registration failed (${response.status})`);
+	const registration = (await response.json()) as {
+		manifestId: string;
+		status: string;
+		upload?: { url: string; headers: Record<string, string> };
+	};
+	if (registration.upload) {
+		const upload = await fetch(registration.upload.url, {
+			method: "PUT",
+			headers: registration.upload.headers,
+			body,
+		});
+		if (!upload.ok)
+			throw new Error(`Manifest artifact upload failed (${upload.status})`);
+		const completion = await fetch(
+			`${options.apiUrl.replace(/\/$/, "")}/api/v1/manifests/${registration.manifestId}/complete`,
+			{
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${options.token}`,
+					"idempotency-key": `${hash}:complete`,
+				},
+			},
+		);
+		if (!completion.ok)
+			throw new Error(`Manifest completion failed (${completion.status})`);
+	}
+	return registration;
+}
+
+type ApiFailure = {
+	code?: string;
+	message?: string;
+	requestId?: string;
+};
+
+async function apiJson<T>(url: string, init: RequestInit): Promise<T> {
+	const response = await fetch(url, init);
+	const body = (await response.json().catch(() => ({}))) as T & ApiFailure;
+	if (!response.ok) {
+		const details = [
+			body.code ?? `HTTP_${response.status}`,
+			body.message,
+			body.requestId ? `request ${body.requestId}` : undefined,
+		].filter(Boolean);
+		throw new Error(details.join(": "));
+	}
+	return body;
+}
+
+type BuildJob = {
+	id: string;
+	targetLocale: string;
+	status: string;
+	dispatchStatus: string;
+	errorCode?: string | null;
+	catalogVersionId?: string | null;
+};
+
+async function translateManifest(
+	options: LinguanaPluginOptions,
+	manifestId: string,
+	hash: string,
+	onProgress: (message: string) => void,
+) {
+	const translation = options.translation;
+	if (!translation || !options.apiUrl || !options.token) return;
+	const endpoint = options.apiUrl.replace(/\/$/, "");
+	const buildKey = contentHash({
+		manifestHash: hash,
+		targetLocales: [...translation.targetLocales].sort(),
+		publish: translation.publish,
+	});
+	onProgress(
+		`Requesting ${translation.targetLocales.join(", ")} translations for manifest ${hash.slice(0, 12)}.`,
+	);
+	const created = await apiJson<{
+		requestId: string;
+		maximumChargeMicros: number;
+		jobs: BuildJob[];
+	}>(`${endpoint}/api/v1/manifests/${manifestId}/translations`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${options.token}`,
+			"content-type": "application/json",
+			"idempotency-key": buildKey,
+		},
+		body: JSON.stringify({
+			targetLocales: translation.targetLocales,
+			maxChargeMicros: translation.maxChargeMicros,
+		}),
+	});
+	onProgress(
+		`Translation jobs accepted (maximum charge ${created.maximumChargeMicros} micros).`,
+	);
+	const deadline = Date.now() + (translation.waitTimeoutMs ?? 300_000);
+	const completed = new Map<string, BuildJob>();
+	while (completed.size < created.jobs.length && Date.now() < deadline) {
+		for (const initial of created.jobs) {
+			if (completed.has(initial.id)) continue;
+			const job = await apiJson<BuildJob>(
+				`${endpoint}/api/v1/jobs/${initial.id}`,
+				{
+					method: "GET",
+					headers: { authorization: `Bearer ${options.token}` },
+				},
+			);
+			if (
+				job.dispatchStatus === "FAILED" &&
+				!["SUCCEEDED", "REVIEW_REQUIRED", "FAILED", "CANCELED"].includes(
+					job.status,
+				)
+			) {
+				throw new Error(
+					`${job.targetLocale}: ${job.errorCode ?? "INNGEST_DISPATCH_FAILED"}: job ${job.id}. Start or reconnect the Inngest worker.`,
+				);
+			}
+			if (job.status === "SUCCEEDED") {
+				if (!job.catalogVersionId)
+					throw new Error(
+						`${job.targetLocale}: CATALOG_VERSION_MISSING: job ${job.id}.`,
+					);
+				completed.set(job.id, job);
+				onProgress(`${job.targetLocale} translation completed.`);
+			} else if (
+				["REVIEW_REQUIRED", "FAILED", "CANCELED"].includes(job.status)
+			) {
+				throw new Error(
+					`${job.targetLocale}: ${job.errorCode ?? job.status}: job ${job.id}. Inspect the translation job in the dashboard.`,
+				);
+			}
+		}
+		const remainingMs = deadline - Date.now();
+		if (completed.size < created.jobs.length && remainingMs > 0)
+			await new Promise((resolve) =>
+				setTimeout(resolve, Math.min(1_000, remainingMs)),
+			);
+	}
+	if (completed.size !== created.jobs.length) {
+		const pending = created.jobs
+			.filter((job) => !completed.has(job.id))
+			.map((job) => `${job.targetLocale} (${job.id})`)
+			.join(", ");
+		throw new Error(
+			`TRANSLATION_BUILD_TIMEOUT: ${pending} did not finish within ${translation.waitTimeoutMs ?? 300_000}ms.`,
+		);
+	}
+	await apiJson(
+		`${endpoint}/api/v1/manifests/${manifestId}/development-release`,
+		{
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${options.token}`,
+				"content-type": "application/json",
+				"idempotency-key": `${buildKey}:release:${contentHash(
+					created.jobs.map(({ id }) => id).sort(),
+				).slice(0, 16)}`,
+			},
+			body: JSON.stringify({
+				catalogVersionIds: [...completed.values()].map(
+					(job) => job.catalogVersionId,
+				),
+			}),
+		},
+	);
+	onProgress("Published the translated development catalog.");
+}
+
+function validatePluginOptions(options: LinguanaPluginOptions) {
+	const translation = options.translation;
+	if (!translation) return;
+	if (!options.apiUrl || !options.token)
+		throw new Error(
+			"Linguana translation requires both apiUrl and a project token.",
+		);
+	if (options.environment !== "development")
+		throw new Error(
+			"Linguana build-driven publication is restricted to the development environment.",
+		);
+	if (
+		!Number.isSafeInteger(translation.maxChargeMicros) ||
+		translation.maxChargeMicros <= 0
+	)
+		throw new Error(
+			"Linguana translation maxChargeMicros must be a positive safe integer.",
+		);
+	if (
+		translation.waitTimeoutMs !== undefined &&
+		(!Number.isSafeInteger(translation.waitTimeoutMs) ||
+			translation.waitTimeoutMs <= 0)
+	)
+		throw new Error(
+			"Linguana translation waitTimeoutMs must be a positive safe integer.",
+		);
+	if (translation.targetLocales.length === 0)
+		throw new Error(
+			"Linguana translation requires at least one target locale.",
+		);
+	if (
+		new Set(translation.targetLocales).size !== translation.targetLocales.length
+	)
+		throw new Error("Linguana translation target locales must be unique.");
+	if (translation.targetLocales.includes(options.sourceLocale))
+		throw new Error(
+			"Linguana translation target locales must differ from the source locale.",
+		);
+}
+
+export function linguana(options: LinguanaPluginOptions): Plugin {
+	validatePluginOptions(options);
+	const filter = createFilter(
+		options.include ?? ["**/*.jsx", "**/*.tsx"],
+		options.exclude ?? ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
+	);
+	const collected = new Map<string, ManifestMessage>();
+	const diagnostics: Diagnostic[] = [];
+	const diagnosticKeys = new Set<string>();
+	const buildRuns = new Map<string, Promise<void>>();
+	const restrictToRoot = options.include === undefined;
+	let root = process.cwd();
+
+	return {
+		name: "linguana",
+		enforce: "pre",
+		buildStart() {
+			this.warn(
+				"@linguanahq/compiler is deprecated; migrate to @linguanahq/vite with @linguanahq/vite/react.",
+			);
+		},
+		configResolved(config) {
+			root = config.root;
+		},
+		transform(code, id) {
+			const cleanId = id.split("?", 1)[0] ?? id;
+			const projectRelativeId = relative(root, cleanId);
+			if (
+				restrictToRoot &&
+				(projectRelativeId === ".." ||
+					projectRelativeId.startsWith("../") ||
+					projectRelativeId.startsWith("..\\") ||
+					isAbsolute(projectRelativeId))
+			)
+				return null;
+			if (!filter(cleanId)) return null;
+			const result = transformSource(code, cleanId, {
+				sourceLocale: options.sourceLocale,
+				root,
+			});
+			for (const message of result.messages) {
+				const existing = collected.get(message.id);
+				if (existing && existing.contentHash === message.contentHash) {
+					for (const item of message.locations) {
+						const key = `${item.file}:${item.line}:${item.column}`;
+						if (
+							!existing.locations.some(
+								(candidate) =>
+									`${candidate.file}:${candidate.line}:${candidate.column}` ===
+									key,
+							)
+						) {
+							existing.locations.push(item);
+						}
+					}
+				} else if (existing) {
+					const item = message.locations[0];
+					const key = `duplicate-id:${item?.file ?? ""}:${item?.line ?? 0}:${item?.column ?? 0}`;
+					if (!diagnosticKeys.has(key)) {
+						diagnosticKeys.add(key);
+						diagnostics.push({
+							code: "duplicate-id",
+							severity: "error",
+							message: `Message ID ${message.id} refers to incompatible source content across modules.`,
+							location: item,
+							remediation:
+								"Choose a unique explicit ID or make the source messages identical.",
+						});
+					}
+				} else {
+					collected.set(message.id, message);
+				}
+			}
+			for (const diagnostic of result.diagnostics) {
+				const item = diagnostic.location;
+				const key = `${diagnostic.code}:${item?.file ?? ""}:${item?.line ?? 0}:${item?.column ?? 0}`;
+				if (!diagnosticKeys.has(key)) {
+					diagnosticKeys.add(key);
+					diagnostics.push(diagnostic);
+				}
+			}
+			return { code: result.code, map: result.map };
+		},
+		async writeBundle() {
+			const manifest = manifestSchema.parse({
+				schemaVersion: SCHEMA_VERSION,
+				compilerVersion: COMPILER_VERSION,
+				projectId: options.projectId,
+				environment: options.environment,
+				sourceLocale: options.sourceLocale,
+				sourceRevision: process.env.GIT_COMMIT_SHA,
+				messages: [...collected.values()].sort((left, right) =>
+					left.id.localeCompare(right.id),
+				),
+				diagnostics,
+			});
+			const output = resolve(root, options.output ?? ".linguana/manifest.json");
+			await mkdir(dirname(output), { recursive: true });
+			await writeFile(output, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+			for (const item of diagnostics) {
+				const method = item.severity === "error" ? "error" : "warn";
+				this[method](`${item.code}: ${item.message}`);
+			}
+			if (shouldFail(options.strict, diagnostics)) {
+				this.error("Linguana strict policy rejected compiler diagnostics.");
+			}
+			if (options.upload || options.translation) {
+				const hash = manifestHash(manifest);
+				let buildRun = buildRuns.get(hash);
+				if (!buildRun) {
+					buildRun = (async () => {
+						const registration = await uploadManifest(options, manifest, hash);
+						if (options.translation)
+							await translateManifest(
+								options,
+								registration.manifestId,
+								hash,
+								(message) => this.info(`[linguana] ${message}`),
+							);
+					})();
+					buildRuns.set(hash, buildRun);
+				}
+				await buildRun;
+			}
+		},
+	};
+}
+
+export default linguana;