@gunshi/plugin-i18n 1.0.0-rc.5 → 1.0.0-rc.6

package/README.md

@@ -108,6 +108,7 @@ This means:
 - If you're using the globals plugin (which adds `--help` and `--version` options), the i18n plugin will automatically handle their translations
 - The translations for "Display this help message" and "Display this version" will be available in your configured locale
 - You can override these translations by providing your own `help` and `version` keys in your built-in resources
+- The description of `--json` of a command that spreads `jsonArgs` ("Output the result as JSON") is translated by the `json` key of the built-in resources in the same way, unless the resource of the command has its own `arg:json`
 
 Example with globals plugin:
 

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, PluginWithExtension, Prettify } from "@gunshi/plugin";
+import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, PluginWithExtension, Prettify, SubCommandable } from "@gunshi/plugin";
 //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -623,11 +623,13 @@ 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 COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES", "CAUSEDBY"];
 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", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
 declare const ARG_ERROR_HINT_RESOURCE_KEYS: readonly ["err:arg:missing-value:hint"];
 declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
+declare const JSON_RESOURCE_KEYS: readonly ["json", "json:invalid-arguments", "json:next:help", "json:next:help-placeholder"];
+declare const JSON_ERROR_RESOURCE_KEYS: readonly ["err:json:not-supported", "err:json:invalid-result", "err:json:unserializable-result"];
 //#endregion
 //#region ../shared/src/types.d.ts
 type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
@@ -667,14 +669,23 @@ type CommandErrorResourceKeys = (typeof COMMAND_ERROR_RESOURCE_KEYS)[number];
  * Suggestion error resource keys.
  */
 type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the errors of the JSON output.
+ */
+type JsonErrorResourceKeys = (typeof JSON_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the description of the `json` argument of `jsonArgs`, and of the texts that only
+ * the JSON errors print.
+ */
+type JsonResourceKeys = (typeof JSON_RESOURCE_KEYS)[number];
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys | JsonErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
-type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys | JsonResourceKeys;
 /**
  * Built-in resource.
  */
@@ -916,7 +927,7 @@ type I18nCommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunsh
  *
  * @internal
  */
-type WithI18nResourceResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> = Command<G>> = Prettify<C & {
+type WithI18nResourceResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> | SubCommandable = Command<G>> = Prettify<C & {
   resource: CommandResourceFetcher<G>;
 } & { [K in Exclude<keyof I18nCommand<G>, keyof C | 'resource'>]?: I18nCommand<G>[K]; }>;
 /**
@@ -1065,7 +1076,7 @@ declare function defineI18nWithTypes<G extends GunshiParamsConstraint>(): Define
  * @param resource - A {@link CommandResourceFetcher | resource fetcher} for the command
  * @returns A {@link I18nCommand | command} with i18n resource support
  */
-declare function withI18nResource<G extends GunshiParamsConstraint, C extends Command<G>>(command: C, resource: CommandResourceFetcher<G>): WithI18nResourceResult<G, C>;
+declare function withI18nResource<G extends GunshiParamsConstraint, C extends Command<G> | SubCommandable>(command: C, resource: CommandResourceFetcher<G>): WithI18nResourceResult<G, C>;
 //#endregion
 //#region src/translation.d.ts
 /**

package/lib/index.js

@@ -3,6 +3,25 @@ import { plugin } from "@gunshi/plugin";
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+//#endregion
+//#region ../gunshi/src/utils.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Check whether an argument schema is the `json` argument of `jsonArgs`, by its mark.
+*
+* @param schema - An argument schema
+* @returns `true` if the schema has the mark of `jsonArgs`
+*/
+function isJsonArg(schema) {
+	return typeof schema === "object" && schema !== null && schema["~gunshi.json-arg"] === true;
+}
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 const ARG_PREFIX_AND_KEY_SEPARATOR = `arg:`;
 const ERROR_PREFIX_AND_KEY_SEPARATOR = `err:`;
 const COMMON_ARGS = {
@@ -31,8 +50,13 @@ var en_US_default = {
 	NEGATABLE: "Negatable of",
 	DEFAULT: "default",
 	CHOICES: "choices",
+	CAUSEDBY: "Caused by",
 	help: "Display this help message",
 	version: "Display this version",
+	json: "Output the result as JSON",
+	"json:invalid-arguments": "{$count} arguments are invalid",
+	"json:next:help": "See the arguments of the command",
+	"json:next:help-placeholder": "Replace <COMMAND> with how you ran this CLI, to see the arguments of the command",
 	"err:arg:required-option": "Option {$displayName} is required",
 	"err:arg:required-positional": "Positional argument {$displayName} is required",
 	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
@@ -48,6 +72,9 @@ var en_US_default = {
 	"err:cmd:ambiguous": "The command is ambiguous. Move options after the command name: {$candidatePaths}",
 	"err:cmd:inconsistent-options": "The options do not identify a consistent command. Move options after the command name.",
 	"err:cmd:lazy-schema-mismatch": "The lazy command definition does not match its loaded options. Declare leading options in the lazy definition or move options after the command name: {$commandPath}",
+	"err:json:not-supported": "This command does not support --json",
+	"err:json:invalid-result": "The command finished, but did not return an object to output as JSON. A plugin that decorates the command may have dropped its result",
+	"err:json:unserializable-result": "The command finished, but its result cannot be converted to JSON: {$message}",
 	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
@@ -139,6 +166,11 @@ function formatResource(resource, values = Object.create(null)) {
 		return values[name] == null ? "" : String(values[name]);
 	});
 }
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+namespacedId("i18n");
 //#endregion
 //#region ../shared/src/index.ts
 /**
@@ -449,6 +481,16 @@ function i18n(options = {}) {
 				if (originalResource) loaded = true;
 				const localeStr = toLocaleString(locale);
 				const resource = originalResource ? await normalizeResource(originalResource, ctx) : Object.create(null);
+				/**
+				* NOTE(kazupon): the `json` argument of `jsonArgs` is described by the built-in resources, as the
+				* global options are, unless the resource of the command describes it. A command without a
+				* translation of its own keeps the English description of `jsonArgs`.
+				*/
+				if (isJsonArg(ctx.args.json)) {
+					const jsonKey = resolveArgKey("json", ctx.name);
+					const description = builtinResources[localeStr]?.json;
+					if (resource[jsonKey] === void 0 && description) resource[jsonKey] = description;
+				}
 				for (const globalOption of getGlobalOptions()) if (globalOptionResources.has(globalOption)) {
 					const optionResource = globalOptionResources.get(globalOption);
 					const globalOptionKey = resolveArgKey(globalOption, ctx.name);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-i18n",
   "description": "internationalization plugin for gunshi",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-rc.5"
+    "@gunshi/plugin": "1.0.0-rc.6"
   },
   "peerDependencies": {
-    "@gunshi/plugin-global": "1.0.0-rc.5"
+    "@gunshi/plugin-global": "1.0.0-rc.6"
   },
   "peerDependenciesMeta": {
     "@gunshi/plugin-global": {
@@ -64,13 +64,13 @@
     }
   },
   "devDependencies": {
-    "@gunshi/bone": "1.0.0-rc.5",
-    "@gunshi/plugin-global": "1.0.0-rc.5",
-    "@gunshi/plugin-renderer": "1.0.0-rc.5",
-    "@gunshi/resources": "1.0.0-rc.5",
-    "@gunshi/shared": "1.0.0-rc.5",
+    "@gunshi/bone": "1.0.0-rc.6",
+    "@gunshi/plugin-global": "1.0.0-rc.6",
+    "@gunshi/plugin-renderer": "1.0.0-rc.6",
+    "@gunshi/resources": "1.0.0-rc.6",
+    "@gunshi/shared": "1.0.0-rc.6",
     "@intlify/core-base": "12.0.0-alpha.7",
-    "gunshi": "1.0.0-rc.5",
+    "gunshi": "1.0.0-rc.6",
     "messageformat": "4.1.0",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"