@x18n/builtins 0.0.0-stage → 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+x18n adapts code and ideas from [i18n-ally](https://github.com/lokalise/i18n-ally). Each adapted file starts with a line `Adapted from i18n-ally (MIT), <original path>`.
+
+## Adapted files
+
+| x18n file | i18n-ally source |
+| --- | --- |
+| `packages/builtins/src/finders/pattern.ts` | `src/utils/PathMatcher.ts`, `src/core/loaders/LocaleLoader.ts` (`guessDirStructure`, `findLocaleDirs`) |
+| `packages/builtins/src/scanners/regex.ts` | `src/utils/Regex.ts` |
+| `packages/builtins/src/manifests/index.ts` | `src/packagesParsers/*` |
+| `packages/builtins/src/presets/index.ts` | `src/frameworks/*` |
+| `packages/builtins/src/extractors/index.ts` | `src/extraction/*`, `src/core/Extract.ts` |
+
+## i18n-ally license
+
+MIT License
+
+Copyright (c) 2020 Lokalise Inc., Anthony Fu, think2011
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/checks.d.mts

@@ -0,0 +1,19 @@
+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 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,330 @@
+import { shouldExtract } from "./extractors.mjs";
+import { 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
+					}))
+				}] : []]
+			};
+		}
+	}
+};
+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"
+				}]
+			}]
+		};
+	}
+};
+function placeholderNames(ctx, value) {
+	return ctx.placeholders(value).map((p) => p.name).sort();
+}
+const placeholderMismatch = {
+	id: "placeholder-mismatch",
+	defaultSeverity: "error",
+	description: "Target value placeholders differ from the source value.",
+	*run(ctx) {
+		for (const key of ctx.keys()) {
+			const source = ctx.message(key, ctx.sourceLocale);
+			if (typeof source?.value !== "string") continue;
+			const expected = placeholderNames(ctx, source.value);
+			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 actual = placeholderNames(ctx, target.value);
+				const missing = expected.filter((name) => !actual.includes(name));
+				const extra = actual.filter((name) => !expected.includes(name));
+				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 ctx.hardStrings()) if (shouldExtract(hard.text, hard.kind)) yield {
+			location: {
+				path: hard.path,
+				range: hard.range
+			},
+			message: `Hard-coded string "${hard.text}".`
+		};
+	}
+};
+function* glossaryDiagnostics(ctx, entry) {
+	const term = entry.term.toLowerCase();
+	for (const key of ctx.keys()) {
+		const source = ctx.message(key, ctx.sourceLocale)?.value;
+		if (typeof source !== "string" || !source.toLowerCase().includes(term)) 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 (!value.toLowerCase().includes(expected.toLowerCase())) 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,
+	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, unusedKey };

package/dist/extractors.d.mts

@@ -0,0 +1,51 @@
+import { ExtractItem, ExtractTemplate, 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, 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