@x18n/core 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -284,9 +284,13 @@ interface LocaleInfo {
   readonly region: string | undefined;
   readonly displayName: string | undefined;
   readonly flag: string | undefined;
+  /** The plural categories a message may have. */
   readonly pluralCategories: readonly Intl.LDMLPluralRule[];
   /** Categories of ordinal numbers (1st, 2nd), which differ from the cardinal ones. */
   readonly ordinalCategories: readonly Intl.LDMLPluralRule[];
+  /** The plural categories a message must have: those whole numbers select. French may leave out `many`, from 1,000,000 only. */
+  readonly requiredPluralCategories: readonly Intl.LDMLPluralRule[];
+  readonly requiredOrdinalCategories: readonly Intl.LDMLPluralRule[];
 }
 /** Embedded resource inside a file, for example a Vue `<i18n>` block. */
 interface ResourceBlock {
@@ -330,6 +334,10 @@ interface Usage {
   readonly range: TextRange;
   /** Range of the whole call that holds the key (`t('a', { n })`), when the scanner knows it. */
   readonly expression: TextRange | undefined;
+  /** Names of the params the call passes (`t('a', { n })` gives `['n']`); undefined when the scanner cannot tell, as with a spread or a variable. */
+  readonly params?: readonly string[] | undefined;
+  /** The default value written in code (`t('a', 'Default')`), when the scanner knows it. */
+  readonly defaultValue?: string | undefined;
   readonly scanner: string;
   readonly kind: UsageKind;
   /** `t(`pages.${id}.title`)` gives 'prefix' with key `pages`. */
@@ -623,6 +631,10 @@ interface UsageCandidate {
   readonly range: TextRange;
   /** Range of the whole call that holds the key, when the scanner knows it. */
   readonly expression?: TextRange | undefined;
+  /** Names of the params the call passes, when they are all static. */
+  readonly params?: readonly string[] | undefined;
+  /** The default value the call writes in code. */
+  readonly defaultValue?: string | undefined;
   readonly kind: UsageKind;
   readonly dynamic: false | "prefix" | "unknown";
   readonly namespace?: string | undefined;
@@ -782,10 +794,19 @@ interface ReportInput {
   readonly coverage: readonly LocaleCoverage[];
   readonly summary: ReportSummary;
 }
+/** What a check baseline left out (`x18n check --baseline`). */
+interface BaselineSummary {
+  /** Known diagnostics that the baseline left out of the report. */
+  readonly suppressed: number;
+  /** Baseline entries that no longer occur, to drop with `--update-baseline`. */
+  readonly fixed: number;
+}
 interface ReporterContext {
   /** Turns a project path into the path to print (relative to the cwd). */
   readonly displayPath: (path: string, project: string) => string;
   readonly color: boolean;
+  /** Set when a baseline applies; the inputs then hold only new diagnostics. */
+  readonly baseline?: BaselineSummary | undefined;
 }
 interface Reporter {
   readonly id: string;
@@ -907,6 +928,13 @@ interface ArgSource {
   readonly arg: number;
   readonly property?: string | undefined;
 }
+/** Where the params of a call are: the static keys of an object literal argument. */
+interface ParamsSource {
+  /** Arguments that may hold the params object, in order; string arguments are skipped (`t(key, 'Default', { n })`). */
+  readonly arg: number | readonly number[];
+  /** Option names the library reads itself, which a message need not use (`ns`, `defaultValue`). */
+  readonly options?: readonly string[] | undefined;
+}
 /** Data that drives the AST scanners: which calls are translate calls and where the key is. */
 interface CallSpec {
   /** Function or member path: 't', '$t', 'i18n.t', 'intl.formatMessage'. */
@@ -919,6 +947,10 @@ interface CallSpec {
   readonly namespace?: ArgSource | string | undefined;
   /** Where a key prefix comes from (`keyPrefix` option, or next-intl `useTranslations('a.b')`). */
   readonly keyPrefix?: ArgSource | undefined;
+  /** Where the params passed to the message are. For factories, those of the returned functions. */
+  readonly params?: ParamsSource | undefined;
+  /** Where a default value written in code comes from; the first string found wins. For factories, that of the returned functions. */
+  readonly defaultValue?: readonly ArgSource[] | undefined;
   /** The callee is a factory that returns the translate function, for example `useI18n()` returning `{ t }`. */
   readonly factory?: boolean | undefined;
   /** For factories: the names of the returned translate functions. Default `['t']`. */
@@ -1308,6 +1340,13 @@ interface PromptOptions {
   readonly context?: boolean | undefined;
   /** Translate prompts: add stale translations (load history first). */
   readonly stale?: boolean | undefined;
+  /** Translate prompts: add translations that checks report in the target locale, all of them (`true`) or of these check ids. */
+  readonly check?: boolean | readonly string[] | undefined;
+}
+interface PromptIssue {
+  /** Check id, for example `identical-to-source`. */
+  readonly code: string;
+  readonly message: string;
 }
 interface UsageContext {
   readonly path: string;
@@ -1322,6 +1361,8 @@ interface PromptItem {
   readonly existing: string | undefined;
   /** For a stale translation: the source value when the translation last changed, when known. */
   readonly previousSource?: string | undefined;
+  /** With `check`: what the checks report for the current value. */
+  readonly issues?: readonly PromptIssue[] | undefined;
   readonly context: readonly UsageContext[];
 }
 interface PromptData {
@@ -1748,4 +1789,4 @@ export declare function rangeContains(range: TextRange, offset: number): boolean
 /** Fast non-cryptographic string hash (cyrb53), as hex. */
 export declare function hashText(text: string): string;
 //#endregion
-export type { Analysis, Answers, ApplyResult, ArgSource, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginLoader, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetDetection, PresetEntry, PresetExplanation, PresetFactory, PresetLoader, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };
+export type { Analysis, Answers, ApplyResult, ArgSource, BaselineSummary, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParamsSource, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginLoader, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetDetection, PresetEntry, PresetExplanation, PresetFactory, PresetLoader, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptIssue, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };

package/dist/index.mjs

@@ -492,6 +492,14 @@ function parseLocaleInfo(code) {
 		const found = language ? safe(() => new Intl.PluralRules(tag, { type }).resolvedOptions().pluralCategories) : void 0;
 		return found ? pluralOrder.filter((category) => found.includes(category)) : ["other"];
 	};
+	const required = (type) => {
+		const found = /* @__PURE__ */ new Set(["other"]);
+		if (language && safe(() => Intl.PluralRules.supportedLocalesOf([tag]).length > 0)) {
+			const rules = new Intl.PluralRules(tag, { type });
+			for (let n = 0; n < 2e3; n++) found.add(rules.select(n));
+		}
+		return pluralOrder.filter((category) => found.has(category));
+	};
 	const flagRegion = region ?? (language === "zh" && script === "Hant" ? "TW" : language ? defaultRegions[language] : void 0);
 	return {
 		code,
@@ -500,7 +508,9 @@ function parseLocaleInfo(code) {
 		displayName,
 		flag: flagRegion ? flagOf(flagRegion) : void 0,
 		pluralCategories: categories("cardinal"),
-		ordinalCategories: categories("ordinal")
+		ordinalCategories: categories("ordinal"),
+		requiredPluralCategories: required("cardinal"),
+		requiredOrdinalCategories: required("ordinal")
 	};
 }
 /** Codes that differ only in spelling (`zh_CN` and `zh-cn`), the same after a lenient normalization. */
@@ -776,6 +786,10 @@ const argSource = v.strictObject({
 	arg: v.number(),
 	property: v.optional(v.string())
 });
+const paramsSource = v.strictObject({
+	arg: v.union([v.number(), v.array(v.number())]),
+	options: v.optional(strings)
+});
 const callSpec = v.strictObject({
 	callee: v.union([v.string(), strings]),
 	kind: v.optional(v.picklist([
@@ -786,6 +800,8 @@ const callSpec = v.strictObject({
 	key: v.optional(v.union([v.number(), argSource])),
 	namespace: v.optional(v.union([argSource, v.string()])),
 	keyPrefix: v.optional(argSource),
+	params: v.optional(paramsSource),
+	defaultValue: v.optional(v.array(argSource)),
 	factory: v.optional(v.boolean()),
 	returns: v.optional(strings),
 	types: v.optional(strings)
@@ -1167,6 +1183,8 @@ function createUsageResolver(config, namespaced, normalizers) {
 			path,
 			range: candidate.range,
 			expression: candidate.expression,
+			...candidate.params ? { params: candidate.params } : {},
+			...candidate.defaultValue === void 0 ? {} : { defaultValue: candidate.defaultValue },
 			scanner,
 			kind: candidate.kind,
 			dynamic: candidate.dynamic,
@@ -1202,8 +1220,12 @@ function suppressedRanges(text) {
 	}
 	return ranges;
 }
-/** The plural categories of a locale's language: Japanese has only `other`. */
-function categoriesOf(info, type) {
+/** The plural categories of a locale's language: Japanese has only `other`. `required` keeps those whole numbers select. */
+function categoriesOf(info, type, required = false) {
+	if (required) {
+		const allowed = categoriesOf(info, type);
+		return (type === "ordinal" ? info.requiredOrdinalCategories : info.requiredPluralCategories).filter((category) => category === "other" || allowed.includes(category));
+	}
 	return type === "ordinal" ? info.ordinalCategories : info.pluralCategories;
 }
 const tokens = /(\{key\}|\{plural\}|\{ordinal\}|\*)/;
@@ -1282,7 +1304,7 @@ function levelOf(setting) {
 }
 /**
 * The keys a locale needs: the reference keys, with plural forms swapped for the categories of the locale's
-* language. Forms the language lacks (`item_zero` in English) count only where they exist.
+* language. Forms the language lacks or may leave out (`item_zero` in English, `item_many` in French) count only where they exist.
 */
 function expectedKeys(state, options, reference, locale) {
 	const info = options.localeInfo(locale);
@@ -1290,7 +1312,7 @@ function expectedKeys(state, options, reference, locale) {
 	for (const key of reference) {
 		const form = options.formOf(key);
 		if (!form || state.messages.get(key)?.has(locale)) keys.add(key);
-		form && categoriesOf(info, form.type).forEach((category) => keys.add(form.keyOf(category)));
+		form && categoriesOf(info, form.type, true).forEach((category) => keys.add(form.keyOf(category)));
 	}
 	return [...keys].sort();
 }
@@ -2416,13 +2438,28 @@ function contextOf(project, key) {
 		}];
 	});
 }
+/** The diagnostics of checks (all, or these ids) on values the locale has, by key. */
+function reportedValues(project, diagnostics, to, check) {
+	const codes = check === true ? void 0 : new Set(check);
+	const reported = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		if (diagnostic.key === void 0 || diagnostic.locale !== to || codes && !codes.has(diagnostic.code)) continue;
+		if (!text(project.message(diagnostic.key, to)?.value)) continue;
+		const found = reported.get(diagnostic.key) ?? [];
+		reported.set(diagnostic.key, found);
+		found.push(diagnostic);
+	}
+	return reported;
+}
 /** Builds the parts of a translate or review prompt from project state. */
 function buildPrompt(project, kind, to, options, extra) {
 	const from = project.sourceLocale;
 	const match = typeof options.keys === "string" ? keyMatcher([options.keys]) : void 0;
 	const list = Array.isArray(options.keys) ? new Set(options.keys) : void 0;
-	const outdated = new Set(project.analyze().coverage.find((c) => c.locale === to)?.outdated);
+	const analysis = project.analyze();
+	const outdated = new Set(analysis.coverage.find((c) => c.locale === to)?.outdated);
 	const stale = (key) => outdated.has(key);
+	const reported = kind === "translate" && options.check ? reportedValues(project, analysis.diagnostics, to, options.check) : /* @__PURE__ */ new Map();
 	const candidates = project.keys({ namespace: options.namespace }).filter((key) => {
 		if (match && !match(key)) return false;
 		if (list && !list.has(key)) return false;
@@ -2430,7 +2467,7 @@ function buildPrompt(project, kind, to, options, extra) {
 		if (source === void 0 || source === "") return false;
 		const target = text(project.message(key, to)?.value);
 		if (kind === "review") return target !== void 0 && target !== "";
-		return list !== void 0 || target === void 0 || target === "" || options.stale === true && stale(key);
+		return list !== void 0 || target === void 0 || target === "" || options.stale === true && stale(key) || reported.has(key);
 	});
 	const start = Number(options.cursor ?? 0) || 0;
 	const limit = options.limit ?? 50;
@@ -2444,6 +2481,7 @@ function buildPrompt(project, kind, to, options, extra) {
 	};
 	if (syntaxes.length > 0) draft.rules.push(`Keep every placeholder exactly as written (${syntaxes.map((s) => `\`${s.example ?? s.id}\``).join(", ")}); do not translate their names.`);
 	draft.rules.push("Keep markup tags and their attributes as they are.", "Match the tone and wording of the existing messages in the target locale.", "Do not translate glossary terms marked \"do not translate\".");
+	if (reported.size > 0) draft.rules.push(`A message with a reported problem has a current ${to} value: fix the problem. When the current value is right as it is, such as a word that is the same in both languages, leave the key out of the results.`);
 	if (info.pluralCategories.length > 1) draft.notes.push(`${to} uses the plural categories ${info.pluralCategories.join(", ")}.`);
 	for (const hook of extra.hooks) hook(draft, {
 		sourceLocale: from,
@@ -2453,7 +2491,7 @@ function buildPrompt(project, kind, to, options, extra) {
 	const examples = kind === "translate" ? project.keys().flatMap((key) => {
 		const source = text(project.message(key, from)?.value);
 		const target = text(project.message(key, to)?.value);
-		return source && target && !candidates.includes(key) ? [{
+		return source && target && target !== source && !candidates.includes(key) ? [{
 			key,
 			source,
 			target
@@ -2469,6 +2507,10 @@ function buildPrompt(project, kind, to, options, extra) {
 			placeholders: [...new Set(syntaxes.flatMap((s) => s.find(source)).map((p) => p.text))],
 			existing: text(project.message(key, to)?.value) || void 0,
 			previousSource: previous === source ? void 0 : previous,
+			issues: reported.get(key)?.map((d) => ({
+				code: d.code,
+				message: d.message
+			})),
 			context: options.context === false ? [] : contextOf(project, key)
 		};
 	});
@@ -2513,6 +2555,7 @@ function renderItem(item, to) {
 	if (item.placeholders.length) out.push(`- Placeholders: ${item.placeholders.map((p) => `\`${p}\``).join(", ")}`);
 	if (item.previousSource !== void 0) out.push(`- Source when ${to} last changed: ${JSON.stringify(item.previousSource)}`);
 	if (item.existing !== void 0) out.push(`- Current ${to}: ${JSON.stringify(item.existing)}`);
+	for (const issue of item.issues ?? []) out.push(`- Reported: ${issue.message} (\`${issue.code}\`)`);
 	for (const context of item.context) out.push(`- Used in \`${context.path}:${context.line}\`:`, "", "  ```", ...context.snippet.split("\n").map((line) => `  ${line}`), "  ```");
 	out.push("");
 	return out;
@@ -2605,10 +2648,10 @@ function createProject(options) {
 		}
 		return info;
 	}
-	/** Whether `locale` needs `key`: not a plural form of a category its language lacks. */
+	/** Whether `locale` needs `key`: not a plural form of a category its language lacks or may leave out. */
 	function needs(key, locale) {
 		const form = formOf(key);
-		return !form || categoriesOf(localeInfo(locale), form.type).includes(form.category);
+		return !form || categoriesOf(localeInfo(locale), form.type, true).includes(form.category);
 	}
 	const reviewStore = config.review.enabled ? registry.reviewStores.at(-1) : void 0;
 	async function loadReviews() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Runtime-neutral engine of x18n: domain model, plugin API and project analysis",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",

package/schema/config.json

@@ -272,6 +272,52 @@
                 ],
                 "additionalProperties": false
               },
+              "params": {
+                "type": "object",
+                "properties": {
+                  "arg": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "number"
+                        }
+                      }
+                    ]
+                  },
+                  "options": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "arg"
+                ],
+                "additionalProperties": false
+              },
+              "defaultValue": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "arg": {
+                      "type": "number"
+                    },
+                    "property": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "arg"
+                  ],
+                  "additionalProperties": false
+                }
+              },
               "factory": {
                 "type": "boolean"
               },

package/schema/plugin.json

@@ -217,6 +217,52 @@
                 ],
                 "additionalProperties": false
               },
+              "params": {
+                "type": "object",
+                "properties": {
+                  "arg": {
+                    "anyOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "number"
+                        }
+                      }
+                    ]
+                  },
+                  "options": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "arg"
+                ],
+                "additionalProperties": false
+              },
+              "defaultValue": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "arg": {
+                      "type": "number"
+                    },
+                    "property": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "arg"
+                  ],
+                  "additionalProperties": false
+                }
+              },
               "factory": {
                 "type": "boolean"
               },