@gunshi/plugin-i18n 0.35.1 → 0.35.3

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, PluginWithExtension, Prettify } from "@gunshi/plugin";
 
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/resolver.d.ts
 
 //#region src/resolver.d.ts
 /**
@@ -422,7 +422,7 @@ interface ArgSchema {
    *
    * @param value - Raw string value from command line
    * @returns Parsed value of any type
-   * @throws Error or subclass when value is invalid
+   * @throws {Error} Error or subclass when value is invalid
    *
    * @example
    * Custom parsing functions:
@@ -454,6 +454,13 @@ interface ArgSchema {
    */
   parse?: (value: string) => any;
 }
+/**
+ * Machine-readable error codes for {@link ArgsValidationError}.
+ *
+ * Each code identifies a validation failure category and is also suitable as an
+ * i18n resource key for localized rendering.
+ */
+
 /**
  * An object that contains {@link ArgSchema | argument schema}.
  *
@@ -535,6 +542,9 @@ type CommonArgType = {
 };
 declare const COMMON_ARGS: CommonArgType;
 declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
+declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option"];
+declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found"];
+declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
 //#endregion
 //#region ../gunshi/src/index.d.ts
 
@@ -565,14 +575,34 @@ type CommandBuiltinArgsKeys = keyof typeof COMMON_ARGS;
  * Command i18n built-in resource keys.
  */
 type CommandBuiltinResourceKeys = (typeof COMMAND_BUILTIN_RESOURCE_KEYS)[number];
+/**
+ * Args validation error resource keys.
+ */
+type ArgErrorResourceKeys = (typeof ARG_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Command validation error resource keys.
+ */
+type CommandErrorResourceKeys = (typeof COMMAND_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Suggestion error resource keys.
+ */
+type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Error resource keys.
+ */
+type ErrorResourceKeys = ArgErrorResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
-type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+/**
+ * Built-in resource.
+ */
+type BuiltinResource = Partial<Record<BuiltinResourceKeys, string>>;
 /**
  * Command built-in keys.
  */
-type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
+type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>;
 /**
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
@@ -589,7 +619,7 @@ E extends Record<string, string> = {},
 // for extended resources
 R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
   name: infer N;
-} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = CommandBuiltinKeys | O | T;
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
 //#endregion
 //#region ../shared/src/localization.d.ts
 
@@ -705,7 +735,7 @@ interface I18nPluginOptions {
   /**
    * Built-in localizable resources
    */
-  builtinResources?: Record<string, Record<BuiltinResourceKeys, string>>;
+  builtinResources?: Record<string, BuiltinResource>;
 }
 /**
  * Translation adapter factory.

package/lib/index.js

@@ -4,6 +4,7 @@ import { plugin } from "@gunshi/plugin";
 * @license MIT
 */
 const ARG_PREFIX_AND_KEY_SEPARATOR = `arg:`;
+const ERROR_PREFIX_AND_KEY_SEPARATOR = `err:`;
 const COMMON_ARGS = {
 	help: {
 		type: "boolean",
@@ -31,7 +32,15 @@ var en_US_default = {
 	DEFAULT: "default",
 	CHOICES: "choices",
 	help: "Display this help message",
-	version: "Display this version"
+	version: "Display this version",
+	"err:arg:required-option": "Optional argument {$displayName} is required",
+	"err:arg:required-positional": "Positional argument {$name} is required",
+	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
+	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
+	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
+	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
 //#region ../shared/src/utils.ts
@@ -110,6 +119,18 @@ function namespacedId(id) {
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+/**
+* Format a resource message by replacing placeholder values.
+*
+* @param resource - Resource message template
+* @param values - Placeholder values
+* @returns Formatted resource message
+*/
+function formatResource(resource, values = Object.create(null)) {
+	return resource?.replaceAll(/\{\$(\w+)\}/g, (_, name) => {
+		return values[name] == null ? "" : String(values[name]);
+	});
+}
 //#endregion
 //#region ../shared/src/index.ts
 /**
@@ -388,8 +409,11 @@ function i18n(options = {}) {
 			}
 			function translate(key, values = Object.create(null)) {
 				const strKey = key;
-				if (strKey.codePointAt(0) === BUILT_IN_PREFIX_CODE) return (localeBuiltinResources.get(localeStr) || localeBuiltinResources.get("en-US"))[strKey] || strKey;
-				else return adapter.translate(localeStr, strKey, values) || "";
+				if (isBuiltinResourceKey(strKey)) {
+					const resource = localeBuiltinResources.get(localeStr);
+					const defaultResource = localeBuiltinResources.get(DEFAULT_LOCALE);
+					return formatResource(resource?.[strKey] ?? defaultResource[strKey], values) || strKey;
+				} else return adapter.translate(localeStr, strKey, values) || "";
 			}
 			function setResource(locale, resource) {
 				const targetLocaleStr = toLocaleString(toLocale(locale));
@@ -404,7 +428,8 @@ function i18n(options = {}) {
 			}
 			for (const [locale, resource] of Object.entries(builtinResources)) for (const globalOption of builtinGlobalOptions) {
 				const globalOptionResource = builtinGlobalOptionResources[globalOption];
-				globalOptionResource[locale] = resource[globalOption];
+				const message = resource[globalOption];
+				if (message) globalOptionResource[locale] = message;
 			}
 			for (const globalOption of builtinGlobalOptions) registerGlobalOptionResources(globalOption, builtinGlobalOptionResources[globalOption]);
 			setResource(DEFAULT_LOCALE, en_US_default);
@@ -461,10 +486,14 @@ async function loadCommandResource(locale, command) {
 }
 function mapResourceWithBuiltinKey(resource, ctx, globalOptions) {
 	return Object.entries(resource).reduce((acc, [key, value]) => {
-		acc[globalOptions.includes(key) ? resolveArgKey(key, ctx.name) : resolveBuiltInKey(key)] = value;
+		if (value == null) return acc;
+		acc[key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR) ? key : globalOptions.includes(key) ? resolveArgKey(key, ctx.name) : resolveBuiltInKey(key)] = value;
 		return acc;
 	}, Object.create(null));
 }
+function isBuiltinResourceKey(key) {
+	return key.codePointAt(0) === BUILT_IN_PREFIX_CODE || key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR);
+}
 function hasI18nResource(command) {
 	return "resource" in command && typeof command.resource === "function";
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-i18n",
   "description": "internationalization plugin for gunshi",
-  "version": "0.35.1",
+  "version": "0.35.3",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.35.1"
+    "@gunshi/plugin": "0.35.3"
   },
   "peerDependencies": {
-    "@gunshi/plugin-global": "0.35.1"
+    "@gunshi/plugin-global": "0.35.3"
   },
   "peerDependenciesMeta": {
     "@gunshi/plugin-global": {
@@ -71,12 +71,12 @@
     "messageformat": "4.0.0",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "@gunshi/bone": "0.35.1",
-    "@gunshi/plugin-global": "0.35.1",
-    "@gunshi/plugin-renderer": "0.35.1",
-    "@gunshi/resources": "0.35.1",
-    "@gunshi/shared": "0.35.1",
-    "gunshi": "0.35.1"
+    "@gunshi/bone": "0.35.3",
+    "@gunshi/plugin-global": "0.35.3",
+    "@gunshi/plugin-renderer": "0.35.3",
+    "@gunshi/resources": "0.35.3",
+    "@gunshi/shared": "0.35.3",
+    "gunshi": "0.35.3"
   },
   "scripts": {
     "build": "tsdown",