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

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,26 @@ 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
-  })
+  }),
+  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,5 +1,7 @@
 import { I18nOptions, I18n } from 'vue-i18n';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+declare const I18N_PLUGIN_NAME: "i18n";
 
 /**
  * Configuration options for the Vue I18n test plugin.
@@ -41,7 +43,7 @@ declare module "@testforgejs/vue-test-core" {
          * });
          * ```
          */
-        i18n: VueTestI18nOptions;
+        [I18N_PLUGIN_NAME]: VueTestI18nOptions;
     }
 }
 
@@ -49,6 +51,6 @@ declare module "@testforgejs/vue-test-core" {
  * Vue I18n plugin module definition for the TestForge framework.
  * Automatically handles internationalization setup inside test environments.
  */
-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,5 +1,7 @@
 import { I18nOptions, I18n } from 'vue-i18n';
-import { PluginControlOptions, PluginModule } from '@testforgejs/vue-test-core';
+import { PluginControlOptions, PluginModuleWithDefaults } from '@testforgejs/vue-test-core';
+
+declare const I18N_PLUGIN_NAME: "i18n";
 
 /**
  * Configuration options for the Vue I18n test plugin.
@@ -41,7 +43,7 @@ declare module "@testforgejs/vue-test-core" {
          * });
          * ```
          */
-        i18n: VueTestI18nOptions;
+        [I18N_PLUGIN_NAME]: VueTestI18nOptions;
     }
 }
 
@@ -49,6 +51,6 @@ declare module "@testforgejs/vue-test-core" {
  * Vue I18n plugin module definition for the TestForge framework.
  * Automatically handles internationalization setup inside test environments.
  */
-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,25 @@ 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
-  })
+  }),
+  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.3",
   "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.3"
   },
   "devDependencies": {
     "vue-i18n": "^11.4.8",
-    "@testforgejs/vue-test-core": "1.0.0-beta.2"
+    "@testforgejs/vue-test-core": "1.0.0-beta.3"
+  },
+  "testforge": {
+    "plugin": {
+      "schemaVersion": 1,
+      "displayName": "Vue I18n"
+    }
   },
   "scripts": {
     "build": "tsup",