gunshi 0.6.2 → 0.8.0

package/README.md

@@ -317,7 +317,7 @@ const customUsageRenderer = ctx => {
 
   for (const [key, option] of Object.entries(ctx.options || Object.create(null))) {
     const shortFlag = option.short ? `-${option.short}, ` : '    '
-    lines.push(`  ${shortFlag}--${key.padEnd(10)} ${ctx.translation(key)}`)
+    lines.push(`  ${shortFlag}--${key.padEnd(10)} ${ctx.translate(key)}`)
   }
 
   return Promise.resolve(lines.join('\n'))
@@ -365,7 +365,7 @@ const command = {
   },
   run: ctx => {
     const { name = 'World', formal } = ctx.values
-    const greeting = formal ? ctx.translation('formal') : ctx.translation('informal')
+    const greeting = formal ? ctx.translate('formal_greeting') : ctx.translate('informal_greeting')
     console.log(`${greeting}, ${name}!`)
   }
 }

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

@@ -1,4 +1,4 @@
-import { create, deepFreeze, resolveLazyCommand } from "./utils-NHs5DuHk.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";
@@ -23,48 +23,47 @@ var en_US_default = {
 };
 
 //#endregion
-//#region src/constants.ts
-const COMMON_OPTIONS = {
-	help: {
-		type: "boolean",
-		short: "h"
-	},
-	version: {
-		type: "boolean",
-		short: "v"
+//#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);
 	}
 };
-const COMMAND_OPTIONS_DEFAULT = {
-	name: undefined,
-	description: undefined,
-	version: undefined,
-	cwd: undefined,
-	subCommands: undefined,
-	leftMargin: 2,
-	middleMargin: 10,
-	usageOptionType: false,
-	renderHeader: undefined,
-	renderUsage: undefined,
-	renderValidationErrors: undefined
-};
-const COMMAND_I18N_RESOURCE_KEYS = [
-	"USAGE",
-	"COMMAND",
-	"SUBCOMMAND",
-	"COMMANDS",
-	"OPTIONS",
-	"EXAMPLES",
-	"FORMORE"
-];
 
 //#endregion
 //#region src/context.ts
-const DEFAULT_LOCALE = "en-US";
+const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
 async function createCommandContext({ options, values, positionals, command, commandOptions, omitted = false }) {
 	/**
 	* tweak the options and values
 	*/
-	const _options = options == null ? undefined : Object.entries(options).reduce((acc, [key, value]) => {
+	const _options = Object.entries(options).reduce((acc, [key, value]) => {
 		acc[key] = Object.assign(create(), value);
 		return acc;
 	}, create());
@@ -83,29 +82,31 @@ 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
 	*/
-	localeResources.set(DEFAULT_LOCALE, en_US_default);
+	localeResources.set(DEFAULT_LOCALE, mapResourceWithBuiltinKey(en_US_default));
 	if (DEFAULT_LOCALE !== locale.toString()) try {
 		builtInLoadedResources = await import(`../locales/${locale.toString()}.json`, { with: { type: "json" } });
-		localeResources.set(locale.toString(), builtInLoadedResources);
+		localeResources.set(locale.toString(), mapResourceWithBuiltinKey(builtInLoadedResources));
 	} catch {}
 	/**
-	* define the translation function, which is used to {@link CommandContext.translation}.
+	* define the translation function, which is used to {@link CommandContext.translate}.
 	*
 	*/
-	function translation(key) {
-		if (COMMAND_I18N_RESOURCE_KEYS.includes(key)) {
+	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
@@ -130,7 +131,7 @@ async function createCommandContext({ options, values, positionals, command, com
 		positionals,
 		usage,
 		loadCommands,
-		translation
+		translate
 	}));
 	/**
 	* load the command resources
@@ -145,21 +146,18 @@ 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.entries(originalResource.options).reduce((res, [key, value]) => {
-			res[key] = value;
-			return res;
-		}, Object.assign(create(), {
+		const resource = Object.assign(create(), {
 			description: originalResource.description,
 			examples: originalResource.examples
-		}));
+		}, originalResource);
 		if (builtInLoadedResources) {
 			resource.help = builtInLoadedResources.help;
 			resource.version = builtInLoadedResources.version;
 		}
-		commandResources.set(locale.toString(), resource);
+		adapter.setResource(locale.toString(), resource);
 	}
 	return ctx;
 }
@@ -175,4 +173,4 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, createCommandContext };
+export { DefaultTranslation, createCommandContext };

package/lib/context.d.ts

@@ -1,10 +1,6 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CxaX4FVV.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CX4RmDVT.js';
 
-/**
-* The default locale string, which format is BCP 47 language tag
-*/
-declare const DEFAULT_LOCALE = "en-US";
 /**
 * Parameters of {@link createCommandContext}
 */
@@ -15,7 +11,7 @@ interface CommandContextParams<
 	/**
 	* An options of target command
 	*/
-	options: Options | undefined;
+	options: Options;
 	/**
 	* A values of target command
 	*/
@@ -47,4 +43,4 @@ declare function createCommandContext<
 	Values = ArgValues<Options>
 >({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 
-export { DEFAULT_LOCALE, createCommandContext };
+export { createCommandContext };

package/lib/context.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LOCALE, createCommandContext } from "./context-DmZAeiph.js";
-import "./utils-NHs5DuHk.js";
+import { createCommandContext } from "./context-DYokJ5k3.js";
+import "./utils-CU_LSsUg.js";
 
-export { DEFAULT_LOCALE, createCommandContext };
+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-CxaX4FVV.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, L as LazyCommand } from './types.d-CxaX4FVV.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 { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-DmZAeiph.js";
-import { create, log, resolveLazyCommand } from "./utils-NHs5DuHk.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-v5Uq0km9.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
@@ -45,7 +45,8 @@ function resolveArgOptions(options) {
 function resolveCommandOptions(options, entry) {
 	const subCommands = new Map(options.subCommands);
 	if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
-	return Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	return resolvedOptions;
 }
 function getSubCommand(tokens) {
 	const firstToken = tokens[0];
@@ -92,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-CxaX4FVV.js';
+import { b as CommandContext } from '../types.d-CX4RmDVT.js';
 
 /**
 * Render the header

package/lib/renderer/index.js

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

package/lib/{renderer-v5Uq0km9.js → renderer-KLx2dW-W.js}

@@ -1,4 +1,4 @@
-import { create } from "./utils-NHs5DuHk.js";
+import { create, resolveBuiltInKey } from "./utils-CU_LSsUg.js";
 
 //#region src/renderer/header.ts
 function renderHeader(ctx) {
@@ -27,9 +27,8 @@ async function renderUsage(ctx) {
 */
 async function renderOptionsSection(ctx) {
 	const messages = [];
-	messages.push(`${ctx.translation("OPTIONS")}:`);
-	const optionsPairs = getOptionsPairs(ctx);
-	messages.push(await generateOptionsUsage(ctx, optionsPairs));
+	messages.push(`${ctx.translate(resolveBuiltInKey("OPTIONS"))}:`);
+	messages.push(await generateOptionsUsage(ctx, getOptionsPairs(ctx)));
 	return messages;
 }
 /**
@@ -40,7 +39,7 @@ async function renderOptionsSection(ctx) {
 function renderExamplesSection(ctx) {
 	const messages = [];
 	const examples = ctx.usage.examples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
-	messages.push(`${ctx.translation("EXAMPLES")}:`, ...examples);
+	messages.push(`${ctx.translate(resolveBuiltInKey("EXAMPLES"))}:`, ...examples);
 	return messages;
 }
 /**
@@ -49,12 +48,12 @@ function renderExamplesSection(ctx) {
 * @returns A rendered usage section
 */
 async function renderUsageSection(ctx) {
-	const messages = [`${ctx.translation("USAGE")}:`];
+	const messages = [`${ctx.translate(resolveBuiltInKey("USAGE"))}:`];
 	if (ctx.omitted) {
-		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${hasOptions(ctx) ? `<${ctx.translation("OPTIONS")}>` : ""} `;
+		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${hasOptions(ctx) ? `<${ctx.translate(resolveBuiltInKey("OPTIONS"))}>` : ""} `;
 		messages.push(defaultCommand.padStart(ctx.env.leftMargin + defaultCommand.length));
 		if (await hasCommands(ctx)) {
-			const commandsUsage = `${resolveEntry(ctx)} <${ctx.translation("COMMANDS")}>`;
+			const commandsUsage = `${resolveEntry(ctx)} <${ctx.translate(resolveBuiltInKey("COMMANDS"))}>`;
 			messages.push(commandsUsage.padStart(ctx.env.leftMargin + commandsUsage.length));
 		}
 	} else {
@@ -69,7 +68,7 @@ async function renderUsageSection(ctx) {
 * @returns A rendered commands section
 */
 async function renderCommandsSection(ctx) {
-	const messages = [`${ctx.translation("COMMANDS")}:`];
+	const messages = [`${ctx.translate(resolveBuiltInKey("COMMANDS"))}:`];
 	const loadedCommands = await ctx.loadCommands();
 	const commandMaxLength = Math.max(...loadedCommands.map((cmd) => (cmd.name || "").length));
 	const commandsStr = await Promise.all(loadedCommands.map((cmd) => {
@@ -78,7 +77,7 @@ async function renderCommandsSection(ctx) {
 		const command = `${key.padEnd(commandMaxLength + ctx.env.middleMargin)}${desc} `;
 		return `${command.padStart(ctx.env.leftMargin + command.length)} `;
 	}));
-	messages.push(...commandsStr, "", ctx.translation("FORMORE"));
+	messages.push(...commandsStr, "", ctx.translate(resolveBuiltInKey("FORMORE")));
 	messages.push(...loadedCommands.map((cmd) => {
 		const commandHelp = `${ctx.env.name} ${cmd.name} --help`;
 		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
@@ -91,7 +90,7 @@ async function renderCommandsSection(ctx) {
 * @returns The entry command name
 */
 function resolveEntry(ctx) {
-	return ctx.env.name || ctx.translation("COMMAND");
+	return ctx.env.name || ctx.translate(resolveBuiltInKey("COMMAND"));
 }
 /**
 * Resolve the sub command name
@@ -99,7 +98,7 @@ function resolveEntry(ctx) {
 * @returns The sub command name
 */
 function resolveSubCommand(ctx) {
-	return ctx.name || ctx.translation("SUBCOMMAND");
+	return ctx.name || ctx.translate(resolveBuiltInKey("SUBCOMMAND"));
 }
 /**
 * Resolve the command description
@@ -107,7 +106,7 @@ function resolveSubCommand(ctx) {
 * @returns resolved command description
 */
 function resolveDescription(ctx) {
-	return ctx.translation("description") || ctx.description || "";
+	return ctx.translate("description") || ctx.description || "";
 }
 /**
 * Check if the command has sub commands
@@ -148,7 +147,7 @@ function hasAllDefaultOptions(ctx) {
 * @returns Options symbols for usage
 */
 function generateOptionsSymbols(ctx) {
-	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translation("OPTIONS")}]` : `<${ctx.translation("OPTIONS")}>` : "";
+	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translate("_:OPTIONS")}]` : `<${ctx.translate("_:OPTIONS")}>` : "";
 }
 /**
 * Get options pairs for usage
@@ -174,7 +173,7 @@ async function generateOptionsUsage(ctx, optionsPairs) {
 	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
 	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key, _]) => ctx.options[key].type.length)) : 0;
 	const usages = await Promise.all(Object.entries(optionsPairs).map(([key, value]) => {
-		const rawDesc = ctx.translation(key);
+		const rawDesc = ctx.translate(key);
 		const optionsSchema = ctx.env.usageOptionType ? `[${ctx.options[key].type}] ` : "";
 		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
 		const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}`;

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

@@ -1,5 +1,11 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
 
+/**
+* The default locale string, which format is BCP 47 language tag
+*/
+declare const DEFAULT_LOCALE = "en-US";
+declare const BUILT_IN_PREFIX = "_";
+declare const BUILT_IN_KEY_SEPARATOR = ":";
 type CommonOptionType = {
 	readonly help: {
 		readonly type: "boolean"
@@ -12,19 +18,26 @@ type CommonOptionType = {
 };
 declare const COMMON_OPTIONS: CommonOptionType;
 declare const COMMAND_OPTIONS_DEFAULT: CommandOptions<ArgOptions>;
-declare const COMMAND_I18N_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "OPTIONS", "EXAMPLES", "FORMORE"];
+declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "OPTIONS", "EXAMPLES", "FORMORE"];
 
-declare const __constants_COMMAND_I18N_RESOURCE_KEYS: typeof COMMAND_I18N_RESOURCE_KEYS;
+declare const __constants_BUILT_IN_KEY_SEPARATOR: typeof BUILT_IN_KEY_SEPARATOR;
+declare const __constants_BUILT_IN_PREFIX: typeof BUILT_IN_PREFIX;
+declare const __constants_COMMAND_BUILTIN_RESOURCE_KEYS: typeof COMMAND_BUILTIN_RESOURCE_KEYS;
 declare const __constants_COMMAND_OPTIONS_DEFAULT: typeof COMMAND_OPTIONS_DEFAULT;
 declare const __constants_COMMON_OPTIONS: typeof COMMON_OPTIONS;
+declare const __constants_DEFAULT_LOCALE: typeof DEFAULT_LOCALE;
 declare namespace __constants {
-  export { __constants_COMMAND_I18N_RESOURCE_KEYS as COMMAND_I18N_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS };
+  export { __constants_BUILT_IN_KEY_SEPARATOR as BUILT_IN_KEY_SEPARATOR, __constants_BUILT_IN_PREFIX as BUILT_IN_PREFIX, __constants_COMMAND_BUILTIN_RESOURCE_KEYS as COMMAND_BUILTIN_RESOURCE_KEYS, __constants_COMMAND_OPTIONS_DEFAULT as COMMAND_OPTIONS_DEFAULT, __constants_COMMON_OPTIONS as COMMON_OPTIONS, __constants_DEFAULT_LOCALE as DEFAULT_LOCALE };
 }
 
 /**
 * Define a promise type that can be await from T
 */
 type Awaitable<T> = T | Promise<T>;
+type GenerateNamespacedKey<
+	Key extends string,
+	Prefixed extends string = typeof BUILT_IN_PREFIX
+> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
 /**
 * Command i18n built-in options keys
 * @experimental
@@ -34,13 +47,13 @@ type CommandBuiltinOptionsKeys = keyof (typeof __constants)["COMMON_OPTIONS"];
 * Command i18n built-in resource keys
 * @experimental
 */
-type CommandBuiltinResourceKeys = (typeof __constants)["COMMAND_I18N_RESOURCE_KEYS"][number];
+type CommandBuiltinResourceKeys = (typeof __constants)["COMMAND_BUILTIN_RESOURCE_KEYS"][number];
 /**
 * Command i18n built-in keys
-* @description The command i18n built-in keys are used to {@link CommandContext.translation | translate} function
+* @description The command i18n built-in keys are used to {@link CommandContext.translate | translate} function
 * @experimental
 */
-type CommandBuiltinKeys = CommandBuiltinOptionsKeys | CommandBuiltinResourceKeys | "description" | "examples";
+type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinOptionsKeys> | GenerateNamespacedKey<CommandBuiltinResourceKeys> | "description" | "examples";
 /**
 * Command environment
 */
@@ -155,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
@@ -187,7 +205,7 @@ interface CommandContext<
 	* Command options, that is the options of the command that is executed
 	* @description The command options is same {@link Command.options}
 	*/
-	options: Options | undefined;
+	options: Options;
 	/**
 	* Command values, that is the values of the command that is executed
 	* @description Resolve values with `resolveArgs` from command arguments and {@link Command.options}
@@ -214,15 +232,16 @@ interface CommandContext<
 	*/
 	loadCommands: () => Promise<Command<Options>[]>;
 	/**
-	* Translation function
+	* Translate function
 	* @param key the key to be translated
+	* @param values the values to be formatted
 	* @returns A translated string
 	* @experimental
 	*/
-	translation: <
-		T = CommandBuiltinKeys,
-		Key = CommandBuiltinKeys | T
-	>(key: Key) => string;
+	translate: <
+		T extends string = CommandBuiltinKeys,
+		Key = CommandBuiltinKeys | keyof Options | T
+	>(key: Key, values?: Record<string, unknown>) => string;
 }
 /**
 * Command usage
@@ -282,20 +301,18 @@ interface Command<Options extends ArgOptions = ArgOptions> {
 * Command resource
 * @experimental
 */
-interface CommandResource<Options extends ArgOptions = ArgOptions> {
+type CommandResource<Options extends ArgOptions = ArgOptions> = {
 	/**
 	* Command description
 	*/
-	description: string;
-	/**
-	* Options usage
-	*/
-	options: { [Option in keyof Options] : string };
+	description: string
 	/**
 	* Examples usage
 	*/
-	examples: string;
-}
+	examples: string
+} & { [Option in keyof Options] : string } & {
+	[key: string]: string
+};
 /**
 * Command resource fetcher
 * @param ctx A {@link CommandContext | command context}
@@ -304,6 +321,59 @@ interface 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}
 */
@@ -318,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, 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-CU_LSsUg.js

@@ -0,0 +1,63 @@
+
+//#region src/constants.ts
+const DEFAULT_LOCALE = "en-US";
+const BUILT_IN_PREFIX = "_";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const COMMON_OPTIONS = {
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	version: {
+		type: "boolean",
+		short: "v"
+	}
+};
+const COMMAND_OPTIONS_DEFAULT = {
+	name: undefined,
+	description: undefined,
+	version: undefined,
+	cwd: undefined,
+	subCommands: undefined,
+	leftMargin: 2,
+	middleMargin: 10,
+	usageOptionType: false,
+	renderHeader: undefined,
+	renderUsage: undefined,
+	renderValidationErrors: undefined,
+	translationAdapterFactory: undefined
+};
+
+//#endregion
+//#region src/utils.ts
+async function resolveLazyCommand(cmd, name, entry = false) {
+	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd, { default: entry });
+	if (resolved.name == null && name) resolved.name = name;
+	return deepFreeze(resolved);
+}
+function resolveBuiltInKey(key) {
+	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+function mapResourceWithBuiltinKey(resource) {
+	return Object.entries(resource).reduce((acc, [key, value]) => {
+		acc[resolveBuiltInKey(key)] = value;
+		return acc;
+	}, create());
+}
+function create(obj = null) {
+	return Object.create(obj);
+}
+function log(...args) {
+	console.log(...args);
+}
+function deepFreeze(obj) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (typeof value === "object" && value !== null) deepFreeze(value);
+	}
+	return Object.freeze(obj);
+}
+
+//#endregion
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.6.2",
+  "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",

package/lib/utils-NHs5DuHk.js

@@ -1,24 +0,0 @@
-
-//#region src/utils.ts
-async function resolveLazyCommand(cmd, name, entry = false) {
-	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd, { default: entry });
-	if (resolved.name == null && name) resolved.name = name;
-	return deepFreeze(resolved);
-}
-function create(obj = null) {
-	return Object.create(obj);
-}
-function log(...args) {
-	console.log(...args);
-}
-function deepFreeze(obj) {
-	if (obj === null || typeof obj !== "object") return obj;
-	for (const key of Object.keys(obj)) {
-		const value = obj[key];
-		if (typeof value === "object" && value !== null) deepFreeze(value);
-	}
-	return Object.freeze(obj);
-}
-
-//#endregion
-export { create, deepFreeze, log, resolveLazyCommand };