@vertana/core 0.1.0-dev.1

package/dist/evaluation.d.ts

@@ -0,0 +1,111 @@
+import { Glossary } from "./glossary.js";
+import { LanguageModel } from "ai";
+
+//#region src/evaluation.d.ts
+
+/**
+ * Options for {@link TranslationEvaluator}.
+ */
+interface EvaluatorOptions {
+  /**
+   * An optional `AbortSignal` to cancel the evaluation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Options for the {@link evaluate} function.
+ */
+interface EvaluateOptions {
+  /**
+   * The target language of the translation.
+   */
+  readonly targetLanguage: Intl.Locale | string;
+  /**
+   * The source language of the original text.
+   */
+  readonly sourceLanguage?: Intl.Locale | string;
+  /**
+   * A glossary of terms that should be used consistently.
+   */
+  readonly glossary?: Glossary;
+  /**
+   * An optional `AbortSignal` to cancel the evaluation.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Evaluates the quality of a translation.
+ *
+ * @param original The original text that was translated.
+ * @param translated The translated text to evaluate.
+ * @param options Optional settings for the evaluation.
+ * @returns A promise that resolves to the evaluation result.
+ */
+type TranslationEvaluator = (original: string, translated: string, options?: EvaluatorOptions) => Promise<EvaluationResult>;
+/**
+ * The result of evaluating a translation.
+ */
+interface EvaluationResult {
+  /**
+   * A quality score between 0 and 1, where 1 indicates a perfect translation
+   * and 0 indicates a completely incorrect translation.
+   */
+  readonly score: number;
+  /**
+   * Specific issues found in the translation.
+   */
+  readonly issues: readonly TranslationIssue[];
+}
+/**
+ * The type of issue found in a translation.
+ *
+ * - `"accuracy"`: The translation does not accurately convey the meaning
+ *   of the original text.
+ * - `"fluency"`: The translation is not natural or readable in the target
+ *   language.
+ * - `"terminology"`: Incorrect or inconsistent use of domain-specific terms.
+ * - `"style"`: The translation does not match the desired tone or style.
+ */
+type TranslationIssueType = "accuracy" | "fluency" | "terminology" | "style";
+/**
+ * A specific issue found in a translation.
+ */
+interface TranslationIssue {
+  /**
+   * The type of issue.
+   */
+  readonly type: TranslationIssueType;
+  /**
+   * A human-readable description of the issue.
+   */
+  readonly description: string;
+  /**
+   * The location of the issue in the translated text, if applicable.
+   */
+  readonly location?: TranslationIssueLocation;
+}
+/**
+ * The location of a translation issue within the translated text.
+ */
+interface TranslationIssueLocation {
+  /**
+   * The starting character index (0-based, inclusive).
+   */
+  readonly start: number;
+  /**
+   * The ending character index (0-based, exclusive).
+   */
+  readonly end: number;
+}
+/**
+ * Evaluates the quality of a translation using an LLM.
+ *
+ * @param model The language model to use for evaluation.
+ * @param original The original text that was translated.
+ * @param translated The translated text to evaluate.
+ * @param options Evaluation options including target language.
+ * @returns A promise that resolves to the evaluation result.
+ */
+declare function evaluate(model: LanguageModel, original: string, translated: string, options: EvaluateOptions): Promise<EvaluationResult>;
+//#endregion
+export { EvaluateOptions, EvaluationResult, EvaluatorOptions, TranslationEvaluator, TranslationIssue, TranslationIssueLocation, TranslationIssueType, evaluate };

package/dist/evaluation.js

@@ -0,0 +1,119 @@
+import { getLogger } from "@logtape/logtape";
+import { generateObject } from "ai";
+import { z } from "zod";
+
+//#region src/evaluation.ts
+const logger = getLogger([
+	"vertana",
+	"core",
+	"evaluate"
+]);
+const issueTypeSchema = z.enum([
+	"accuracy",
+	"fluency",
+	"terminology",
+	"style"
+]);
+const issueSchema = z.object({
+	type: issueTypeSchema,
+	description: z.string(),
+	location: z.object({
+		start: z.number(),
+		end: z.number()
+	}).optional()
+});
+const evaluationResultSchema = z.object({
+	score: z.number().min(0).max(1),
+	issues: z.array(issueSchema)
+});
+/**
+* Gets the language name from a locale.
+*/
+function getLanguageName(locale) {
+	const tag = typeof locale === "string" ? locale : locale.baseName;
+	try {
+		return new Intl.DisplayNames(["en"], { type: "language" }).of(tag) ?? tag;
+	} catch {
+		return tag;
+	}
+}
+/**
+* Builds the system prompt for evaluation.
+*/
+function buildEvaluationSystemPrompt(options) {
+	const targetLang = getLanguageName(options.targetLanguage);
+	let prompt = `You are an expert translation quality evaluator.
+
+Your task is to evaluate the quality of a translation from ${(options.sourceLanguage ? getLanguageName(options.sourceLanguage) : null) ?? "the source language"} to ${targetLang}.
+
+Evaluate the translation based on these criteria:
+
+1. **Accuracy**: Does the translation accurately convey the meaning of the original text?
+2. **Fluency**: Is the translation natural and readable in ${targetLang}?
+3. **Terminology**: Are domain-specific terms translated correctly and consistently?
+4. **Style**: Does the translation maintain the appropriate tone and style?
+
+Provide:
+- A score from 0 to 1 (where 1 is perfect, 0.9+ is excellent, 0.7-0.9 is good, 0.5-0.7 is acceptable, below 0.5 is poor)
+- A list of specific issues found, if any
+
+Be strict but fair in your evaluation. Minor issues should result in small deductions, while major meaning errors should significantly lower the score.`;
+	if (options.glossary != null && options.glossary.length > 0) {
+		prompt += `\n\n## Glossary
+
+The following terms MUST be translated as specified. Violations should be marked as "terminology" issues:
+
+`;
+		for (const entry of options.glossary) prompt += `- "${entry.original}" → "${entry.translated}"\n`;
+	}
+	return prompt;
+}
+/**
+* Builds the user prompt for evaluation.
+*/
+function buildEvaluationUserPrompt(original, translated) {
+	return `## Original Text
+
+${original}
+
+## Translated Text
+
+${translated}
+
+Please evaluate this translation.`;
+}
+/**
+* Evaluates the quality of a translation using an LLM.
+*
+* @param model The language model to use for evaluation.
+* @param original The original text that was translated.
+* @param translated The translated text to evaluate.
+* @param options Evaluation options including target language.
+* @returns A promise that resolves to the evaluation result.
+*/
+async function evaluate(model, original, translated, options) {
+	logger.debug("Evaluating translation quality...");
+	const result = await generateObject({
+		model,
+		schema: evaluationResultSchema,
+		system: buildEvaluationSystemPrompt(options),
+		prompt: buildEvaluationUserPrompt(original, translated),
+		abortSignal: options.signal
+	});
+	const issues = result.object.issues.map((issue) => ({
+		type: issue.type,
+		description: issue.description,
+		location: issue.location
+	}));
+	logger.debug("Evaluation result: score {score}, {issueCount} issue(s).", {
+		score: result.object.score,
+		issueCount: issues.length
+	});
+	return {
+		score: result.object.score,
+		issues
+	};
+}
+
+//#endregion
+export { evaluate };

package/dist/glossary.d.cts

@@ -0,0 +1,25 @@
+//#region src/glossary.d.ts
+/**
+ * A glossary of terms for consistent translation.
+ */
+type Glossary = readonly GlossaryEntry[];
+/**
+ * An entry in a {@link Glossary}.
+ */
+interface GlossaryEntry {
+  /**
+   * The original term in the source language.
+   */
+  readonly original: string;
+  /**
+   * The translated term in the target language.
+   */
+  readonly translated: string;
+  /**
+   * Optional context describing when to use this translation.
+   * This helps disambiguate terms that may have multiple translations.
+   */
+  readonly context?: string;
+}
+//#endregion
+export { Glossary, GlossaryEntry };

package/dist/glossary.d.ts

@@ -0,0 +1,25 @@
+//#region src/glossary.d.ts
+/**
+ * A glossary of terms for consistent translation.
+ */
+type Glossary = readonly GlossaryEntry[];
+/**
+ * An entry in a {@link Glossary}.
+ */
+interface GlossaryEntry {
+  /**
+   * The original term in the source language.
+   */
+  readonly original: string;
+  /**
+   * The translated term in the target language.
+   */
+  readonly translated: string;
+  /**
+   * Optional context describing when to use this translation.
+   * This helps disambiguate terms that may have multiple translations.
+   */
+  readonly context?: string;
+}
+//#endregion
+export { Glossary, GlossaryEntry };

package/dist/html.cjs

@@ -0,0 +1,253 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_tokens = require('./tokens.cjs');
+let htmlparser2 = require("htmlparser2");
+let dom_serializer = require("dom-serializer");
+dom_serializer = require_rolldown_runtime.__toESM(dom_serializer);
+
+//#region src/html.ts
+/**
+* Default attributes that should be translated.
+*/
+const DEFAULT_TRANSLATABLE_ATTRIBUTES = [
+	"alt",
+	"title",
+	"placeholder",
+	"aria-label",
+	"aria-description"
+];
+/**
+* Block-level elements that create natural chunk boundaries.
+*/
+const BLOCK_ELEMENTS = new Set([
+	"address",
+	"article",
+	"aside",
+	"blockquote",
+	"canvas",
+	"dd",
+	"div",
+	"dl",
+	"dt",
+	"fieldset",
+	"figcaption",
+	"figure",
+	"footer",
+	"form",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"header",
+	"hr",
+	"li",
+	"main",
+	"nav",
+	"noscript",
+	"ol",
+	"p",
+	"pre",
+	"section",
+	"table",
+	"tbody",
+	"td",
+	"tfoot",
+	"th",
+	"thead",
+	"tr",
+	"ul",
+	"video"
+]);
+/**
+* Elements whose content should not be translated.
+*/
+const NON_TRANSLATABLE_ELEMENTS = new Set([
+	"script",
+	"style",
+	"svg",
+	"math"
+]);
+/**
+* Determines if a node is an element.
+*/
+function isElement(node) {
+	return node.type === "tag";
+}
+/**
+* Determines if an element is a block-level element.
+*/
+function isBlockElement(node) {
+	return isElement(node) && BLOCK_ELEMENTS.has(node.name.toLowerCase());
+}
+/**
+* Determines if an element should be excluded from translation.
+*/
+function isNonTranslatable(node) {
+	return isElement(node) && NON_TRANSLATABLE_ELEMENTS.has(node.name.toLowerCase());
+}
+/**
+* Determines the chunk type from an HTML element.
+*/
+function getChunkTypeFromElement(element) {
+	const name = element.name.toLowerCase();
+	if (/^h[1-6]$/.test(name)) return "heading";
+	if ([
+		"ul",
+		"ol",
+		"dl"
+	].includes(name)) return "list";
+	if (["pre", "code"].includes(name)) return "code";
+	if ([
+		"section",
+		"article",
+		"header",
+		"footer",
+		"nav",
+		"aside",
+		"main"
+	].includes(name)) return "section";
+	return "paragraph";
+}
+/**
+* Gets the text content of a node (for checking if it has translatable
+* content).
+*/
+function getTextContent(node) {
+	if ("type" in node && node.type === "text") return node.data;
+	if ("children" in node) return node.children.map((child) => getTextContent(child)).join("");
+	return "";
+}
+/**
+* Checks if an element has any translatable attributes.
+*/
+function hasTranslatableAttributes(node) {
+	if (!isElement(node)) return false;
+	for (const attr of DEFAULT_TRANSLATABLE_ATTRIBUTES) {
+		const value = node.attribs[attr];
+		if (value != null && value.trim().length > 0) return true;
+	}
+	for (const child of node.children) if (hasTranslatableAttributes(child)) return true;
+	return false;
+}
+/**
+* Checks if a node has any translatable content.
+*/
+function hasTranslatableContent(node) {
+	if (isNonTranslatable(node)) return false;
+	if (getTextContent(node).trim().length > 0) return true;
+	return hasTranslatableAttributes(node);
+}
+/**
+* Extracts translatable blocks from an HTML document.
+*/
+function extractBlocks(doc, _options) {
+	const blocks = [];
+	function processNode(node) {
+		if (!isElement(node)) return;
+		const name = node.name.toLowerCase();
+		if (NON_TRANSLATABLE_ELEMENTS.has(name)) return;
+		if (BLOCK_ELEMENTS.has(name)) {
+			if (hasTranslatableContent(node)) blocks.push({
+				html: (0, dom_serializer.default)(node),
+				type: getChunkTypeFromElement(node)
+			});
+			return;
+		}
+		for (const child of node.children) processNode(child);
+	}
+	for (const node of doc.children) processNode(node);
+	return blocks;
+}
+/**
+* Splits text content at sentence boundaries.
+*/
+function splitAtSentences(text) {
+	return text.split(/(?<=[.!?])\s+/).filter((p) => p.trim().length > 0);
+}
+/**
+* Splits an HTML block into smaller pieces if it exceeds the token limit.
+*/
+function splitHtmlBlock(block, maxTokens, countTokens$1) {
+	if (countTokens$1(block.html) <= maxTokens) return [block];
+	const doc = (0, htmlparser2.parseDocument)(block.html);
+	const children = doc.children;
+	if (children.length === 1 && isElement(children[0])) {
+		const blockChildren = children[0].children.filter(isBlockElement);
+		if (blockChildren.length > 1) {
+			const result = [];
+			for (const child of blockChildren) {
+				const childBlocks = splitHtmlBlock({
+					html: (0, dom_serializer.default)(child),
+					type: getChunkTypeFromElement(child)
+				}, maxTokens, countTokens$1);
+				result.push(...childBlocks);
+			}
+			return result;
+		}
+	}
+	const sentences = splitAtSentences(getTextContent(doc));
+	if (sentences.length > 1) {
+		const result = [];
+		let currentText = "";
+		for (const sentence of sentences) {
+			const combined = currentText ? `${currentText} ${sentence}` : sentence;
+			if (countTokens$1(combined) <= maxTokens) currentText = combined;
+			else {
+				if (currentText) result.push({
+					html: currentText,
+					type: block.type
+				});
+				currentText = sentence;
+			}
+		}
+		if (currentText) result.push({
+			html: currentText,
+			type: block.type
+		});
+		return result;
+	}
+	return [block];
+}
+/**
+* Creates an HTML chunker.
+*
+* The chunker parses HTML content and creates chunks that respect element
+* boundaries.  Each block element is kept as a single chunk when possible,
+* and only split when exceeding the token limit.
+*
+* @param htmlOptions Optional HTML-specific chunking options.
+* @returns A chunker function for HTML content.
+* @since 0.2.0
+*/
+function createHtmlChunker(htmlOptions) {
+	const options = htmlOptions ?? {};
+	return async (text, chunkerOptions) => {
+		const maxTokens = chunkerOptions?.maxTokens ?? 4096;
+		const countTokens$1 = chunkerOptions?.countTokens ?? require_tokens.countTokens;
+		const signal = chunkerOptions?.signal;
+		signal?.throwIfAborted();
+		await Promise.resolve();
+		if (text.trim().length === 0) return [];
+		const blocks = extractBlocks((0, htmlparser2.parseDocument)(text, {
+			lowerCaseTags: true,
+			lowerCaseAttributeNames: true
+		}), options);
+		const chunks = [];
+		let chunkIndex = 0;
+		for (const block of blocks) {
+			signal?.throwIfAborted();
+			const splitBlocks = splitHtmlBlock(block, maxTokens, countTokens$1);
+			for (const splitBlock of splitBlocks) chunks.push({
+				content: splitBlock.html,
+				type: splitBlock.type,
+				index: chunkIndex++
+			});
+		}
+		return chunks;
+	};
+}
+
+//#endregion
+exports.DEFAULT_TRANSLATABLE_ATTRIBUTES = DEFAULT_TRANSLATABLE_ATTRIBUTES;
+exports.createHtmlChunker = createHtmlChunker;

package/dist/html.d.cts

@@ -0,0 +1,41 @@
+import { Chunker } from "./chunking.cjs";
+
+//#region src/html.d.ts
+
+/**
+ * Options specific to HTML chunking.
+ *
+ * @since 0.2.0
+ */
+interface HtmlChunkerOptions {
+  /**
+   * Additional HTML attributes to include for translation.
+   * Default translatable attributes: alt, title, placeholder, aria-label,
+   * aria-description.
+   */
+  readonly additionalTranslatableAttributes?: readonly string[];
+  /**
+   * Whether to strip HTML comments from the output.
+   *
+   * @default false
+   */
+  readonly stripComments?: boolean;
+}
+/**
+ * Default attributes that should be translated.
+ */
+declare const DEFAULT_TRANSLATABLE_ATTRIBUTES: readonly ["alt", "title", "placeholder", "aria-label", "aria-description"];
+/**
+ * Creates an HTML chunker.
+ *
+ * The chunker parses HTML content and creates chunks that respect element
+ * boundaries.  Each block element is kept as a single chunk when possible,
+ * and only split when exceeding the token limit.
+ *
+ * @param htmlOptions Optional HTML-specific chunking options.
+ * @returns A chunker function for HTML content.
+ * @since 0.2.0
+ */
+declare function createHtmlChunker(htmlOptions?: HtmlChunkerOptions): Chunker;
+//#endregion
+export { DEFAULT_TRANSLATABLE_ATTRIBUTES, HtmlChunkerOptions, createHtmlChunker };

package/dist/html.d.ts

@@ -0,0 +1,41 @@
+import { Chunker } from "./chunking.js";
+
+//#region src/html.d.ts
+
+/**
+ * Options specific to HTML chunking.
+ *
+ * @since 0.2.0
+ */
+interface HtmlChunkerOptions {
+  /**
+   * Additional HTML attributes to include for translation.
+   * Default translatable attributes: alt, title, placeholder, aria-label,
+   * aria-description.
+   */
+  readonly additionalTranslatableAttributes?: readonly string[];
+  /**
+   * Whether to strip HTML comments from the output.
+   *
+   * @default false
+   */
+  readonly stripComments?: boolean;
+}
+/**
+ * Default attributes that should be translated.
+ */
+declare const DEFAULT_TRANSLATABLE_ATTRIBUTES: readonly ["alt", "title", "placeholder", "aria-label", "aria-description"];
+/**
+ * Creates an HTML chunker.
+ *
+ * The chunker parses HTML content and creates chunks that respect element
+ * boundaries.  Each block element is kept as a single chunk when possible,
+ * and only split when exceeding the token limit.
+ *
+ * @param htmlOptions Optional HTML-specific chunking options.
+ * @returns A chunker function for HTML content.
+ * @since 0.2.0
+ */
+declare function createHtmlChunker(htmlOptions?: HtmlChunkerOptions): Chunker;
+//#endregion
+export { DEFAULT_TRANSLATABLE_ATTRIBUTES, HtmlChunkerOptions, createHtmlChunker };