@x18n/builtins 0.0.2 → 0.0.5

package/dist/checks.d.mts

@@ -0,0 +1,20 @@
+import { Check, Plugin } from "@x18n/core";
+//#region src/checks/index.d.ts
+export declare const missingKey: Check;
+export declare const missingTranslation: Check;
+export declare const staleTranslation: Check;
+export declare const emptyTranslation: Check;
+export declare const keyConflict: Check;
+export declare const localeCodeConflict: Check;
+export declare const unusedKey: Check;
+export declare const placeholderMismatch: Check;
+export declare const invalidSyntax: Check;
+export declare const dynamicKey: Check;
+export declare const identicalToSource: Check;
+export declare const keyStyle: Check;
+export declare const hardString: Check;
+export declare const glossary: Check;
+export declare const allChecks: readonly Check[];
+/** Every built-in check with its `recommended` severity. */
+export declare function recommended(): Plugin;
+//#endregion

package/dist/checks.mjs

@@ -0,0 +1,352 @@
+import { extractableHardStrings } from "./extractors.mjs";
+import { createPlaceholderComparer, localeSpellingKey } from "@x18n/core";
+//#region src/checks/index.ts
+function list(items) {
+	return items.join(", ");
+}
+const missingKey = {
+	id: "missing-key",
+	defaultSeverity: "error",
+	description: "A usage whose key is not defined in the source locale.",
+	*run(ctx) {
+		for (const usage of ctx.undefinedUsages()) yield {
+			key: usage.key,
+			locale: ctx.sourceLocale,
+			location: {
+				path: usage.path,
+				range: usage.range
+			},
+			message: `"${usage.key}" is not defined in ${ctx.sourceLocale}.`,
+			fixes: [{
+				title: `Add "${usage.key}" to ${ctx.sourceLocale}`,
+				ops: [{
+					type: "set",
+					key: usage.key,
+					locale: ctx.sourceLocale,
+					value: ""
+				}]
+			}]
+		};
+	}
+};
+const missingTranslation = {
+	id: "missing-translation",
+	defaultSeverity: "warning",
+	description: "A source-locale key that target locales lack. One diagnostic per key, at the source entry.",
+	*run(ctx) {
+		const missing = /* @__PURE__ */ new Map();
+		for (const coverage of ctx.coverage()) {
+			if (coverage.locale === ctx.sourceLocale) continue;
+			for (const key of coverage.missing) {
+				const locales = missing.get(key) ?? [];
+				missing.set(key, locales);
+				locales.push(coverage.locale);
+			}
+		}
+		for (const [key, locales] of missing) {
+			const source = ctx.message(key, ctx.sourceLocale);
+			yield {
+				key,
+				locale: ctx.sourceLocale,
+				message: `"${key}" is missing in ${list(locales)}.`,
+				fixes: [{
+					title: `Add empty values in ${list(locales)}`,
+					ops: locales.map((locale) => ({
+						type: "set",
+						key,
+						locale,
+						value: ""
+					}))
+				}, ...source ? [{
+					title: "Copy the source value",
+					ops: locales.map((locale) => ({
+						type: "set",
+						key,
+						locale,
+						value: source.value
+					}))
+				}] : []]
+			};
+		}
+	}
+};
+function changed(change) {
+	if (!Number.isFinite(change.updatedAt)) return "changed locally";
+	const revision = change.revision ? ` in ${change.revision.slice(0, 7)}` : "";
+	return `changed ${new Date(change.updatedAt).toISOString().slice(0, 10)}${revision}`;
+}
+const staleTranslation = {
+	id: "stale-translation",
+	defaultSeverity: "warning",
+	description: "A translation that last changed before its source message, by the history providers (git).",
+	*run(ctx) {
+		for (const coverage of ctx.coverage()) for (const key of coverage.outdated) yield {
+			key,
+			locale: coverage.locale,
+			message: `"${key}" in ${coverage.locale} is older than ${ctx.sourceLocale} (source ${changed(ctx.history(key, ctx.sourceLocale))}).`
+		};
+	}
+};
+const emptyTranslation = {
+	id: "empty-translation",
+	defaultSeverity: "warning",
+	description: "A message with an empty string value.",
+	*run(ctx) {
+		for (const message of ctx.messages()) if (message.value === "") yield {
+			key: message.key,
+			locale: message.locale,
+			message: `"${message.key}" is empty in ${message.locale}.`
+		};
+	}
+};
+const keyConflict = {
+	id: "key-conflict",
+	defaultSeverity: "error",
+	description: "A key that is both a leaf and a parent, or is duplicated across files of one locale.",
+	*run(ctx) {
+		const keys = new Set(ctx.keys());
+		for (const key of keys) {
+			const segments = key.split(".");
+			for (let i = 1; i < segments.length; i++) {
+				const parent = segments.slice(0, i).join(".");
+				if (keys.has(parent)) yield {
+					key: parent,
+					message: `"${parent}" is a message and also the parent of "${key}".`
+				};
+			}
+			for (const locale of ctx.locales) {
+				const copies = ctx.duplicates(key, locale);
+				if (copies.length > 1) {
+					const files = [...new Set(copies.map((m) => ctx.resources.find((r) => r.id === m.resource)?.path ?? m.resource))];
+					yield {
+						key,
+						locale,
+						message: `"${key}" is defined ${copies.length} times in ${locale} (${list(files)}).`
+					};
+				}
+			}
+		}
+	}
+};
+const localeCodeConflict = {
+	id: "locale-code-conflict",
+	defaultSeverity: "warning",
+	description: "Locale codes that differ only in spelling, such as zh_CN and zh-CN.",
+	*run(ctx) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const locale of ctx.locales) {
+			const id = localeSpellingKey(locale);
+			const group = groups.get(id) ?? [];
+			groups.set(id, group);
+			group.push(locale);
+		}
+		for (const group of groups.values()) if (group.length > 1) {
+			const resource = ctx.resources.find((r) => r.locale === group[1]);
+			yield {
+				locale: group[1],
+				location: resource ? {
+					path: resource.path,
+					range: {
+						start: 0,
+						end: 0
+					}
+				} : void 0,
+				message: `Locale codes ${list(group)} differ only in spelling; they are separate locales.`
+			};
+		}
+	}
+};
+const unusedKey = {
+	id: "unused-key",
+	defaultSeverity: "warning",
+	description: "A key with no usage, after keysInUse, derived keys and dynamic prefixes.",
+	*run(ctx) {
+		if (!ctx.hasScanners) return;
+		for (const key of ctx.unused()) yield {
+			key,
+			message: `"${key}" is not used.`,
+			fixes: [{
+				title: `Delete "${key}" in every locale`,
+				ops: [{
+					type: "delete",
+					key,
+					locales: "all"
+				}]
+			}]
+		};
+	}
+};
+const placeholderMismatch = {
+	id: "placeholder-mismatch",
+	defaultSeverity: "error",
+	description: "Target value placeholders differ from the source value.",
+	*run(ctx) {
+		const compare = createPlaceholderComparer(ctx.placeholderSyntaxes, ctx.placeholders);
+		for (const key of ctx.keys()) {
+			const source = ctx.message(key, ctx.sourceLocale);
+			if (typeof source?.value !== "string") continue;
+			for (const locale of ctx.locales) {
+				if (locale === ctx.sourceLocale) continue;
+				const target = ctx.message(key, locale);
+				if (typeof target?.value !== "string" || target.value === "") continue;
+				const { missing, extra } = compare(source.value, target.value);
+				if (missing.length || extra.length) {
+					const parts = [missing.length ? `missing ${list(missing)}` : "", extra.length ? `unexpected ${list(extra)}` : ""].filter(Boolean);
+					yield {
+						key,
+						locale,
+						message: `"${key}" in ${locale} has different placeholders than ${ctx.sourceLocale}: ${parts.join("; ")}.`
+					};
+				}
+			}
+		}
+	}
+};
+const invalidSyntax = {
+	id: "invalid-syntax",
+	defaultSeverity: "error",
+	description: "Message syntax errors (ICU, linked messages, nesting).",
+	*run(ctx) {
+		const keys = new Set(ctx.keys());
+		const exists = (key) => keys.has(key) || ctx.keys().some((k) => k.startsWith(`${key}.`));
+		for (const message of ctx.messages()) {
+			if (typeof message.value !== "string") continue;
+			const errors = [...ctx.syntaxErrors(message.value)];
+			for (const placeholder of ctx.placeholders(message.value)) if (placeholder.syntax === "linked" && !exists(placeholder.name)) errors.push(`linked message "${placeholder.name}" does not exist`);
+			for (const error of errors) yield {
+				key: message.key,
+				locale: message.locale,
+				message: `"${message.key}" in ${message.locale}: ${error}.`
+			};
+		}
+	}
+};
+const dynamicKey = {
+	id: "dynamic-key",
+	defaultSeverity: "off",
+	description: "A fully dynamic key that no check can follow.",
+	*run(ctx) {
+		for (const usage of ctx.usages()) if (usage.dynamic === "unknown") yield {
+			location: {
+				path: usage.path,
+				range: usage.range
+			},
+			message: `Dynamic key "${usage.raw}" cannot be checked.`
+		};
+	}
+};
+const identicalToSource = {
+	id: "identical-to-source",
+	defaultSeverity: "off",
+	description: "A target value that equals the source value.",
+	*run(ctx) {
+		for (const message of ctx.messages()) {
+			if (message.locale === ctx.sourceLocale || typeof message.value !== "string" || message.value === "") continue;
+			if (ctx.message(message.key, ctx.sourceLocale)?.value === message.value) yield {
+				key: message.key,
+				locale: message.locale,
+				message: `"${message.key}" in ${message.locale} is the same as in ${ctx.sourceLocale}.`
+			};
+		}
+	}
+};
+const caseRules = {
+	camel: /^[a-z][a-zA-Z0-9]*$/,
+	snake: /^[a-z][a-z0-9_]*$/,
+	kebab: /^[a-z][a-z0-9-]*$/,
+	pascal: /^[A-Z][a-zA-Z0-9]*$/
+};
+const keyStyle = {
+	id: "key-style",
+	defaultSeverity: "off",
+	description: "A key that does not match a naming rule (options: case, pattern).",
+	*run(ctx) {
+		const rule = typeof ctx.options.case === "string" ? caseRules[ctx.options.case] : void 0;
+		const pattern = typeof ctx.options.pattern === "string" ? new RegExp(ctx.options.pattern) : void 0;
+		for (const key of ctx.keys()) {
+			const path = key.slice(key.indexOf(":") + 1);
+			if (rule && !path.split(".").every((segment) => rule.test(segment))) yield {
+				key,
+				message: `"${key}" is not ${String(ctx.options.case)} case.`
+			};
+			else if (pattern && !pattern.test(key)) yield {
+				key,
+				message: `"${key}" does not match ${pattern.source}.`
+			};
+		}
+	}
+};
+const hardString = {
+	id: "hard-string",
+	defaultSeverity: "info",
+	description: "A hard-coded string that should probably be a message. On with `extract.autoDetect`.",
+	*run(ctx) {
+		if (!ctx.config.extract.autoDetect && ctx.config.checks["hard-string"] === void 0) return;
+		for (const hard of extractableHardStrings(ctx.config.extract, ctx.hardStrings(), ctx.text)) yield {
+			location: {
+				path: hard.path,
+				range: hard.range
+			},
+			message: `Hard-coded string "${hard.text}".`
+		};
+	}
+};
+const unspaced = "\\p{scx=Han}\\p{scx=Hiragana}\\p{scx=Katakana}\\p{scx=Hangul}\\p{scx=Thai}\\p{scx=Lao}\\p{scx=Khmer}\\p{scx=Myanmar}";
+const startsUnspaced = new RegExp(`^[${unspaced}]`, "u");
+const endsUnspaced = new RegExp(`[${unspaced}]$`, "u");
+/** A term as a whole word, so "Home" does not match "Homepage"; a plain substring at edges in unspaced scripts. */
+function wordPattern(term) {
+	const before = startsUnspaced.test(term) ? "" : "(?<![\\p{L}\\p{N}])";
+	const after = endsUnspaced.test(term) ? "" : "(?![\\p{L}\\p{N}])";
+	return new RegExp(`${before}${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}${after}`, "iu");
+}
+function* glossaryDiagnostics(ctx, entry) {
+	const term = wordPattern(entry.term);
+	for (const key of ctx.keys()) {
+		const source = ctx.message(key, ctx.sourceLocale)?.value;
+		if (typeof source !== "string" || !term.test(source)) continue;
+		for (const locale of ctx.locales) {
+			const value = ctx.message(key, locale)?.value;
+			const expected = entry.doNotTranslate ? entry.term : entry.translations?.[locale];
+			if (locale === ctx.sourceLocale || typeof value !== "string" || value === "" || !expected) continue;
+			if (!wordPattern(expected).test(value)) yield {
+				key,
+				locale,
+				message: `"${key}" in ${locale} should use "${expected}" for "${entry.term}".`
+			};
+		}
+	}
+}
+const glossary = {
+	id: "glossary",
+	defaultSeverity: "off",
+	description: "A glossary term translated differently from the glossary.",
+	*run(ctx) {
+		for (const entry of ctx.config.glossary) yield* glossaryDiagnostics(ctx, entry);
+	}
+};
+const allChecks = [
+	missingKey,
+	invalidSyntax,
+	placeholderMismatch,
+	keyConflict,
+	missingTranslation,
+	staleTranslation,
+	emptyTranslation,
+	unusedKey,
+	localeCodeConflict,
+	dynamicKey,
+	identicalToSource,
+	keyStyle,
+	hardString,
+	glossary
+];
+/** Every built-in check with its `recommended` severity. */
+function recommended() {
+	return {
+		name: "x18n:checks",
+		checks: allChecks
+	};
+}
+//#endregion
+export { allChecks, dynamicKey, emptyTranslation, glossary, hardString, identicalToSource, invalidSyntax, keyConflict, keyStyle, localeCodeConflict, missingKey, missingTranslation, placeholderMismatch, recommended, staleTranslation, unusedKey };

package/dist/extractors.d.mts

@@ -0,0 +1,57 @@
+import { ExtractItem, ExtractOptions, ExtractTemplate, HardString, KeyString, Project, TextRange } from "@x18n/core";
+//#region src/extractors/index.d.ts
+export type Score = "must-include" | "should-include" | "none" | "should-exclude" | "must-exclude";
+export interface ExtractionRule {
+  readonly id: string;
+  readonly test: (text: string, kind: string) => Score;
+}
+/** Built-in rules, applied in order. A `must-*` wins at once; otherwise the last `should-*` decides. */
+export declare const rules: readonly ExtractionRule[];
+/** Folds rule scores the i18n-ally way (`shouldExtract`). */
+export declare function shouldExtract(text: string, kind: string, list?: readonly ExtractionRule[]): boolean;
+export type KeyCase = "camel" | "snake" | "kebab" | "dot";
+/** "Forgot password?" becomes `forgotPassword` (camel), `forgot_password`, `forgot-password` or `forgot.password`. */
+export declare function slugify(text: string, keyCase?: KeyCase, maxLength?: number): string;
+/** Fallback templates per kind, used after config and preset templates. */
+export declare const defaultTemplates: readonly ExtractTemplate[];
+export interface ExtractCandidate {
+  readonly path: string;
+  /** 1-based line, for display. */
+  readonly line: number;
+  readonly kind: string;
+  readonly text: string;
+  /** The text in the file at `range`, used to detect stale plans. */
+  readonly original: string;
+  readonly range: TextRange;
+  readonly attribute: string | undefined;
+  readonly key: KeyString;
+  /** True when an existing key with the same source value is reused. */
+  readonly reused: boolean;
+  /** The message to store: template arguments become placeholders. */
+  readonly value: string;
+  readonly replacement: string;
+  readonly imports: readonly string[];
+  /** Other templates that also apply, for surfaces that let users choose. */
+  readonly alternatives: readonly string[];
+}
+export interface FindOptions {
+  /** Only these files (globs). */
+  readonly files?: readonly string[] | undefined;
+}
+/** Hard strings worth extracting: they pass the rules and no non-UI file, config ignore or control comment skips them. */
+export declare function extractableHardStrings(options: ExtractOptions, hardStrings: Iterable<HardString & {
+  readonly path: string;
+}>, textOf: (path: string) => string | undefined): Generator<HardString & {
+  readonly path: string;
+}>;
+/** Hard strings worth extracting, with proposed keys, values and replacements. */
+export declare function findCandidates(project: Project, options?: FindOptions): ExtractCandidate[];
+export interface ExtractPlanFile {
+  readonly x18n: 1;
+  readonly project: string;
+  readonly items: readonly ExtractCandidate[];
+}
+export declare function toPlanFile(project: Project, candidates: readonly ExtractCandidate[]): ExtractPlanFile;
+/** Turns plan items (maybe edited by a human or agent) into edit items, after checking the files did not change. */
+export declare function extractItems(project: Project, items: readonly Pick<ExtractCandidate, "path" | "range" | "original" | "key" | "value" | "replacement" | "imports">[]): ExtractItem[];
+//#endregion