@gunshi/plugin-i18n 0.26.3 → 0.27.0-alpha.10

package/README.md

@@ -50,7 +50,6 @@ const greetCommand = defineI18n({
   // Define resource fetcher for translations
   resource: async ctx => ({
     description: 'Greet someone in their language',
-    examples: '$ your-cli --name yourname',
     'arg:name': "The person's name",
     greeting: 'Hello, {$name}!'
   }),
@@ -86,7 +85,7 @@ await cli(process.argv.slice(2), greetCommand, {
 - Default: `{}`
 - Description:
   - Built-in resource translations for different locales. Used for translating gunshi built-in level messages like "USAGE", "OPTIONS", "COMMANDS", etc.
-  - for details, see [Resource Key Naming Conventions](#resource-key-naming-conventions)
+  - for details, see [Resource Key Naming Conventions](#-resource-key-naming-conventions)
 
 ### `translationAdapterFactory`
 
@@ -185,6 +184,88 @@ const i18nCommand = withI18nResource(basicCommand, async ctx => {
 })
 ```
 
+### Key Resolution Helpers
+
+The i18n plugin exports key resolution helper functions that handle the internal key structure, so you don't need to manually prefix your keys:
+
+- `resolveKey(key: string, ctx: CommandContext): string` - Resolves a custom key with command namespace if applicable
+- `resolveArgKey(key: string, ctx: CommandContext): string` - Resolves an argument key with `arg:` prefix and namespace
+- `resolveBuiltInKey(key: string): string` - Resolves a built-in key with `_:` prefix
+
+```ts
+import { resolveKey, resolveArgKey, resolveBuiltInKey } from '@gunshi/plugin-i18n'
+
+// These helpers automatically add the correct prefixes
+resolveKey('description', ctx) // Returns namespaced key for description
+resolveArgKey('verbose', ctx) // Returns 'arg:verbose' or 'command:arg:verbose' based on context
+resolveBuiltInKey('USAGE') // Returns '_:USAGE'
+```
+
+#### Why Use Key Resolution Helpers?
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> See also the [Resource Key Naming Conventions](#-resource-key-naming-conventions) section for details on how keys should be structured in your resource definitions.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+The i18n plugin internally uses different key prefixes to organize translations:
+
+- Built-in keys use `_:` prefix (e.g., `_:USAGE`, `_:OPTIONS`)
+- Argument keys use `arg:` prefix (e.g., `arg:file`, `arg:verbose`)
+- Command-specific keys can be namespaced with command name
+
+While the `translate` function accepts keys without prefixes in most cases, using these helpers ensures:
+
+- Consistent key resolution across your application
+- Proper namespacing when using sub-commands
+- Compatibility with future plugin updates
+- Type-safe key generation
+
+#### Example Usage
+
+```ts
+import { defineI18n, resolveKey, resolveArgKey, resolveBuiltInKey } from '@gunshi/plugin-i18n'
+
+const command = defineI18n({
+  name: 'deploy',
+  args: {
+    environment: { type: 'string', short: 'e' },
+    force: { type: 'boolean', short: 'f' }
+  },
+  resource: async ctx => ({
+    description: 'Deploy application',
+    'arg:environment': 'Target environment',
+    'arg:force': 'Force deployment',
+    deploy_start: 'Starting deployment...',
+    deploy_success: 'Deployment completed successfully!'
+  }),
+  run: async ctx => {
+    const { translate } = ctx.extensions['g:i18n']
+
+    // Direct usage (need to prefix with command name)
+    console.log(translate('deploy:deploy_start'))
+
+    // Using helpers for explicit control
+    const envKey = resolveArgKey('environment', ctx)
+    console.log(translate(envKey)) // Same as translate('arg:environment')
+
+    // Useful when building dynamic keys
+    const args = ['environment', 'force']
+    for (const arg of args) {
+      const key = resolveArgKey(arg, ctx)
+      const description = translate(key)
+      console.log(`${arg}: ${description}`)
+    }
+
+    // For built-in messages
+    const usageKey = resolveBuiltInKey('USAGE')
+    console.log(translate(usageKey)) // Translates the "USAGE" header
+  }
+})
+```
+
 ## 🧩 Context Extensions
 
 When using the i18n plugin, your command context is extended via `ctx.extensions['g:i18n']`.
@@ -200,9 +281,17 @@ Available extensions:
 
 - `locale: Intl.Locale`: The current locale
 - `translate<T>(key: T, values?: Record<string, unknown>): string`: Translation function
+- `loadResource(locale: string | Intl.Locale, ctx: CommandContext, command: Command): Promise<boolean>`: Manually load resources for a specific locale and command
 
 ## 📝 Resource Key Naming Conventions
 
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> The plugin provides [Key Resolution Helpers](#key-resolution-helpers) (`resolveKey`, `resolveArgKey`, `resolveBuiltInKey`) to automatically handle these naming conventions programmatically.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
 When defining your localization resources (either directly in the `resource` function or in separate files), there are specific naming conventions to follow for the keys:
 
 - **Command Description**: Use the key `description` for the main description of the command.
@@ -225,7 +314,7 @@ When defining your localization resources (either directly in the `resource` fun
   - `help` - Description for the help option ("Display this help message")
   - `version` - Description for the version option ("Display this version")
 
-  Internally, these keys are prefixed with `_:` (e.g., `_:USAGE`, `_:OPTIONS`), but you don't need to use this prefix directly. When overriding built-in translations in your resources, use the key names without the prefix (e.g., providing your own translation for `NEGATABLE`, not `_:NEGATABLE`).
+  Internally, these keys are prefixed with `_:` (e.g., `_:USAGE`, `_:OPTIONS`), but you don't need to use this prefix directly. When overriding built-in translations in your resources, use the key names without the prefix (e.g., providing your own translation for `NEGATABLE`, not `_:NEGATABLE`). Additionally, custom keys are automatically namespaced with the command name in sub-command contexts (e.g., `deploy:informal_greeting` for a 'deploy' command).
 
 Here's an example illustrating the convention:
 
@@ -242,7 +331,6 @@ const command = defineI18n({
     // Example for 'en-US' locale
     return {
       description: 'This is my command.', // No prefix
-      examples: '$ my-command --target file.txt', // No prefix
       'arg:target': 'The target file to process.', // 'arg:' prefix
       'arg:verbose': 'Enable verbose output.', // 'arg:' prefix
       'arg:no-verbose': 'Disable verbose logging specifically.', // Optional custom translation for the negatable option
@@ -255,6 +343,13 @@ const command = defineI18n({
 })
 ```
 
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> When defining resources, argument and option descriptions **must** be prefixed with `arg:` (e.g., `arg:target`, `arg:verbose`). All other keys like `description`, `examples`, and custom keys do not require prefixes.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
 Adhering to these conventions ensures that Gunshi correctly identifies and uses your translations for descriptions, help messages, and within your command's logic via `ctx.extensions['g:i18n'].translate()`.
 
 <!-- eslint-disable markdown/no-missing-label-refs -->
@@ -284,6 +379,78 @@ Bad Nested structure (won't work with `ctx.extensions['g:i18n'].translate('messa
 }
 ```
 
+## 🔧 Implementation Details
+
+This section covers important implementation details that can help you better understand and use the i18n plugin.
+
+### Translation Return Values
+
+The `translate` function has different behaviors depending on the key type:
+
+- **Custom keys**: Returns an empty string (`''`) if the key is not found
+- **Built-in keys** (internally prefixed with `_:`): Returns the key itself if not found
+
+This difference is important for error handling and fallback displays:
+
+```ts
+const { translate } = ctx.extensions['g:i18n']
+
+// Custom key not found
+translate('nonexistent_key') // Returns: ''
+
+// Built-in key not found (if not overridden)
+translate('USAGE') // Returns: 'USAGE'
+```
+
+### Resource Loading Behavior
+
+When loading command resources, the plugin automatically:
+
+1. Extracts option descriptions from command args definitions
+2. Creates default resources in English
+3. Merges built-in resources with command-specific resources
+4. Handles errors gracefully (logs to console.error but continues execution)
+
+### Extending DefaultTranslation
+
+The default translation adapter is exported and can be extended:
+
+```ts
+import { DefaultTranslation } from '@gunshi/plugin-i18n'
+
+class MyCustomTranslation extends DefaultTranslation {
+  translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined {
+    const result = super.translate(locale, key, values)
+    // Add custom post-processing
+    return result?.toUpperCase()
+  }
+}
+
+// Use in plugin options
+await cli(args, command, {
+  plugins: [
+    i18n({
+      translationAdapterFactory: options => new MyCustomTranslation(options)
+    })
+  ]
+})
+```
+
+### Internal Key Prefixing
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> Understanding these prefixes is essential for using the [Key Resolution Helpers](#key-resolution-helpers) effectively and following the [Resource Key Naming Conventions](#-resource-key-naming-conventions).
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+- Built-in resource keys are internally prefixed with `_:` (e.g., `_:USAGE`, `_:OPTIONS`)
+- This prefix is handled automatically - you don't need to use it when overriding built-in translations
+- Argument keys use the `arg:` prefix as documented
+- Custom keys can be namespaced with the command name when in sub-command context (e.g., `deploy:custom_message` for a 'deploy' command)
+- Use the exported helper functions (`resolveKey`, `resolveArgKey`, `resolveBuiltInKey`) to generate properly prefixed keys programmatically
+
 ## 🔤 Translation Interpolation
 
 The default translation adapter supports simple interpolation using `{$key}` syntax:
@@ -298,10 +465,10 @@ const resource = {
 }
 // In your command
 const { translate } = ctx.extensions['g:i18n']
-translate('welcome', { name: 'John' }) // "Welcome, John!"
-translate('items.count', { count: 5 }) // "You have 5 items"
-translate('file_deleted', { path: '/tmp/file.txt' }) // "Deleted /tmp/file.txt"
-translate('error_message', { error: 'File not found' }) // "Error: File not found"
+translate(resolveKey('welcome'), { name: 'John' }) // "Welcome, John!"
+translate(resolveKey('items.count'), { count: 5 }) // "You have 5 items"
+translate(resolveKey('file_deleted'), { path: '/tmp/file.txt' }) // "Deleted /tmp/file.txt"
+translate(resolveKey('error_message'), { error: 'File not found' }) // "Error: File not found"
 ```
 
 <!-- eslint-disable markdown/no-missing-label-refs -->
@@ -518,6 +685,43 @@ With Intlify, you get advanced features like:
 
 <!-- eslint-enable markdown/no-missing-label-refs -->
 
+## 🎯 Type-Safe Translation Keys
+
+The i18n plugin provides sophisticated TypeScript type support for translation keys. When using TypeScript, the `translate` function will provide auto-completion and type checking for:
+
+- Built-in keys (`USAGE`, `OPTIONS`, `COMMANDS`, etc.)
+- Argument keys based on your command's args definition (`arg:name`, `arg:verbose`, etc.)
+- Custom keys defined in your resource
+
+```ts
+import { defineI18n } from '@gunshi/plugin-i18n'
+
+const command = defineI18n({
+  name: 'example',
+  args: {
+    file: { type: 'string' },
+    verbose: { type: 'boolean' }
+  },
+  resource: async () => ({
+    description: 'Example command',
+    'arg:file': 'File to process',
+    'arg:verbose': 'Enable verbose output',
+    custom_message: 'This is a custom message'
+  }),
+  run: ctx => {
+    const { translate } = ctx.extensions['g:i18n']
+
+    // TypeScript knows these are valid keys
+    translate('USAGE') // Built-in key
+    translate('arg:file') // Arg key from command definition
+    translate('custom_message') // Custom key from resource
+
+    // TypeScript will error on invalid keys
+    // translate('invalid_key')  // Type error!
+  }
+})
+```
+
 ## 📚 API References
 
 See the [API References](./docs/index.md)

package/lib/index.d.ts

@@ -1,78 +1,568 @@
-import { Awaitable, Command, CommandContext, DefaultGunshiParams, ExtractArgs, GunshiParams, GunshiParamsConstraint, NormalizeToGunshiParams, PluginWithExtension } from "@gunshi/plugin";
+import { Args, Awaitable, Command, CommandContext, DefaultGunshiParams, ExtractArgs, GunshiParams, GunshiParamsConstraint, PluginWithExtension } from "@gunshi/plugin";
 
 //#region rolldown:runtime
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/parser-Cbxholql.d.ts
+//#region src/parser.d.ts
+/**
+ * Entry point of argument parser.
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Argument token Kind.
+ * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
+ * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+ * - `positional`: positional token
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
+interface ArgToken {
+  /**
+   * Argument token kind.
+   */
+  kind: ArgTokenKind;
+  /**
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
+  index: number;
+  /**
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
+  name?: string;
+  /**
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
+  rawName?: string;
+  /**
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
+  value?: string;
+  /**
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
+  inlineValue?: boolean;
+}
+/**
+ * Parser Options.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-BoS-UnqX.d.ts
 //#region src/resolver.d.ts
 
 /**
-* An argument schema
-* This schema is similar to the schema of the `node:utils`.
-* difference is that:
-* - `required` property and `description` property are added
-* - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
-* - `default` property type, not support multiple types
-*/
+ * An argument schema
+ * This schema is similar to the schema of the `node:utils`.
+ * difference is that:
+ * - `required` property and `description` property are added
+ * - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
+ * - `default` property type, not support multiple types
+ */
 interface ArgSchema {
   /**
-  * Type of argument.
-  */
-  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
+   * Type of argument.
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
   /**
-  * A single character alias for the argument.
-  */
+   * A single character alias for the argument.
+   */
   short?: string;
   /**
-  * A description of the argument.
-  */
+   * A description of the argument.
+   */
   description?: string;
   /**
-  * Whether the argument is required or not.
-  */
+   * Whether the argument is required or not.
+   */
   required?: true;
   /**
-  * Whether the argument allow multiple values or not.
-  */
+   * Whether the argument allow multiple values or not.
+   */
   multiple?: true;
   /**
-  * Whether the negatable option for `boolean` type
-  */
+   * Whether the negatable option for `boolean` type
+   */
   negatable?: boolean;
   /**
-  * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
-  */
+   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+   */
   choices?: string[] | readonly string[];
   /**
-  * The default value of the argument.
-  * if the type is 'enum', the default value must be one of the allowed values.
-  */
+   * The default value of the argument.
+   * if the type is 'enum', the default value must be one of the allowed values.
+   */
   default?: string | boolean | number;
   /**
-  * Whether to convert the argument name to kebab-case.
-  */
+   * Whether to convert the argument name to kebab-case.
+   */
   toKebab?: true;
   /**
-  * A function to parse the value of the argument. if the type is 'custom', this function is required.
-  * If argument value will be invalid, this function have to throw an error.
-  * @param value
-  * @returns Parsed value
-  * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
-  */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   * A function to parse the value of the argument. if the type is 'custom', this function is required.
+   * If argument value will be invalid, this function have to throw an error.
+   * @param value
+   * @returns Parsed value
+   * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
+   */
   parse?: (value: string) => any;
 }
 /**
-* An object that contains {@link ArgSchema | argument schema}.
-*/
-interface Args {
+ * An object that contains {@link ArgSchema | argument schema}.
+ */
+interface Args$1 {
   [option: string]: ArgSchema;
-} //#endregion
-//#region ../shared/src/constants.d.ts
+}
+/**
+ * An object that contains the values of the arguments.
+ */
+type ArgValues<T> = T extends Args$1 ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
+  [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
+};
+type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
+/**
+ * @internal
+ */
+type ExtractOptionValue<A extends ArgSchema> = A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? IsFunction<A['parse']> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A['parse']>>> : never : ResolveOptionValue<A, string | boolean | number>;
+type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
+/**
+ * @internal
+ */
+type ResolveArgValues<A extends Args$1, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
+/**
+ * @internal
+ */
+type FilterArgs<A extends Args$1, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+/**
+ * @internal
+ */
+type FilterPositionalArgs<A extends Args$1, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
+/**
+ * An arguments for {@link resolveArgs | resolve arguments}.
+ */
+
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ */
+type ArgExplicitlyProvided<A extends Args$1> = { [K in keyof A]: boolean };
+/**
+ * Resolve command line arguments.
+ * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
+//#endregion
+//#region ../gunshi/src/types.d.ts
+type Awaitable$1<T> = T | Promise<T>;
+/**
+ * Extend command context type. This type is used to extend the command context with additional properties at {@link CommandContext.extensions}.
+ * @since v0.27.0
+ */
+type ExtendContext = Record<string, unknown>;
+/**
+ * Gunshi unified parameter type.
+ * This type combines both argument definitions and command context extensions.
+ * @since v0.27.0
+ */
+interface GunshiParams$1<P extends {
+  args?: Args$1;
+  extensions?: ExtendContext;
+} = {
+  args: Args$1;
+  extensions: {};
+}> {
+  /**
+   * Command argument definitions
+   */
+  args: P extends {
+    args: infer A extends Args$1;
+  } ? A : Args$1;
+  /**
+   * Command context extensions
+   */
+  extensions: P extends {
+    extensions: infer E extends ExtendContext;
+  } ? E : {};
+}
+/**
+ * Default Gunshi parameters
+ * @since v0.27.0
+ */
+type DefaultGunshiParams$1 = GunshiParams$1;
+/**
+ * Generic constraint for command-related types.
+ * This type constraint allows both GunshiParams and objects with extensions.
+ * @since v0.27.0
+ */
+type GunshiParamsConstraint$1 = GunshiParams$1<any> | {
+  extensions: ExtendContext;
+};
+/**
+ * Type helper to extract args from G
+ * @internal
+ */
+type ExtractArgs$1<G> = G extends GunshiParams$1<any> ? G['args'] : Args$1;
+/**
+ * Type helper to extract explicitly provided argument flags from G
+ * @internal
+ */
+type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs$1<G>>;
+/**
+ * Type helper to extract extensions from G
+ * @internal
+ */
+type ExtractExtensions<G> = G extends GunshiParams$1<any> ? G['extensions'] : G extends {
+  extensions: infer E;
+} ? E : {};
+/**
+ * Type helper to normalize G to GunshiParams
+ * @internal
+ */
+
+/**
+ * Command environment.
+ */
+interface CommandEnvironment<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> {
+  /**
+   * Current working directory.
+   * @see {@link CliOptions.cwd}
+   */
+  cwd: string | undefined;
+  /**
+   * Command name.
+   * @see {@link CliOptions.name}
+   */
+  name: string | undefined;
+  /**
+   * Command description.
+   * @see {@link CliOptions.description}
+   *
+   */
+  description: string | undefined;
+  /**
+   * Command version.
+   * @see {@link CliOptions.version}
+   */
+  version: string | undefined;
+  /**
+   * Left margin of the command output.
+   * @default 2
+   * @see {@link CliOptions.leftMargin}
+   */
+  leftMargin: number;
+  /**
+   * Middle margin of the command output.
+   * @default 10
+   * @see {@link CliOptions.middleMargin}
+   */
+  middleMargin: number;
+  /**
+   * Whether to display the usage option type.
+   * @default false
+   * @see {@link CliOptions.usageOptionType}
+   */
+  usageOptionType: boolean;
+  /**
+   * Whether to display the option value.
+   * @default true
+   * @see {@link CliOptions.usageOptionValue}
+   */
+  usageOptionValue: boolean;
+  /**
+   * Whether to display the command usage.
+   * @default false
+   * @see {@link CliOptions.usageSilent}
+   */
+  usageSilent: boolean;
+  /**
+   * Sub commands.
+   * @see {@link CliOptions.subCommands}
+   */
+  subCommands: Map<string, Command$1<any> | LazyCommand<any>> | undefined;
+  /**
+   * Render function the command usage.
+   */
+  renderUsage: ((ctx: Readonly<CommandContext$1<G>>) => Promise<string>) | null | undefined;
+  /**
+   * Render function the header section in the command usage.
+   */
+  renderHeader: ((ctx: Readonly<CommandContext$1<G>>) => Promise<string>) | null | undefined;
+  /**
+   * Render function the validation errors.
+   */
+  renderValidationErrors: ((ctx: Readonly<CommandContext$1<G>>, error: AggregateError) => Promise<string>) | null | undefined;
+  /**
+   * Hook that runs before any command execution
+   * @see {@link CliOptions.onBeforeCommand}
+   * @since v0.27.0
+   */
+  onBeforeCommand: ((ctx: Readonly<CommandContext$1<G>>) => Awaitable$1<void>) | undefined;
+  /**
+   * Hook that runs after successful command execution
+   * @see {@link CliOptions.onAfterCommand}
+   * @since v0.27.0
+   */
+  onAfterCommand: ((ctx: Readonly<CommandContext$1<G>>, result: string | undefined) => Awaitable$1<void>) | undefined;
+  /**
+   * Hook that runs when a command throws an error
+   * @see {@link CliOptions.onErrorCommand}
+   * @since v0.27.0
+   */
+  onErrorCommand: ((ctx: Readonly<CommandContext$1<G>>, error: Error) => Awaitable$1<void>) | undefined;
+}
+/**
+ * CLI options of `cli` function.
+ */
+
+/**
+ * Command call mode.
+ */
+type CommandCallMode = 'entry' | 'subCommand' | 'unexpected';
+/**
+ * Command context.
+ * Command context is the context of the command execution.
+ */
+interface CommandContext$1<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> {
+  /**
+   * Command name, that is the command that is executed.
+   * The command name is same {@link CommandEnvironment.name}.
+   */
+  name: string | undefined;
+  /**
+   * Command description, that is the description of the command that is executed.
+   * The command description is same {@link CommandEnvironment.description}.
+   */
+  description: string | undefined;
+  /**
+   * Command environment, that is the environment of the command that is executed.
+   * The command environment is same {@link CommandEnvironment}.
+   */
+  env: Readonly<CommandEnvironment<G>>;
+  /**
+   * Command arguments, that is the arguments of the command that is executed.
+   * The command arguments is same {@link Command.args}.
+   */
+  args: ExtractArgs$1<G>;
+  /**
+   * Whether arguments were explicitly provided by the user.
+   *
+   * - `true`: The argument was explicitly provided via command line
+   * - `false`: The argument was not explicitly provided. This means either:
+   *   - The value comes from a default value defined in the argument schema
+   *   - The value is `undefined` (no explicit input and no default value)
+   */
+  explicit: ExtractArgExplicitlyProvided<G>;
+  /**
+   * Command values, that is the values of the command that is executed.
+   * Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
+   */
+  values: ArgValues<ExtractArgs$1<G>>;
+  /**
+   * Command positionals arguments, that is the positionals of the command that is executed.
+   * Resolve positionals with `resolveArgs` from command arguments.
+   */
+  positionals: string[];
+  /**
+   * Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`.
+   */
+  rest: string[];
+  /**
+   * Original command line arguments.
+   * This argument is passed from `cli` function.
+   */
+  _: string[];
+  /**
+   * Argument tokens, that is parsed by `parseArgs` function.
+   */
+  tokens: ArgToken[];
+  /**
+   * Whether the currently executing command has been executed with the sub-command name omitted.
+   */
+  omitted: boolean;
+  /**
+   * Command call mode.
+   * The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command.
+   */
+  callMode: CommandCallMode;
+  /**
+   * Whether to convert the camel-case style argument name to kebab-case.
+   * This context value is set from {@link Command.toKebab} option.
+   */
+  toKebab?: boolean;
+  /**
+   * Output a message.
+   * If {@link CommandEnvironment.usageSilent} is true, the message is not output.
+   * @param message an output message, @see {@link console.log}
+   * @param optionalParams an optional parameters, @see {@link console.log}
+   * @internal
+   */
+  log: (message?: any, ...optionalParams: any[]) => void;
+  /**
+   * Command context extensions.
+   * @since v0.27.0
+   */
+  extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
+  /**
+   * Validation error from argument parsing.
+   * This will be set if argument validation fails during CLI execution.
+   */
+  validationError?: AggregateError;
+}
+/**
+ * CommandContextCore type (base type without extensions)
+ * @since v0.27.0
+ */
 
 /**
-* An object that contains the values of the arguments.
-*/
+ * Rendering control options
+ * @since v0.27.0
+ */
+interface RenderingOptions<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> {
+  /**
+   * Header rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  header?: ((ctx: Readonly<CommandContext$1<G>>) => Promise<string>) | null;
+  /**
+   * Usage rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  usage?: ((ctx: Readonly<CommandContext$1<G>>) => Promise<string>) | null;
+  /**
+   * Validation errors rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  validationErrors?: ((ctx: Readonly<CommandContext$1<G>>, error: AggregateError) => Promise<string>) | null;
+}
+/**
+ * Command interface.
+ */
+interface Command$1<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> {
+  /**
+   * Command name.
+   * It's used to find command line arguments to execute from sub commands, and it's recommended to specify.
+   */
+  name?: string;
+  /**
+   * Command description.
+   * It's used to describe the command in usage and it's recommended to specify.
+   */
+  description?: string;
+  /**
+   * Command arguments.
+   * Each argument can include a description property to describe the argument in usage.
+   */
+  args?: ExtractArgs$1<G>;
+  /**
+   * Command examples.
+   * examples of how to use the command.
+   */
+  examples?: string | CommandExamplesFetcher<G>;
+  /**
+   * Command runner. it's the command to be executed
+   */
+  run?: CommandRunner<G>;
+  /**
+   * Whether to convert the camel-case style argument name to kebab-case.
+   * If you will set to `true`, All {@link Command.args} names will be converted to kebab-case.
+   */
+  toKebab?: boolean;
+  /**
+   * Whether this is an internal command.
+   * Internal commands are not shown in help usage.
+   * @default false
+   * @since v0.27.0
+   */
+  internal?: boolean;
+  /**
+   * Whether this command is an entry command.
+   * @default undefined
+   * @since v0.27.0
+   */
+  entry?: boolean;
+  /**
+   * Rendering control options
+   * @since v0.27.0
+   */
+  rendering?: RenderingOptions<G>;
+}
+/**
+ * Lazy command interface.
+ * Lazy command that's not loaded until it is executed.
+ */
+type LazyCommand<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> = {
+  /**
+   * Command load function
+   */
+  (): Awaitable$1<Command$1<G> | CommandRunner<G>>;
+  /**
+   * Command name
+   */
+  commandName?: string;
+} & Omit<Command$1<G>, 'run' | 'name'>;
+/**
+ * Define a command type.
+ */
+
+/**
+ * Command examples fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched command examples.
+ */
+type CommandExamplesFetcher<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> = (ctx: Readonly<CommandContext$1<G>>) => Awaitable$1<string>;
+/**
+ * Command runner.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns void or string (for CLI output)
+ */
+type CommandRunner<G extends GunshiParamsConstraint$1 = DefaultGunshiParams$1> = (ctx: Readonly<CommandContext$1<G>>) => Awaitable$1<string | void>;
+/**
+ * Command loader.
+ * A function that returns a command or command runner.
+ * This is used to lazily load commands.
+ * @returns A command or command runner
+ */
 declare namespace constants_d_exports {
   export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, PLUGIN_PREFIX };
 }
@@ -101,7 +591,6 @@ 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"];
-
 //#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] };
@@ -109,7 +598,7 @@ type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : num
  * Remove index signature from object or record type.
  */
 type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
-type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
+type KeyOfArgs<A extends Args$1> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
 /**
  * Generate a namespaced key.
  */
@@ -123,20 +612,59 @@ type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
  */
 type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
 /**
- * i18n built-in resource keys.
+ * Built-in resource keys.
  */
 type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
 /**
- * Command i18n built-in keys.
- * The command i18n built-in keys are used by the i18n plugin for translation.
+ * Command built-in keys.
  */
-type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys> | 'description' | 'examples';
+type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
 /**
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
  */
-type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
-
+type CommandArgKeys<A extends Args$1, C = {}, K extends string = GenerateNamespacedKey<Extract<KeyOfArgs<RemovedIndex<A>>, string>, typeof ARG_PREFIX>> = C extends {
+  name: infer N;
+} ? (N extends string ? GenerateNamespacedKey<K, N> : K) : K;
+/**
+ * Resolve translation keys for command context.
+ */
+type ResolveTranslationKeys<A extends Args$1, C = {},
+// for CommandContext
+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;
+/**
+ * Translation function interface
+ */
+//#endregion
+//#region ../shared/src/utils.d.ts
+/**
+ * Resolve a namespaced key for built-in resources.
+ * Built-in keys are prefixed with "_:".
+ * @param key The built-in key to resolve.
+ * @returns Prefixed built-in key.
+ */
+declare function resolveBuiltInKey<K extends string = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
+/**
+ * Resolve a namespaced key for argument resources.
+ * Argument keys are prefixed with "arg:".
+ * If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
+ * @param key The argument key to resolve.
+ * @param ctx The command context.
+ * @returns Prefixed argument key.
+ */
+declare function resolveArgKey<A extends Args$1 = DefaultGunshiParams$1['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, ctx?: Readonly<CommandContext$1>): string;
+/**
+ * Resolve a namespaced key for non-built-in resources.
+ * Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+ * @param key The non-built-in key to resolve.
+ * @param ctx The command context.
+ * @returns Prefixed non-built-in key.
+ */
+declare function resolveKey<T extends Record<string, string> = {}, K = (keyof T extends string ? keyof T : string)>(key: K, ctx?: Readonly<CommandContext$1>): string;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -155,16 +683,27 @@ interface I18nCommandContext<G extends GunshiParams<any> = DefaultGunshiParams>
   /**
    * Command locale
    */
-  locale: string | Intl.Locale;
+  locale: Intl.Locale;
   /**
-   * Translate a message
+   * Translate a message.
    * @param key Translation key
    * @param values Values to interpolate
    * @returns Translated message. If the key is not found:
    *   - For custom keys: returns an empty string ('')
    *   - For built-in keys (prefixed with '_:'): returns the key itself
    */
-  translate: <T extends string = CommandBuiltinKeys, O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>) => string;
+  translate: <A extends Args = G['args'], C = {},
+  // for CommandContext
+  E extends Record<string, string> = {},
+  // for extended resources
+  K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>) => string;
+  /**
+   * Load command resources.
+   * @param ctx Command context
+   * @param command Command
+   * @returns Whether the resources were loaded successfully
+   */
+  loadResource: (locale: string | Intl.Locale, ctx: CommandContext, command: Command) => Promise<boolean>;
 }
 /**
  * i18n plugin options
@@ -243,19 +782,9 @@ type CommandResource<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
    * Command description.
    */
   description: string;
-  /**
-   * Examples usage.
-   */
-  examples: string | CommandExamplesFetcher<NormalizeToGunshiParams<G>>;
 } & { [Arg in GenerateNamespacedKey<KeyOfArgs<RemovedIndex<ExtractArgs<G>>>, typeof ARG_PREFIX>]: string } & {
   [key: string]: string;
 };
-/**
- * Command examples fetcher.
- * @param ctx A {@link CommandContext | command context}
- * @returns A fetched command examples.
- */
-type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
 /**
  * Command resource fetcher.
  * @param ctx A {@link CommandContext | command context}
@@ -272,7 +801,6 @@ interface I18nCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> ex
    */
   resource?: CommandResourceFetcher<G>;
 }
-
 //#endregion
 //#region src/helpers.d.ts
 /**
@@ -328,7 +856,6 @@ declare function defineI18n<G extends GunshiParamsConstraint = DefaultGunshiPara
  * ```
  */
 declare function withI18nResource<G extends GunshiParamsConstraint>(command: Command<G>, resource: CommandResourceFetcher<G>): I18nCommand<G>;
-
 //#endregion
 //#region src/translation.d.ts
 declare function createTranslationAdapter(options: TranslationAdapterFactoryOptions): TranslationAdapter;
@@ -340,7 +867,6 @@ declare class DefaultTranslation implements TranslationAdapter {
   getMessage(locale: string, key: string): string | undefined;
   translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
 }
-
 //#endregion
 //#region src/index.d.ts
 /**
@@ -350,7 +876,6 @@ declare const DEFAULT_LOCALE = "en-US";
 /**
  * i18n plugin
  */
-declare function i18n(options?: I18nPluginOptions): PluginWithExtension<Promise<I18nCommandContext<DefaultGunshiParams>>>;
-
+declare function i18n(options?: I18nPluginOptions): PluginWithExtension<I18nCommandContext<DefaultGunshiParams>>;
 //#endregion
-export { CommandExamplesFetcher, CommandResource, CommandResourceFetcher, DEFAULT_LOCALE, DefaultTranslation, I18nCommand, I18nCommandContext, I18nPluginOptions, PluginId, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, createTranslationAdapter, i18n as default, defineI18n, pluginId, withI18nResource };
+export { CommandResource, CommandResourceFetcher, DEFAULT_LOCALE, DefaultTranslation, I18nCommand, I18nCommandContext, I18nPluginOptions, PluginId, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, createTranslationAdapter, i18n as default, defineI18n, pluginId, resolveArgKey, resolveBuiltInKey, resolveKey, withI18nResource };

package/lib/index.js

@@ -45,11 +45,38 @@ var en_US_default = {
 
 //#endregion
 //#region ../shared/src/utils.ts
+/**
+* Resolve a namespaced key for built-in resources.
+* Built-in keys are prefixed with "_:".
+* @param key The built-in key to resolve.
+* @returns Prefixed built-in key.
+*/
 function resolveBuiltInKey(key) {
 	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
-function resolveArgKey(key) {
-	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+/**
+* Resolve a namespaced key for argument resources.
+* Argument keys are prefixed with "arg:".
+* If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
+* @param key The argument key to resolve.
+* @param ctx The command context.
+* @returns Prefixed argument key.
+*/
+function resolveArgKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+/**
+* Resolve a namespaced key for non-built-in resources.
+* Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+* @param key The non-built-in key to resolve.
+* @param ctx The command context.
+* @returns Prefixed non-built-in key.
+*/
+function resolveKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
+}
+async function resolveExamples(ctx, examples) {
+	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
 }
 function namespacedId(id) {
 	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
@@ -169,7 +196,7 @@ const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
 */
 function i18n(options = {}) {
 	const locale = toLocale(options.locale);
-	const localeStr = locale.toString();
+	const localeStr = toLocaleString(locale);
 	const resources = options.resources || Object.create(null);
 	const translationAdapterFactory = options.translationAdapterFactory || createTranslationAdapter;
 	const adapter = translationAdapterFactory({
@@ -195,56 +222,69 @@ function i18n(options = {}) {
 			}
 			function getResource(locale$1) {
 				const targetLocale = toLocale(locale$1);
-				const targetLocaleStr = targetLocale.toString();
+				const targetLocaleStr = toLocaleString(targetLocale);
 				return localeBuiltinResources.get(targetLocaleStr);
 			}
 			function setResource(locale$1, resource) {
 				const targetLocale = toLocale(locale$1);
-				const targetLocaleStr = targetLocale.toString();
+				const targetLocaleStr = toLocaleString(targetLocale);
 				if (localeBuiltinResources.has(targetLocaleStr)) return;
-				localeBuiltinResources.set(targetLocale.toString(), mapResourceWithBuiltinKey(resource));
+				localeBuiltinResources.set(targetLocaleStr, mapResourceWithBuiltinKey(resource));
 			}
 			setResource(DEFAULT_LOCALE, en_US_default);
 			for (const [locale$1, resource] of Object.entries(resources)) setResource(locale$1, resource);
 			builtInLoadedResources = getResource(locale);
+			async function loadResource(locale$1, ctx, cmd) {
+				let loaded = false;
+				const originalResource = await loadCommandResource(ctx, cmd);
+				if (originalResource) {
+					const resource = await normalizeResource(originalResource, ctx);
+					if (builtInLoadedResources) {
+						resource.help = builtInLoadedResources.help;
+						resource.version = builtInLoadedResources.version;
+					}
+					adapter.setResource(toLocaleString(locale$1), resource);
+					loaded = true;
+				}
+				return loaded;
+			}
 			return {
 				locale,
-				translate
+				translate,
+				loadResource
 			};
 		},
 		onExtension: async (ctx, cmd) => {
+			const i18n$1 = ctx.extensions[pluginId];
 			/**
 			* load command resources, after the command context is extended
 			*/
 			const loadedOptionsResources = Object.entries(ctx.args).map(([key, schema]) => [key, schema.description || ""]);
 			const defaultCommandResource = loadedOptionsResources.reduce((res, [key, value]) => {
-				res[resolveArgKey(key)] = value;
+				res[resolveArgKey(key, ctx)] = value;
 				return res;
 			}, Object.create(null));
-			defaultCommandResource.description = cmd.description || "";
-			defaultCommandResource.examples = typeof cmd.examples === "string" ? cmd.examples : typeof cmd.examples === "function" ? await cmd.examples(ctx) : "";
+			defaultCommandResource[resolveKey("description", ctx)] = cmd.description || "";
+			defaultCommandResource[resolveKey("examples", ctx)] = await resolveExamples(ctx, cmd.examples);
 			adapter.setResource(DEFAULT_LOCALE, defaultCommandResource);
-			const originalResource = await loadCommandResource(ctx, cmd);
-			if (originalResource) {
-				const resource = Object.assign(Object.create(null), originalResource, { examples: typeof originalResource.examples === "string" ? originalResource.examples : typeof originalResource.examples === "function" ? await originalResource.examples(ctx) : "" });
-				if (builtInLoadedResources) {
-					resource.help = builtInLoadedResources.help;
-					resource.version = builtInLoadedResources.version;
-				}
-				adapter.setResource(localeStr, resource);
-			}
+			await i18n$1.loadResource(localeStr, ctx, cmd);
 		}
 	});
 }
 function toLocale(locale) {
 	return locale instanceof Intl.Locale ? locale : typeof locale === "string" ? new Intl.Locale(locale) : new Intl.Locale(DEFAULT_LOCALE);
 }
+function toLocaleString(locale) {
+	return locale instanceof Intl.Locale ? locale.toString() : locale;
+}
 async function loadCommandResource(ctx, command) {
 	if (!hasI18nResource(command)) return void 0;
 	let resource;
 	try {
 		resource = await command.resource(ctx);
-	} catch {}
+	} catch (error) {
+		console.error(`Failed to load resource for command "${command.name}":`, error);
+	}
 	return resource;
 }
 function mapResourceWithBuiltinKey(resource) {
@@ -256,6 +296,13 @@ function mapResourceWithBuiltinKey(resource) {
 function hasI18nResource(command) {
 	return "resource" in command && typeof command.resource === "function";
 }
+async function normalizeResource(resource, ctx) {
+	const ret = Object.create(null);
+	for (const [key, value] of Object.entries(resource)) if (key.startsWith(ARG_PREFIX_AND_KEY_SEPARATOR)) ret[resolveKey(key, ctx)] = value;
+	else if (key === "examples") ret[resolveKey("examples", ctx)] = await resolveExamples(ctx, value);
+	else ret[resolveKey(key, ctx)] = value;
+	return ret;
+}
 
 //#endregion
-export { DEFAULT_LOCALE, DefaultTranslation, createTranslationAdapter, i18n as default, defineI18n, pluginId, withI18nResource };
+export { DEFAULT_LOCALE, DefaultTranslation, createTranslationAdapter, i18n as default, defineI18n, pluginId, resolveArgKey, resolveBuiltInKey, resolveKey, withI18nResource };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-i18n",
   "description": "internationalization plugin for gunshi",
-  "version": "0.26.3",
+  "version": "0.27.0-alpha.10",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.26.3"
+    "@gunshi/plugin": "0.27.0-alpha.10"
   },
   "peerDependencies": {
-    "@gunshi/plugin-global": "0.26.3"
+    "@gunshi/plugin-global": "0.27.0-alpha.10"
   },
   "peerDependenciesMeta": {
     "@gunshi/plugin-global": {
@@ -65,16 +65,16 @@
   },
   "devDependencies": {
     "@intlify/core": "next",
-    "deno": "^2.3.3",
-    "jsr": "^0.13.4",
+    "deno": "^2.4.2",
+    "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "messageformat": "4.0.0-12",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.3",
-    "typedoc": "^0.28.4",
-    "typedoc-plugin-markdown": "^4.6.3",
-    "@gunshi/shared": "0.26.3",
-    "@gunshi/resources": "0.26.3"
+    "tsdown": "^0.13.0",
+    "typedoc": "^0.28.7",
+    "typedoc-plugin-markdown": "^4.7.1",
+    "@gunshi/resources": "0.27.0-alpha.10",
+    "@gunshi/shared": "0.27.0-alpha.10"
   },
   "scripts": {
     "build": "tsdown",