gunshi 0.7.0 → 0.8.0

package/lib/{context-CEZVz8Dg.js → context-DYokJ5k3.js}

@@ -1,4 +1,4 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, create, deepFreeze, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-B39blQOf.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, create, deepFreeze, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-CU_LSsUg.js";
 
 //#region locales/en-US.json
 var COMMAND = "COMMAND";
@@ -22,6 +22,40 @@ var en_US_default = {
 	version
 };
 
+//#endregion
+//#region src/translation.ts
+function createTranslationAdapter(options) {
+	return new DefaultTranslation(options);
+}
+var DefaultTranslation = class {
+	#resources = new Map();
+	options;
+	constructor(options) {
+		this.options = options;
+		this.#resources = new Map();
+	}
+	getResource(locale) {
+		return this.#resources.get(locale);
+	}
+	setResource(locale, resource) {
+		this.#resources.set(locale, resource);
+	}
+	getMessage(locale, key) {
+		const resource = this.getResource(locale);
+		if (resource) return resource[key];
+		return undefined;
+	}
+	translate(locale, key, _values = create()) {
+		/**
+		* NOTE:
+		* DefaultTranslation support static message only
+		* If you want to resolve message with values and use the complex message format,
+		* you should inherit this class or implement your own translation adapter.
+		*/
+		return this.getMessage(locale, key) || this.getMessage(this.options.fallbackLocale, key);
+	}
+};
+
 //#endregion
 //#region src/context.ts
 const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
@@ -48,8 +82,12 @@ async function createCommandContext({ options, values, positionals, command, com
 	*/
 	const env = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, commandOptions);
 	const locale = resolveLocale(commandOptions.locale);
+	const translationAdapterFactory = commandOptions.translationAdapterFactory || createTranslationAdapter;
+	const adapter = translationAdapterFactory({
+		locale: locale.toString(),
+		fallbackLocale: DEFAULT_LOCALE
+	});
 	const localeResources = new Map();
-	const commandResources = new Map();
 	let builtInLoadedResources;
 	/**
 	* load the built-in locale resources
@@ -63,14 +101,12 @@ async function createCommandContext({ options, values, positionals, command, com
 	* define the translation function, which is used to {@link CommandContext.translate}.
 	*
 	*/
-	function translate(key) {
-		if (key.codePointAt(0) === BUILT_IN_PREFIX_CODE) {
+	function translate(key, values$1 = create()) {
+		const strKey = key;
+		if (strKey.codePointAt(0) === BUILT_IN_PREFIX_CODE) {
 			const resource = localeResources.get(locale.toString()) || localeResources.get(DEFAULT_LOCALE);
-			return resource[key] || key;
-		} else {
-			const resource = commandResources.get(locale.toString()) || commandResources.get(DEFAULT_LOCALE);
-			return resource[key] || "";
-		}
+			return resource[strKey] || strKey;
+		} else return adapter.translate(locale.toString(), strKey, values$1) || "";
 	}
 	/**
 	* load the sub commands
@@ -110,7 +146,7 @@ async function createCommandContext({ options, values, positionals, command, com
 	}, create());
 	defaultCommandResource.description = command.description || "";
 	defaultCommandResource.examples = usage.examples || "";
-	commandResources.set(DEFAULT_LOCALE, defaultCommandResource);
+	adapter.setResource(DEFAULT_LOCALE, defaultCommandResource);
 	const originalResource = await loadCommandResource(ctx, command);
 	if (originalResource) {
 		const resource = Object.assign(create(), {
@@ -121,7 +157,7 @@ async function createCommandContext({ options, values, positionals, command, com
 			resource.help = builtInLoadedResources.help;
 			resource.version = builtInLoadedResources.version;
 		}
-		commandResources.set(locale.toString(), resource);
+		adapter.setResource(locale.toString(), resource);
 	}
 	return ctx;
 }
@@ -137,4 +173,4 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { createCommandContext };
+export { DefaultTranslation, createCommandContext };

package/lib/context.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-BvzTOO8I.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CX4RmDVT.js';
 
 /**
 * Parameters of {@link createCommandContext}

package/lib/context.js

@@ -1,4 +1,4 @@
-import { createCommandContext } from "./context-CEZVz8Dg.js";
-import "./utils-B39blQOf.js";
+import { createCommandContext } from "./context-DYokJ5k3.js";
+import "./utils-CU_LSsUg.js";
 
 export { createCommandContext };

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-BvzTOO8I.js';
-export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, h as CommandResource, i as CommandResourceFetcher, j as Commandable, G as GenerateNamespacedKey, L as LazyCommand } from './types.d-BvzTOO8I.js';
+import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-CX4RmDVT.js';
+export { g as CommandBuiltinKeys, e as CommandBuiltinOptionsKeys, f as CommandBuiltinResourceKeys, b as CommandContext, h as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-CX4RmDVT.js';
 
 /**
 * Run the command
@@ -11,4 +11,14 @@ export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBu
 */
 declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 
-export { Command, CommandOptions, CommandRunner, cli };
+declare class DefaultTranslation implements TranslationAdapter {
+	#private;
+	options: TranslationAdapterFactoryOptions;
+	constructor(options: TranslationAdapterFactoryOptions);
+	getResource(locale: string): Record<string, string> | undefined;
+	setResource(locale: string, resource: Record<string, string>): void;
+	getMessage(locale: string, key: string): string | undefined;
+	translate(locale: string, key: string, _values?: Record<string, unknown>): string | undefined;
+}
+
+export { Command, CommandOptions, CommandRunner, DefaultTranslation, TranslationAdapter, TranslationAdapterFactoryOptions, cli };

package/lib/index.js

@@ -1,6 +1,6 @@
-import { createCommandContext } from "./context-CEZVz8Dg.js";
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, log, resolveLazyCommand } from "./utils-B39blQOf.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-CD-yc-xk.js";
+import { DefaultTranslation, createCommandContext } from "./context-DYokJ5k3.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, log, resolveLazyCommand } from "./utils-CU_LSsUg.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-KLx2dW-W.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.ts
@@ -93,4 +93,4 @@ async function resolveCommand(sub, entry, options) {
 }
 
 //#endregion
-export { cli };
+export { DefaultTranslation, cli };

package/lib/renderer/index.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-BvzTOO8I.js';
+import { b as CommandContext } from '../types.d-CX4RmDVT.js';
 
 /**
 * Render the header

package/lib/renderer/index.js

@@ -1,4 +1,4 @@
-import "../utils-B39blQOf.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-CD-yc-xk.js";
+import "../utils-CU_LSsUg.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-KLx2dW-W.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{renderer-CD-yc-xk.js → renderer-KLx2dW-W.js}

@@ -1,4 +1,4 @@
-import { create, resolveBuiltInKey } from "./utils-B39blQOf.js";
+import { create, resolveBuiltInKey } from "./utils-CU_LSsUg.js";
 
 //#region src/renderer/header.ts
 function renderHeader(ctx) {

package/lib/{types.d-BvzTOO8I.d.ts → types.d-CX4RmDVT.d.ts}

@@ -168,6 +168,11 @@ interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	* Render function the validation errors
 	*/
 	renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
+	/**
+	* Translation adapter factory
+	* @experimental
+	*/
+	translationAdapterFactory?: TranslationAdapterFactory;
 }
 /**
 * Command context
@@ -229,13 +234,14 @@ interface CommandContext<
 	/**
 	* Translate function
 	* @param key the key to be translated
+	* @param values the values to be formatted
 	* @returns A translated string
 	* @experimental
 	*/
 	translate: <
 		T extends string = CommandBuiltinKeys,
 		Key = CommandBuiltinKeys | keyof Options | T
-	>(key: Key) => string;
+	>(key: Key, values?: Record<string, unknown>) => string;
 }
 /**
 * Command usage
@@ -315,6 +321,59 @@ type CommandResource<Options extends ArgOptions = ArgOptions> = {
 */
 type CommandResourceFetcher<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
 /**
+* Translation adapter factory
+*/
+type TranslationAdapterFactory = (options: TranslationAdapterFactoryOptions) => TranslationAdapter;
+/**
+* Translation adapter factory options
+*/
+interface TranslationAdapterFactoryOptions {
+	/**
+	* A locale
+	*/
+	locale: string;
+	/**
+	* A fallback locale
+	*/
+	fallbackLocale: string;
+}
+/**
+* Translation adapter
+*
+* @description
+* This adapter is used to custom message formatter like {@link https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf | Intlify message format}, {@link https://github.com/tc39/proposal-intl-messageformat | `Intl.MessageFormat` (MF2)}, and etc.
+* This adapter will support localization with your preferred message format
+*/
+interface TranslationAdapter<MessageResource = string> {
+	/**
+	* Get a resource of locale
+	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+	* @returns A resource of locale. if resource not found, return `undefined`
+	*/
+	getResource(locale: string): Record<string, string> | undefined;
+	/**
+	* Set a resource of locale
+	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+	* @param resource A resource of locale
+	*/
+	setResource(locale: string, resource: Record<string, string>): void;
+	/**
+	* Get a message of locale
+	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+	* @param key A key of message resource
+	* @returns A message of locale. if message not found, return `undefined`
+	*/
+	getMessage(locale: string, key: string): MessageResource | undefined;
+	/**
+	* Translate a message
+	* @param locale A Locale at the time of command execution. That is Unicord locale ID (BCP 47)
+	* @param key A key of message resource
+	* @param values A values to be resolved in the message
+	* @returns A translated message, if message is not translated, return `undefined`
+	*/
+	translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
+}
+/**
 * Command runner
 * @param ctx A {@link CommandContext | command context}
 */
@@ -329,4 +388,4 @@ type LazyCommand<Options extends ArgOptions = ArgOptions> = () => Awaitable<Comm
 */
 type Commandable<Options extends ArgOptions> = Command<Options> | LazyCommand<Options>;
 
-export type { Command as C, GenerateNamespacedKey as G, LazyCommand as L, CommandOptions as a, CommandContext as b, CommandRunner as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandResource as h, CommandResourceFetcher as i, Commandable as j };
+export type { Command as C, GenerateNamespacedKey as G, LazyCommand as L, TranslationAdapter as T, CommandOptions as a, CommandContext as b, CommandRunner as c, TranslationAdapterFactoryOptions as d, CommandBuiltinOptionsKeys as e, CommandBuiltinResourceKeys as f, CommandBuiltinKeys as g, CommandEnvironment as h, CommandResource as i, CommandResourceFetcher as j, TranslationAdapterFactory as k, Commandable as l };

package/lib/{utils-B39blQOf.js → utils-CU_LSsUg.js}

@@ -24,7 +24,8 @@ const COMMAND_OPTIONS_DEFAULT = {
 	usageOptionType: false,
 	renderHeader: undefined,
 	renderUsage: undefined,
-	renderValidationErrors: undefined
+	renderValidationErrors: undefined,
+	translationAdapterFactory: undefined
 };
 
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -71,6 +71,7 @@
   },
   "devDependencies": {
     "@eslint/markdown": "^6.2.2",
+    "@intlify/core": "next",
     "@kazupon/eslint-config": "^0.22.0",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.13.9",
@@ -87,6 +88,7 @@
     "jsr": "^0.13.4",
     "knip": "^5.45.0",
     "lint-staged": "^15.4.3",
+    "messageformat": "4.0.0-9",
     "pkg-pr-new": "^0.0.41",
     "prettier": "^3.5.3",
     "tsdown": "^0.6.4",