@x18n/core 0.0.9 → 0.0.12

package/dist/index.d.mts

@@ -575,6 +575,8 @@ interface CheckContext {
   readonly config: ResolvedConfig;
   readonly sourceLocale: LocaleCode;
   readonly locales: readonly LocaleCode[];
+  /** The locales a locale falls back to, nearest first. Empty for a locale without a fallback. */
+  readonly fallbacks: (locale: LocaleCode) => readonly LocaleCode[];
   readonly resources: readonly Resource[];
   /** Options from `[severity, options]` in config. */
   readonly options: JsonObject;
@@ -832,6 +834,10 @@ interface SerializableConfig {
   /** Locale codes as written in paths. Filters the found locales. */
   readonly locales?: readonly string[] | undefined;
   readonly ignoreLocales?: readonly string[] | undefined;
+  /** Locale to the locale it falls back to, such as `{ 'en-GB': 'en' }`. A locale with a fallback holds only overrides: a key it lacks or leaves empty is not missing when the fallback chain has it. `'auto'` falls back to the nearest parent language that exists: `en-US` to `en`, `zh-Hant-TW` to `zh-Hant` or `zh`. */
+  readonly localeFallbacks?: "auto" | {
+    readonly [locale: string]: string;
+  } | undefined;
   /** `'auto'` detects built-in presets from the project's dependencies. */
   readonly presets?: "auto" | readonly PluginSpecifier[] | undefined;
   readonly plugins?: readonly PluginSpecifier[] | undefined;
@@ -892,6 +898,9 @@ interface ResolvedConfig {
   readonly sourceLocale: string;
   readonly locales: readonly string[] | undefined;
   readonly ignoreLocales: readonly string[];
+  readonly localeFallbacks: "auto" | {
+    readonly [locale: string]: string;
+  };
   readonly resources: readonly ResourceSpec[];
   readonly formats: {
     readonly [extension: string]: string;

package/dist/index.mjs

@@ -363,6 +363,28 @@ const defaultRegions = {
 	vi: "VN",
 	zh: "CN"
 };
+/** The fallback of each locale: from the config map, or for `'auto'` the nearest parent language among `locales`. The source locale has none. */
+function resolveFallbacks(setting, locales, sourceLocale) {
+	if (setting !== "auto") return Object.fromEntries(Object.entries(setting).filter(([locale]) => locale !== sourceLocale));
+	const fallbacks = {};
+	for (const locale of locales) {
+		if (locale === sourceLocale) continue;
+		for (let cut = locale.search(/[-_][^-_]*$/); cut > 0; cut = locale.slice(0, cut).search(/[-_][^-_]*$/)) {
+			const parent = locales.find((code) => code === locale.slice(0, cut));
+			if (parent) {
+				fallbacks[locale] = parent;
+				break;
+			}
+		}
+	}
+	return fallbacks;
+}
+/** The locales a locale falls back to, nearest first. Stops at a cycle. */
+function fallbackChain(fallbacks, locale) {
+	const chain = [];
+	for (let next = fallbacks[locale]; next !== void 0 && next !== locale && !chain.includes(next); next = fallbacks[next]) chain.push(next);
+	return chain;
+}
 const pluralOrder = [
 	"zero",
 	"one",
@@ -712,6 +734,7 @@ const ConfigSchema = v.strictObject({
 	sourceLocale: v.optional(v.string()),
 	locales: v.optional(strings),
 	ignoreLocales: v.optional(strings),
+	localeFallbacks: v.optional(v.union([v.literal("auto"), v.record(v.string(), v.string())])),
 	presets: v.optional(v.union([v.literal("auto"), v.array(pluginSpecifier)])),
 	plugins: v.optional(v.array(pluginSpecifier)),
 	resources: v.optional(v.array(resourceSpec)),
@@ -930,14 +953,20 @@ function levelOf(setting) {
 function computeCoverage(state, reference) {
 	const { messages, sourceLocale } = state;
 	return state.locales.map((locale) => {
+		const chain = fallbackChain(state.fallbacks, locale);
+		const inherited = (key) => chain.some((code) => {
+			const value = messages.get(key)?.get(code)?.[0]?.value;
+			return value !== void 0 && value !== "";
+		});
 		const missing = [];
 		const empty = [];
 		const outdated = [];
 		for (const key of reference) {
 			const value = messages.get(key)?.get(locale)?.[0]?.value;
-			if (value === void 0) missing.push(key);
-			else if (value === "") empty.push(key);
-			else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale))) outdated.push(key);
+			if (value === void 0 || value === "") {
+				if (inherited(key)) continue;
+				(value === void 0 ? missing : empty).push(key);
+			} else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale))) outdated.push(key);
 		}
 		return {
 			locale,
@@ -1069,6 +1098,7 @@ function createAnalyzer(options) {
 			config,
 			sourceLocale,
 			locales,
+			fallbacks: (locale) => fallbackChain(state.fallbacks, locale),
 			resources: state.resources.map((s) => s.resource),
 			hasScanners,
 			keys: () => allKeys,
@@ -1543,7 +1573,7 @@ var PlanBuilder = class {
 			case "set":
 				this.setValue(op.key, op.locale, op.value);
 				if (this.config.write.keepFilled) {
-					for (const locale of this.state.locales) if (locale !== op.locale && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
+					for (const locale of this.state.locales) if (locale !== op.locale && !this.state.fallbacks[locale] && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
 				}
 				break;
 			case "delete":
@@ -1993,6 +2023,7 @@ function createProject(options) {
 	let revision = 0;
 	let namespaced = false;
 	let locales = [];
+	let fallbacks = {};
 	let sourceLocale = config.sourceLocale;
 	let resolver;
 	let watcher;
@@ -2184,6 +2215,7 @@ function createProject(options) {
 		if (!found.includes(sourceLocale) && config.origins.sourceLocale === void 0 && found.length > 0) sourceLocale = found.find((code) => code.toLowerCase().startsWith("en")) ?? [...found].sort()[0];
 		locales = [sourceLocale, ...found.filter((code) => code !== sourceLocale).sort()];
 		if (!found.includes(sourceLocale) && found.length === 0) locales = [sourceLocale];
+		fallbacks = resolveFallbacks(config.localeFallbacks, locales, sourceLocale);
 		resolver = createUsageResolver(config, namespaced, normalizers);
 		resolved = /* @__PURE__ */ new WeakMap();
 		resourceIndex = void 0;
@@ -2456,6 +2488,7 @@ function createProject(options) {
 			revision,
 			sourceLocale,
 			locales,
+			fallbacks,
 			resources: [...resourceStates.values()],
 			resourceErrors: [...resourceStates.values()].flatMap((s) => s.error ? [{
 				error: s.error,
@@ -2630,6 +2663,7 @@ function createProject(options) {
 			revision,
 			sourceLocale,
 			locales,
+			fallbacks,
 			namespaced,
 			resources: [...resourceStates.values()],
 			fileTexts
@@ -2779,6 +2813,7 @@ function defaultDraft() {
 		sourceLocale: "en",
 		locales: void 0,
 		ignoreLocales: [],
+		localeFallbacks: {},
 		resources: [],
 		formats: {},
 		keyStyle: "auto",
@@ -2822,6 +2857,12 @@ function serializablePart(config) {
 		history: options
 	};
 }
+function mergeFallbacks(base, layer) {
+	return base === "auto" || layer === "auto" ? layer : {
+		...base,
+		...layer
+	};
+}
 /** Applies a user config layer: scalars replace, lists of rules append. */
 function applyLayer(draft, layer, origin, origins) {
 	const mark = (key) => {
@@ -2839,6 +2880,10 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.ignoreLocales = [...draft.ignoreLocales, ...layer.ignoreLocales];
 		mark("ignoreLocales");
 	}
+	if (layer.localeFallbacks !== void 0) {
+		draft.localeFallbacks = mergeFallbacks(draft.localeFallbacks, layer.localeFallbacks);
+		mark("localeFallbacks");
+	}
 	if (layer.resources !== void 0) {
 		draft.resources = layer.resources;
 		mark("resources");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "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

@@ -25,6 +25,22 @@
         "type": "string"
       }
     },
+    "localeFallbacks": {
+      "anyOf": [
+        {
+          "const": "auto"
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      ]
+    },
     "presets": {
       "anyOf": [
         {