@gunshi/plugin-i18n 0.27.0-alpha.9 → 0.27.0-beta.0

package/README.md

@@ -1,5 +1,9 @@
 # @gunshi/plugin-i18n
 
+[![Version][npm-version-src]][npm-version-href]
+[![InstallSize][install-size-src]][install-size-src]
+[![JSR][jsr-src]][jsr-href]
+
 > internationalization (i18n) plugin for gunshi.
 
 This plugin provides multi-language support for your CLI applications, allowing you to create commands that can display messages in different languages based on user locale.
@@ -27,16 +31,18 @@ bun add @gunshi/plugin-i18n
 
 ```ts
 import { cli } from 'gunshi'
-import i18n, { defineI18n } from '@gunshi/plugin-i18n'
+import i18n, { pluginId as i18nId, defineI18nWithTypes } from '@gunshi/plugin-i18n'
+
+import type { I18nExtension } from '@gunshi/plugin-i18n'
 
 /**
- * You can define a command with `defineI18n`, which is compatible with the `define` function.
+ * You can define a command with `defineI18nWithTypes`, which is compatible with the `define` function.
  * This provides full type safety for i18n commands - TypeScript will suggest the 'resource' option
  * and ensure your resource keys match the expected structure.
  */
 
 // Define a command
-const greetCommand = defineI18n({
+const command = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
   name: 'greet',
   description: 'Greet someone',
 
@@ -48,16 +54,16 @@ const greetCommand = defineI18n({
   },
 
   // Define resource fetcher for translations
-  resource: async ctx => ({
+  resource: locale => ({
     description: 'Greet someone in their language',
     'arg:name': "The person's name",
     greeting: 'Hello, {$name}!'
   }),
 
-  run: async ctx => {
+  run: ctx => {
     const { name } = ctx.values
     // Use translate function from context
-    console.log(ctx.extensions['g:i18n'].translate('greeting', { name }))
+    console.log(ctx.extensions[i18nId].translate('greeting', { name }))
   }
 })
 
@@ -79,7 +85,7 @@ await cli(process.argv.slice(2), greetCommand, {
 - Default: `'en-US'`
 - Description: The locale to use for translations. Can be a BCP 47 language tag string or an `Intl.Locale` object.
 
-### `resources`
+### `builtinResources`
 
 - Type: `Record<string, Record<BuiltinResourceKeys, string>>`
 - Default: `{}`
@@ -112,19 +118,16 @@ Example with globals plugin:
 ```ts
 import { cli } from 'gunshi'
 import i18n from '@gunshi/plugin-i18n'
-import globals from '@gunshi/plugin-global'
+import globals from '@gunshi/plugin-global' // need install `@gunshi/plugin-global`
+import jaJPResource from '@gunshi/resources/ja-JP' with { type: 'json' } // need install `@gunshi/resources`
 
 await cli(args, command, {
   plugins: [
     globals(), // Adds --help and --version options
     i18n({
       locale: 'ja-JP',
-      resources: {
-        'ja-JP': {
-          help: 'ヘルプメッセージを表示', // Override help translation
-          version: 'バージョンを表示' // Override version translation
-          // ... other built-in translations
-        }
+      builtinResources: {
+        'ja-JP': jaJPResource // Set from with providing gunshi built-in resources
       }
     })
   ]
@@ -135,33 +138,81 @@ await cli(args, command, {
 
 ### `defineI18n`
 
-Type-safe helper to define an i18n-aware command.
+Define an i18n-aware command.
 
 ```ts
 import { defineI18n } from '@gunshi/plugin-i18n'
 
-const command = defineI18n({
-  name: 'hello',
+const greetCommand = defineI18n({
+  name: 'greet',
+  description: 'Greet someone',
   args: {
-    name: { type: 'string' }
+    name: {
+      type: 'string',
+      description: 'Name to greet'
+    }
   },
-  resource: async ctx => ({
-    description: 'Say hello',
-    'arg:name': 'Your name'
-  }),
-  run: async ctx => {
+  resource: locale => {
+    switch (locale.toString()) {
+      case 'ja-JP': {
+        return {
+          description: '誰かにあいさつ',
+          'arg:name': 'あいさつするための名前'
+        }
+      }
+      // other locales ...
+    }
+  },
+  run: ctx => {
     console.log(`Hello, ${ctx.values.name}!`)
   }
 })
 ```
 
+The difference from the `define` function is that you can define a `resource` option that can load a locale.
+
+### `defineI18nWithTypes`
+
+Define an i18n-aware command with types
+
+This helper function allows specifying the type parameter of `GunshiParams` while inferring the `Args` type, `ExtendContext` type from the definition.
+
+```ts
+import { defineI18nWithTypes } from '@gunshi/plugin-i18n'
+
+// Define a command with specific extensions type
+type MyExtensions = { logger: { log: (message: string) => void } }
+
+const greetCommand = defineI18nWithTypes<{ extensions: MyExtensions }>()({
+  name: 'greet',
+  args: {
+    name: { type: 'string', description: 'Name to greet' }
+  },
+  resource: locale => {
+    switch (locale.toString()) {
+      case 'ja-JP': {
+        return {
+          description: '誰かにあいさつ',
+          'arg:name': 'あいさつするための名前'
+        }
+      }
+      // other locales ...
+    }
+  },
+  run: ctx => {
+    // ctx.values is inferred as { name?: string }
+    // ctx.extensions is MyExtensions
+  }
+})
+```
+
 ### `withI18nResource`
 
-Add i18n resource to an existing command. This helper is useful for extending an already defined command.
+Add i18n resource to an existing command. This helper is useful for extending an already defined command with `define` function.
 
 ```ts
-import { define } from 'gunshi' // 'gunshi/definition', or '@gunshi/definition'
-import { withI18nResource } from '@gunshi/plugin-i18n'
+import { define } from 'gunshi' // alternative 'gunshi/definition', or '@gunshi/definition'
+import { withI18nResource, pluginId as i18nId } from '@gunshi/plugin-i18n'
 
 const basicCommand = define({
   name: 'test',
@@ -175,11 +226,10 @@ const basicCommand = define({
   run: ctx => console.log(`test: ${ctx.values.target}`)
 })
 
-const i18nCommand = withI18nResource(basicCommand, async ctx => {
-  const resource = await import(
-    `./path/to/resources/test/${ctx.extensions['g:i18n'].locale.toString()}.json`,
-    { with: { type: 'json' } }
-  ).then(l => l.default || l)
+const i18nCommand = withI18nResource(basicCommand, async locale => {
+  const resource = await import(`./path/to/resources/test/${locale.toString()}.json`, {
+    with: { type: 'json' }
+  }).then(l => l.default || l)
   return resource
 })
 ```
@@ -188,16 +238,16 @@ const i18nCommand = withI18nResource(basicCommand, async ctx => {
 
 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
+- `resolveKey(key: string, name?: string): string` - Resolves a custom key with command namespace if applicable
+- `resolveArgKey(key: string, name?: string): 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
+resolveKey('description', ctx.name) // Returns namespaced key for description
+resolveArgKey('verbose', ctx.name) // Returns 'arg:verbose' or 'command:arg:verbose' based on command namespace
 resolveBuiltInKey('USAGE') // Returns '_:USAGE'
 ```
 
@@ -226,35 +276,43 @@ While the `translate` function accepts keys without prefixes in most cases, usin
 #### Example Usage
 
 ```ts
-import { defineI18n, resolveKey, resolveArgKey, resolveBuiltInKey } from '@gunshi/plugin-i18n'
+import {
+  defineI18nWithTypes,
+  pluginId as i18nId,
+  resolveKey,
+  resolveArgKey,
+  resolveBuiltInKey
+} from '@gunshi/plugin-i18n'
 
-const command = defineI18n({
+import type { I18nExtension } from '@gunshi/plugin-i18n'
+
+const createCommand = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
   name: 'deploy',
   args: {
     environment: { type: 'string', short: 'e' },
     force: { type: 'boolean', short: 'f' }
   },
-  resource: async ctx => ({
+  resource: locale => ({
     description: 'Deploy application',
     'arg:environment': 'Target environment',
     'arg:force': 'Force deployment',
-    deploy_start: 'Starting deployment...',
-    deploy_success: 'Deployment completed successfully!'
+    start: 'Starting deployment...',
+    success: 'Deployment completed successfully!'
   }),
-  run: async ctx => {
-    const { translate } = ctx.extensions['g:i18n']
+  run: ctx => {
+    const { translate } = ctx.extensions[i18nId]
 
-    // Direct usage (need to prefix with command name)
-    console.log(translate('deploy:deploy_start'))
+    // Usage helper for custom keys (prefix with command name)
+    console.log(translate(resolveKey('start', ctx.name)))
 
     // Using helpers for explicit control
-    const envKey = resolveArgKey('environment', ctx)
+    const envKey = resolveArgKey('environment', ctx.name)
     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 key = resolveArgKey(arg, ctx.name)
       const description = translate(key)
       console.log(`${arg}: ${description}`)
     }
@@ -282,6 +340,7 @@ 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
+- `registerGlobalOptionResources: (option: string, resources: Record<string, string>) => void`: Register global option resources. If your global option description needs the localization, you can install resource of it at `extension` or `onExtension` hook
 
 ## 📝 Resource Key Naming Conventions
 
@@ -321,20 +380,21 @@ Here's an example illustrating the convention:
 ```ts
 import { defineI18n } from '@gunshi/plugin-i18n'
 
+// if you want to use `I18nExtension` in `run`, you should use `defineI18nWithTypes`, not `defineI18n`
 const command = defineI18n({
   name: 'my-command',
   args: {
     target: { type: 'string' },
     verbose: { type: 'boolean' }
   },
-  resource: async ctx => {
+  resource: locale => {
     // Example for 'en-US' locale
     return {
-      description: 'This is my command.', // No prefix
-      'arg:target': 'The target file to process.', // 'arg:' prefix
-      'arg:verbose': 'Enable verbose output.', // 'arg:' prefix
+      description: 'This is my command.', // built-in key, No prefix
+      'arg:target': 'The target file to process.', // argument key, 'arg:' prefix
+      'arg:verbose': 'Enable verbose output.', // argument key, 'arg:' prefix
       'arg:no-verbose': 'Disable verbose logging specifically.', // Optional custom translation for the negatable option
-      processing_message: 'Processing target...' // No prefix
+      processing_message: 'Processing target...' // custom keys, No prefix
     }
   },
   run: ctx => {
@@ -393,13 +453,15 @@ The `translate` function has different behaviors depending on the key type:
 This difference is important for error handling and fallback displays:
 
 ```ts
+import { resolveKey, resolveBuiltInKey } from '@gunshi/plugin-i18n'
+
 const { translate } = ctx.extensions['g:i18n']
 
 // Custom key not found
-translate('nonexistent_key') // Returns: ''
+translate(resolveKey('nonexistent_key', ctx.name)) // Returns: ''
 
 // Built-in key not found (if not overridden)
-translate('USAGE') // Returns: 'USAGE'
+translate(resolveBuiltInKey('USAGE')) // Returns: 'USAGE'
 ```
 
 ### Resource Loading Behavior
@@ -456,17 +518,19 @@ await cli(args, command, {
 The default translation adapter supports simple interpolation using `{$key}` syntax:
 
 ```ts
+import { pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'
+
 // In your resource
 const resource = {
   welcome: 'Welcome, {$name}!',
-  'items.count': 'You have {$count} items',
+  items_count: 'You have {$count} items',
   file_deleted: 'Deleted {$path}',
   error_message: 'Error: {$error}'
 }
 // In your command
-const { translate } = ctx.extensions['g:i18n']
+const { translate } = ctx.extensions[i18nId]
 translate(resolveKey('welcome'), { name: 'John' }) // "Welcome, John!"
-translate(resolveKey('items.count'), { count: 5 }) // "You have 5 items"
+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"
 ```
@@ -537,7 +601,7 @@ When you provide a custom translation adapter:
 
 ```ts
 import { cli } from 'gunshi'
-import i18n, { defineI18n } from '@gunshi/plugin-i18n'
+import i18n, { defineI18nWithTypes, pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'
 import {
   createCoreContext,
   getLocaleMessage,
@@ -546,6 +610,8 @@ import {
   translate as intlifyTranslate
 } from '@intlify/core' // need to install `npm install --save @intlify/core@next`
 
+import type { I18nExtension } from '@gunshi/plugin-i18n'
+
 // Create an Intlify translation adapter factory
 function createIntlifyAdapterFactory(options) {
   return new IntlifyTranslation(options)
@@ -606,7 +672,7 @@ class IntlifyTranslation {
 }
 
 // Define your command
-const command = defineI18n({
+const command = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
   name: 'greeter',
 
   args: {
@@ -622,10 +688,8 @@ const command = defineI18n({
   },
 
   // Define a resource fetcher with Intlify syntax
-  resource: async ctx => {
-    const locale = ctx.extensions['g:i18n'].locale.toString()
-
-    if (locale === 'ja-JP') {
+  resource: locale => {
+    if (locale.toString() === 'ja-JP') {
       return {
         description: '挨拶アプリケーション',
         'arg:name': '挨拶する相手の名前',
@@ -646,11 +710,11 @@ const command = defineI18n({
 
   run: ctx => {
     const { name = 'World', count } = ctx.values
-    const { translate } = ctx.extensions['g:i18n']
+    const { translate } = ctx.extensions[i18nId]
 
     // Use the translation function with Intlify
     const key = count > 1 ? 'greeting_plural' : 'greeting'
-    const message = translate(key, { name, count })
+    const message = translate(resolveKey(key, ctx.name), { name, count })
 
     console.log(message)
   }
@@ -685,43 +749,6 @@ 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)
@@ -729,3 +756,11 @@ See the [API References](./docs/index.md)
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-i18n?style=flat
+[npm-version-href]: https://npmjs.com/package/@gunshi/plugin-i18n@alpha
+[jsr-src]: https://jsr.io/badges/@gunshi/plugin-i18n
+[jsr-href]: https://jsr.io/@gunshi/plugin-i18n
+[install-size-src]: https://pkg-size.dev/badge/install/67599