@testforgejs/vue-test-plugin-i18n 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -24,10 +24,56 @@ npm install -D @testforgejs/vue-test-plugin-i18n@beta
 yarn add -D @testforgejs/vue-test-plugin-i18n@beta
 ```
 
-> `@testforgejs/vue-test-core` is required.
+> `@testforgejs/vue-test-core` and `vue-i18n` are required.
 
 ## Usage
 
+### Using plugin defaults
+
+The plugin provides a project-independent default configuration through `getDefaultOptions()`:
+
+```typescript
+import { createTestFramework } from "@testforgejs/vue-test-core";
+import { i18nPlugin } from "@testforgejs/vue-test-plugin-i18n";
+
+const framework = createTestFramework({
+  presets: {
+    default: {
+      manifest: [
+        {
+          module: i18nPlugin,
+          enabled: true,
+        },
+      ],
+      defaults: {
+        i18n: i18nPlugin.getDefaultOptions(),
+      },
+    },
+  },
+});
+```
+
+`getDefaultOptions()` returns an options factory suitable for use in a preset.
+
+The plugin-provided defaults are equivalent to:
+
+```typescript
+{
+  legacy: false,
+  globalInjection: true,
+}
+```
+
+These defaults configure Vue I18n to use Composition API mode and make the global Composer properties and functions available to components through Vue's global properties.
+
+The plugin intentionally does not define application-specific localization behavior such as the active locale, fallback locale, messages, formats, or warning policy.
+
+Plugin defaults are **not applied automatically**. Adding the plugin to a preset manifest declares that the plugin is available and whether it is enabled; the preset explicitly decides whether to use the plugin-provided defaults or provide its own configuration.
+
+### Providing custom options
+
+You can define the Vue I18n configuration directly in the preset instead:
+
 ```typescript
 import { createTestFramework } from "@testforgejs/vue-test-core";
 import { i18nPlugin } from "@testforgejs/vue-test-plugin-i18n";
@@ -44,7 +90,14 @@ const framework = createTestFramework({
       defaults: {
         i18n: () => ({
           legacy: false,
+          globalInjection: true,
           locale: "en",
+          fallbackLocale: "en",
+          messages: {
+            en: {
+              hello: "Hello",
+            },
+          },
         }),
       },
     },
@@ -52,12 +105,138 @@ const framework = createTestFramework({
 });
 ```
 
-`defaults.i18n` is an options factory. Each invocation produces a fresh Vue I18n options object for the current pipeline context.
+Using `getDefaultOptions()` is optional. Define custom defaults when tests require application-specific locales, messages, fallback behavior, formatting, warning policy, or other Vue I18n configuration.
+
+## Configuration
+
+### Vue I18n options
+
+The plugin integrates TestForge with Vue I18n by creating a Vue I18n instance from the provided `createI18n()` options.
+
+Configuration fields such as `legacy`, `globalInjection`, `locale`, `fallbackLocale`, `messages`, `missingWarn`, and `fallbackWarn` belong to Vue I18n.
+
+TestForge does not define an alternative configuration format for Vue I18n. The integration passes these options to Vue I18n when creating the plugin instance.
+
+Refer to the Vue I18n documentation for the complete set of supported `createI18n()` options and their behavior.
+
+### TestForge plugin defaults
+
+The defaults provided by this package intentionally contain only:
+
+```typescript
+{
+  legacy: false,
+  globalInjection: true,
+}
+```
+
+`legacy: false` selects Vue I18n's Composition API mode. This provides a modern Vue 3 integration and allows components to use APIs such as `useI18n()`.
+
+`globalInjection: true` makes global Composer properties and functions such as `$t`, `$d`, and `$n` available to components through Vue's global properties.
+
+Setting `globalInjection` explicitly also provides consistent behavior across the supported Vue I18n versions instead of depending on version-specific defaults.
+
+The plugin does not explicitly configure:
+
+```typescript
+locale;
+fallbackLocale;
+messages;
+missingWarn;
+fallbackWarn;
+```
+
+These options therefore retain the behavior defined by Vue I18n unless a preset provides them explicitly.
+
+This keeps plugin defaults project-independent and avoids TestForge choosing an application locale, translation catalog, fallback strategy, or warning policy.
+
+For example, a project-specific preset can provide its actual localization configuration:
+
+```typescript
+defaults: {
+  i18n: () => ({
+    legacy: false,
+    globalInjection: true,
+    locale: "en",
+    fallbackLocale: "en",
+    messages: {
+      en: {
+        hello: "Hello",
+      },
+    },
+  }),
+},
+```
+
+If a test environment intentionally needs to suppress missing-translation or fallback warnings, that policy can also be configured explicitly:
+
+```typescript
+defaults: {
+  i18n: () => ({
+    legacy: false,
+    globalInjection: true,
+    missingWarn: false,
+    fallbackWarn: false,
+  }),
+},
+```
+
+### Options factories
+
+Preset defaults are defined as factories:
+
+```typescript
+defaults: {
+  i18n: () => ({
+    legacy: false,
+    globalInjection: true,
+  }),
+},
+```
+
+Each invocation of the factory produces a fresh options object for the current TestForge pipeline execution.
+
+`i18nPlugin.getDefaultOptions()` follows the same contract: it returns an options factory rather than a shared options object.
+
+This allows presets to choose explicitly between:
+
+- the project-independent defaults provided by the plugin; and
+- a custom Vue I18n configuration defined by the preset.
+
+## Package exports
+
+The package provides both descriptive and standardized plugin exports:
+
+```typescript
+import { i18nPlugin, plugin, PLUGIN_NAME } from "@testforgejs/vue-test-plugin-i18n";
+```
+
+### `i18nPlugin`
+
+The descriptive Vue I18n plugin module export.
+
+### `plugin`
+
+The standardized plugin module export.
+
+It references the same plugin module as `i18nPlugin` and provides a consistent package-level API across TestForge plugin packages.
+
+### `PLUGIN_NAME`
+
+The standardized plugin identifier export.
+
+For this package:
+
+```typescript
+PLUGIN_NAME === "i18n";
+```
+
+The standardized `plugin` and `PLUGIN_NAME` exports are useful for tooling and other code that works with TestForge plugin packages generically.
 
 ## Supported versions
 
-- Vue I18n: 9–11
-- Vue: 3.x
+- Vue: 3.3.0 or higher
+- Vue I18n: 9.x, 10.x, and 11.x
 
 ## Documentation
 

package/dist/index.cjs

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  i18nPlugin: () => i18nPlugin
+  PLUGIN_NAME: () => I18N_PLUGIN_NAME,
+  i18nPlugin: () => i18nPlugin,
+  plugin: () => i18nPlugin
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -31,14 +33,27 @@ function createI18nPlugin(options) {
   return (0, import_vue_test_core.createPluginInstance)(import_vue_i18n.createI18n, options);
 }
 
+// src/defaults.ts
+var defaultOptions = () => () => ({
+  legacy: false,
+  globalInjection: true
+});
+
+// src/constants/constants.ts
+var I18N_PLUGIN_NAME = "i18n";
+
 // src/module/i18nPlugin.ts
 var i18nPlugin = {
-  getName: () => "i18n",
+  getName: () => I18N_PLUGIN_NAME,
   getDefinition: () => ({
-    create: createI18nPlugin
-  })
+    create: createI18nPlugin,
+    supportsInstanceReferences: true
+  }),
+  getDefaultOptions: defaultOptions
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  i18nPlugin
+  PLUGIN_NAME,
+  i18nPlugin,
+  plugin
 });

package/dist/index.d.cts

@@ -1,11 +1,37 @@
 import { I18nOptions, I18n } from 'vue-i18n';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+/**
+ * Stable TestForge identifier for the Vue I18n plugin.
+ *
+ * Use this identifier when declaring plugin configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const I18N_PLUGIN_NAME: "i18n";
 
 /**
  * Configuration options for the Vue I18n test plugin.
  *
- * This interface integrates standard internationalization parameters (`I18nOptions` from `vue-i18n`)
- * with TestForge test kernel control options.
+ * Combines standard Vue I18n configuration (`I18nOptions` from `vue-i18n`)
+ * with TestForge plugin control options.
+ *
+ * @example
+ * Configure the managed Vue I18n plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     i18n: {
+ *       locale: "en",
+ *       messages: {
+ *         en: {
+ *           hello: "Hello World",
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
  *
  * @see {@link I18nOptions} for configuring locales, fallback languages, and translation messages.
  * @see {@link PluginControlOptions} for instance capturing and exposure mechanisms.
@@ -15,10 +41,8 @@ type VueTestI18nOptions = I18nOptions & PluginControlOptions<I18n>;
 /**
  * TestForge core type augmentation for Vue I18n integration.
  *
- * This module registers the i18n configuration under the global plugin options map,
- * enabling full type safety when defining internationalization options in tests.
- *
- * @module I18nAugmentation
+ * Registers the public plugin configuration and runtime instance types
+ * used by TestForge's managed plugin APIs.
  */
 declare module "@testforgejs/vue-test-core" {
     /**
@@ -26,29 +50,27 @@ declare module "@testforgejs/vue-test-core" {
      */
     interface PluginOptionsMap {
         /**
-         * Configuration for the `i18n` plugin.
-         * Accepts a {@link VueTestI18nOptions} object to manage localization and translations.
-         *
-         * @example
-         * ```ts
-         * factory({}, {
-         *   plugins: {
-         *     i18n: {
-         *       locale: "en",
-         *       messages: { en: { hello: "Hello World" } }
-         *     }
-         *   }
-         * });
-         * ```
+         * Configuration accepted by the managed `i18n` plugin.
          */
-        i18n: VueTestI18nOptions;
+        [I18N_PLUGIN_NAME]: VueTestI18nOptions;
+    }
+    /**
+     * Global map for managed plugin runtime instances.
+     */
+    interface PluginInstanceMap {
+        /**
+         * Runtime Vue I18n instance created by the managed `i18n` plugin.
+         */
+        [I18N_PLUGIN_NAME]: I18n;
     }
 }
 
 /**
- * Vue I18n plugin module definition for the TestForge framework.
- * Automatically handles internationalization setup inside test environments.
+ * Managed Vue I18n plugin module for TestForge.
+ *
+ * Provides the runtime definition for creating Vue I18n instances
+ * and exposes the default configuration used by TestForge-managed presets.
  */
-declare const i18nPlugin: PluginModule<I18n, VueTestI18nOptions>;
+declare const i18nPlugin: PluginModuleWithDefaults<I18n, VueTestI18nOptions>;
 
-export { type VueTestI18nOptions, i18nPlugin };
+export { I18N_PLUGIN_NAME as PLUGIN_NAME, type VueTestI18nOptions, i18nPlugin, i18nPlugin as plugin };

package/dist/index.d.ts

@@ -1,11 +1,37 @@
 import { I18nOptions, I18n } from 'vue-i18n';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+/**
+ * Stable TestForge identifier for the Vue I18n plugin.
+ *
+ * Use this identifier when declaring plugin configuration
+ * in presets and other plugin-aware TestForge APIs.
+ */
+declare const I18N_PLUGIN_NAME: "i18n";
 
 /**
  * Configuration options for the Vue I18n test plugin.
  *
- * This interface integrates standard internationalization parameters (`I18nOptions` from `vue-i18n`)
- * with TestForge test kernel control options.
+ * Combines standard Vue I18n configuration (`I18nOptions` from `vue-i18n`)
+ * with TestForge plugin control options.
+ *
+ * @example
+ * Configure the managed Vue I18n plugin for a component test:
+ *
+ * ```ts
+ * factory({}, {
+ *   plugins: {
+ *     i18n: {
+ *       locale: "en",
+ *       messages: {
+ *         en: {
+ *           hello: "Hello World",
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
  *
  * @see {@link I18nOptions} for configuring locales, fallback languages, and translation messages.
  * @see {@link PluginControlOptions} for instance capturing and exposure mechanisms.
@@ -15,10 +41,8 @@ type VueTestI18nOptions = I18nOptions & PluginControlOptions<I18n>;
 /**
  * TestForge core type augmentation for Vue I18n integration.
  *
- * This module registers the i18n configuration under the global plugin options map,
- * enabling full type safety when defining internationalization options in tests.
- *
- * @module I18nAugmentation
+ * Registers the public plugin configuration and runtime instance types
+ * used by TestForge's managed plugin APIs.
  */
 declare module "@testforgejs/vue-test-core" {
     /**
@@ -26,29 +50,27 @@ declare module "@testforgejs/vue-test-core" {
      */
     interface PluginOptionsMap {
         /**
-         * Configuration for the `i18n` plugin.
-         * Accepts a {@link VueTestI18nOptions} object to manage localization and translations.
-         *
-         * @example
-         * ```ts
-         * factory({}, {
-         *   plugins: {
-         *     i18n: {
-         *       locale: "en",
-         *       messages: { en: { hello: "Hello World" } }
-         *     }
-         *   }
-         * });
-         * ```
+         * Configuration accepted by the managed `i18n` plugin.
          */
-        i18n: VueTestI18nOptions;
+        [I18N_PLUGIN_NAME]: VueTestI18nOptions;
+    }
+    /**
+     * Global map for managed plugin runtime instances.
+     */
+    interface PluginInstanceMap {
+        /**
+         * Runtime Vue I18n instance created by the managed `i18n` plugin.
+         */
+        [I18N_PLUGIN_NAME]: I18n;
     }
 }
 
 /**
- * Vue I18n plugin module definition for the TestForge framework.
- * Automatically handles internationalization setup inside test environments.
+ * Managed Vue I18n plugin module for TestForge.
+ *
+ * Provides the runtime definition for creating Vue I18n instances
+ * and exposes the default configuration used by TestForge-managed presets.
  */
-declare const i18nPlugin: PluginModule<I18n, VueTestI18nOptions>;
+declare const i18nPlugin: PluginModuleWithDefaults<I18n, VueTestI18nOptions>;
 
-export { type VueTestI18nOptions, i18nPlugin };
+export { I18N_PLUGIN_NAME as PLUGIN_NAME, type VueTestI18nOptions, i18nPlugin, i18nPlugin as plugin };

package/dist/index.js

@@ -5,13 +5,26 @@ function createI18nPlugin(options) {
   return createPluginInstance(createI18n, options);
 }
 
+// src/defaults.ts
+var defaultOptions = () => () => ({
+  legacy: false,
+  globalInjection: true
+});
+
+// src/constants/constants.ts
+var I18N_PLUGIN_NAME = "i18n";
+
 // src/module/i18nPlugin.ts
 var i18nPlugin = {
-  getName: () => "i18n",
+  getName: () => I18N_PLUGIN_NAME,
   getDefinition: () => ({
-    create: createI18nPlugin
-  })
+    create: createI18nPlugin,
+    supportsInstanceReferences: true
+  }),
+  getDefaultOptions: defaultOptions
 };
 export {
-  i18nPlugin
+  I18N_PLUGIN_NAME as PLUGIN_NAME,
+  i18nPlugin,
+  i18nPlugin as plugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testforgejs/vue-test-plugin-i18n",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "type": "module",
   "description": "Official TestForge plugin for vue-i18n integration in component tests",
   "homepage": "https://github.com/testforgejs/testforge#readme",
@@ -44,11 +44,17 @@
   "author": "Roman Levchenko",
   "peerDependencies": {
     "vue-i18n": ">=9.0.0 <12.0.0",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "@testforgejs/vue-test-core": "1.0.0-beta.4"
   },
   "devDependencies": {
     "vue-i18n": "^11.4.8",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "@testforgejs/vue-test-core": "1.0.0-beta.4"
+  },
+  "testforge": {
+    "plugin": {
+      "schemaVersion": 1,
+      "displayName": "Vue I18n"
+    }
   },
   "scripts": {
     "build": "tsup",