@open-xchange/rolldown-plugin-i18next-gettext 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## `1.2.0` – 2026-Apr-15
+
+- added: switched back to direct imports of PO files
+- removed: virtual modules for namespaces
+
 ## `1.1.0` – 2026-Apr-15
 
 - removed: direct imports of PO files

package/README.md

@@ -4,9 +4,19 @@ A [rolldown](https://rolldown.rs/) plugin that allows building libraries or appl
 
 This plugin has the following responsibilities:
 
-- Virtual module imports provide translation catalogs from selected `.po` files in a single namespace dictionary.
+- All `.po` files imported in source code will be converted to i18next translation catalogs.
 - The source code will be scanned for translation strings (`t` function calls), and `.pot` files containing all strings will be generated into the output directory. Supports i18next namespaces (one `.pot` file per namespace).
 
+## Installation
+
+```sh
+npm install -D @open-xchange/rolldown-plugin-i18next-gettext
+# or
+pnpm add -D @open-xchange/rolldown-plugin-i18next-gettext
+# or
+yarn add -D @open-xchange/rolldown-plugin-i18next-gettext
+```
+
 ## Configuration
 
 Add the plugin to your rolldown configuration (or compatible configurations like Vite or tsdown):
@@ -19,10 +29,6 @@ import i18nextPlugin from '@open-xchange/rolldown-plugin-i18next-gettext'
 export default defineConfig(() => {
   plugins: [
     i18nextPlugin({
-      poFiles: {
-        default: 'i18n/*.po',
-        custom: 'i18n/custom/*.po',
-      },
       srcFiles: 'src/**/*.{js,jsx,ts,tsx}',
       potFiles: '[NAMESPACE].pot',
       projectName: 'My Project',
@@ -33,40 +39,34 @@ export default defineConfig(() => {
 
 ### Options
 
-Type `Globs` can be a single glob pattern as string, or an array of glob patterns.
-
-```ts
-type Globs = string | readonly string[]
-```
-
 | Name | Type | Default | Description |
 | - | - | - | - |
-| `poFiles` | `Record<string,Globs>` | _required_ | Glob pattern(s) for all PO files to be converted to i18next translation catalogs, mapped by i18next namespace identifiers. |
-| `srcFiles` | `Globs` | `src/**/*.{js,jsx,ts,tsx}` | Glob pattern(s) for all source files to be scanned for UI strings for the POT file generator. |
+| `poFiles` | `string\|string[]` | `**/*.po` | Glob pattern(s) for all PO files to be converted when imported in source code. |
+| `srcFiles` | `string\|string[]` | `src/**/*.{js,jsx,ts,tsx}` | Glob pattern(s) for all source files to be scanned for UI strings for the POT file generator. |
 | `potFiles` | `string` | `[NAMESPACE].pot` | Path to and filename of the generated POT files, relative to the build output directory. Must contain the placeholder `[NAMESPACE]` if the project contains translation strings in different i18next namespaces. |
 | `projectName` | `string` | _required_ | The project name to be inserted into the POT file under the key 'Project-Id-Version'. May contain the placeholder `[NAMESPACE]` |
 
 ## Usage
 
-Register TypeScript type definitions for the virtual module imports:
+Register TypeScript type definitions for the PO file imports:
 
 ```json
 // tsconfig.json
 {
   "types": [
-    "@open-xchange/rolldown-plugin-i18next-gettext/virtual"
+    "@open-xchange/rolldown-plugin-i18next-gettext/client"
   ],
 }
 ```
 
-Import translation catalogs in source code:
+Load translation catalogs in source code on demand via i18next backend plugin:
 
 ```ts
-// use namespace specifiers as configured in plugin's option `poFiles`
-import translations from 'virtual:i18next-namespace:default'
+import i18next from 'i18next'
+import resourcesToBackend from 'i18next-resources-to-backend'
 
-i18next.init({ resources: {} });
-for (const [lang, catalog] of Object.entries(translations)) {
-  i18next.addResources(lang, 'translation', catalog)
-}
+i18next.use(resourcesToBackend(async (lang: string, namespace: string) => {
+  // build appropriate path to the PO files
+  return await import(`../i18n/${namespace}/${lang}.po`)
+}))
 ```

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+
+declare module '*.po' {
+
+  /**
+   * Shape of an i18next JSON translation catalog (mapping from source keys to
+   * translations) for a single language, converted from a gettext PO file.
+   */
+  export type Catalog = Record<string, string>
+
+  const catalog: Catalog
+  export default catalog
+}

package/dist/index.d.mts

@@ -1,16 +1,18 @@
 import { Plugin } from "rolldown";
 
 //#region src/index.d.ts
-type Globs = string | readonly string[];
 /**
  * Configuration options for the plugin '@open-xchange/rolldown-plugin-i18next-gettext'.
  */
 interface PluginI18nextGettextOptions {
   /**
-   * Glob pattern(s) for all PO files to be converted to i18next translation
-   * catalogs, mapped by i18next namespace identifiers.
+   * Glob pattern(s) for all PO files to be converted when imported in source
+   * code.
+   *
+   * @default
+   *  '**\/*.po'
    */
-  poFiles: Record<string, Globs>;
+  poFiles?: string | readonly string[];
   /**
    * Glob pattern(s) for all source files to be scanned for UI strings for the
    * POT file generator.
@@ -18,7 +20,7 @@ interface PluginI18nextGettextOptions {
    * @default
    *  'src/**\/*.{js,jsx,ts,tsx}'
    */
-  srcFiles?: Globs;
+  srcFiles?: string | readonly string[];
   /**
    * Path to and filename of the generated POT files, relative to the build
    * output directory. Must contain the placeholder `[NAMESPACE]` if the
@@ -49,5 +51,5 @@ declare const PROJECT_NAME = "@open-xchange/rolldown-plugin-i18next-gettext";
  */
 declare function pluginI18nextGettext(options: PluginI18nextGettextOptions): Plugin;
 //#endregion
-export { Globs, PROJECT_NAME, PluginI18nextGettextOptions, pluginI18nextGettext as default };
+export { PROJECT_NAME, PluginI18nextGettextOptions, pluginI18nextGettext as default };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;KAYY,KAAA;;AAAZ;;UAKiB,2BAAA;EALA;;AAKjB;;EAME,OAAA,EAAS,MAAA,SAAe,KAAA;EAAA;;;;;;;EASxB,QAAA,GAAW,KAAA;EAAX;;;;;;AAwBF;;EAdE,QAAA;EAcuB;;AAAkD;;EARzE,WAAA;AAAA;;;;cAQW,YAAA;;;;;;;;;;iBAaW,oBAAA,CAAqB,OAAA,EAAS,2BAAA,GAA8B,MAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;AAUA;UAAiB,2BAAA;;;;;;;;EASf,OAAA;EAiCW;;;;;AAA8D;;EAxBzE,QAAA;EAqCwF;;;;;;;;EA3BxF,QAAA;;;;;EAMA,WAAA;AAAA;;;;cAQW,YAAA;;;;;;;;;;iBAaW,oBAAA,CAAqB,OAAA,EAAS,2BAAA,GAA8B,MAAA"}

package/dist/index.mjs

@@ -1,6 +1,4 @@
-import * as path from "node:path";
-import { createJsonModule, getRemainder, prefixRegex } from "@open-xchange/rolldown-utils";
-import { glob } from "tinyglobby";
+import { createJsonModule } from "@open-xchange/rolldown-utils";
 import { parsePoFile, parseSourceFiles } from "@open-xchange/i18next-po-parser";
 //#region src/index.ts
 /**
@@ -17,31 +15,16 @@ const PROJECT_NAME = "@open-xchange/rolldown-plugin-i18next-gettext";
 *  The rolldown plugin object.
 */
 function pluginI18nextGettext(options) {
-	const VIRTUAL_MODULE_PREFIX = "virtual:i18next-namespace:";
+	const { poFiles = "**/*.po", srcFiles = "src/**/*.{js,jsx,ts,tsx}", potFiles = "[NAMESPACE].pot", projectName } = options;
 	return {
 		name: PROJECT_NAME,
-		resolveId: {
-			filter: { id: prefixRegex(VIRTUAL_MODULE_PREFIX) },
-			handler: (id) => `\0${id}`
-		},
 		load: {
-			filter: { id: prefixRegex(`\0${VIRTUAL_MODULE_PREFIX}`) },
+			filter: { id: poFiles },
 			async handler(id) {
-				const key = getRemainder(id, `\0${VIRTUAL_MODULE_PREFIX}`);
-				if (!key) this.error("missing namespace specifier");
-				const globs = options.poFiles[key];
-				if (!globs) this.error(`invalid namespace specifier: ${key}`);
-				const catalogs = Object.create(null);
-				const filePaths = await glob(globs);
-				await Promise.all(filePaths.map(async (filePath) => {
-					const basename = path.parse(filePath).name.replaceAll("_", "-");
-					catalogs[basename] = await parsePoFile(filePath);
-				}));
-				return createJsonModule(catalogs);
+				return createJsonModule(await parsePoFile(id));
 			}
 		},
 		async generateBundle() {
-			const { srcFiles = "src/**/*.{js,jsx,ts,tsx}", potFiles = "[NAMESPACE].pot", projectName } = options;
 			const catalogs = await parseSourceFiles({
 				files: srcFiles,
 				project: projectName

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["\nimport * as path from 'node:path'\n\nimport type { Plugin } from 'rolldown'\nimport { prefixRegex, getRemainder, createJsonModule } from '@open-xchange/rolldown-utils'\nimport { glob } from 'tinyglobby'\nimport { parsePoFile, parseSourceFiles } from '@open-xchange/i18next-po-parser'\n\nimport type { Namespace } from 'virtual:i18next-namespace:*'\n\n// types ======================================================================\n\nexport type Globs = string | readonly string[]\n\n/**\n * Configuration options for the plugin '@open-xchange/rolldown-plugin-i18next-gettext'.\n */\nexport interface PluginI18nextGettextOptions {\n\n  /**\n   * Glob pattern(s) for all PO files to be converted to i18next translation\n   * catalogs, mapped by i18next namespace identifiers.\n   */\n  poFiles: Record<string, Globs>\n\n  /**\n   * Glob pattern(s) for all source files to be scanned for UI strings for the\n   * POT file generator.\n   *\n   * @default\n   *  'src/**\\/*.{js,jsx,ts,tsx}'\n   */\n  srcFiles?: Globs\n\n  /**\n   * Path to and filename of the generated POT files, relative to the build\n   * output directory. Must contain the placeholder `[NAMESPACE]` if the\n   * project contains translation strings in different i18next namespaces.\n   *\n   * @default\n   *  '[NAMESPACE].pot'\n   */\n  potFiles?: string\n\n  /**\n   * The project name to be inserted into the POT files under the key\n   * 'Project-Id-Version'. May contain the placeholder `[NAMESPACE]`.\n   */\n  projectName: string\n}\n\n// constants ==================================================================\n\n/**\n * Identifier of this plugin.\n */\nexport const PROJECT_NAME = '@open-xchange/rolldown-plugin-i18next-gettext'\n\n// plugin =====================================================================\n\n/**\n * Rolldown plugin for using i18next with gettext `.po` files under the hood.\n *\n * @param options\n *  Plugin configuration.\n *\n * @returns\n *  The rolldown plugin object.\n */\nexport default function pluginI18nextGettext(options: PluginI18nextGettextOptions): Plugin {\n\n  // prefix for virtual modules generated by this plugin\n  const VIRTUAL_MODULE_PREFIX = 'virtual:i18next-namespace:'\n\n  return {\n    name: PROJECT_NAME,\n\n    // handle virtual module identifiers\n    resolveId: {\n      filter: { id: prefixRegex(VIRTUAL_MODULE_PREFIX) },\n      handler: id => `\\0${id}`,\n    },\n\n    // convert PO files to i18next namespace records\n    load: {\n      filter: { id: prefixRegex(`\\0${VIRTUAL_MODULE_PREFIX}`) },\n      async handler(id) {\n        const key = getRemainder(id, `\\0${VIRTUAL_MODULE_PREFIX}`)\n        if (!key) this.error('missing namespace specifier')\n        const globs = options.poFiles[key]\n        if (!globs) this.error(`invalid namespace specifier: ${key}`)\n        const catalogs = Object.create(null) as Namespace\n        const filePaths = await glob(globs)\n        await Promise.all(filePaths.map(async filePath => {\n          const basename = path.parse(filePath).name.replaceAll('_', '-')\n          catalogs[basename] = await parsePoFile(filePath)\n        }))\n        return createJsonModule(catalogs)\n      },\n    },\n\n    // parse source files and create POT files per namespace\n    async generateBundle() {\n\n      // resolve default options\n      const { srcFiles = 'src/**/*.{js,jsx,ts,tsx}', potFiles = '[NAMESPACE].pot', projectName } = options\n\n      // parse all source files and extract translations\n      const catalogs = await parseSourceFiles({ files: srcFiles, project: projectName })\n\n      // warn when writing multiple POT files to same file location\n      if ((catalogs.size > 1) && !potFiles.includes('[NAMESPACE]')) {\n        this.error('multiple POT files written to same file location (missing placeholder `[NAMESPACE]` in option potFile)')\n      }\n\n      // add all POT files as assets to the bundle\n      for (const [namespace, source] of catalogs) {\n        const fileName = potFiles.replaceAll('[NAMESPACE]', namespace)\n        this.emitFile({ type: 'asset', fileName, source })\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;;;AAwDA,MAAa,eAAe;;;;;;;;;;AAa5B,SAAwB,qBAAqB,SAA8C;CAGzF,MAAM,wBAAwB;AAE9B,QAAO;EACL,MAAM;EAGN,WAAW;GACT,QAAQ,EAAE,IAAI,YAAY,sBAAsB,EAAE;GAClD,UAAS,OAAM,KAAK;GACrB;EAGD,MAAM;GACJ,QAAQ,EAAE,IAAI,YAAY,KAAK,wBAAwB,EAAE;GACzD,MAAM,QAAQ,IAAI;IAChB,MAAM,MAAM,aAAa,IAAI,KAAK,wBAAwB;AAC1D,QAAI,CAAC,IAAK,MAAK,MAAM,8BAA8B;IACnD,MAAM,QAAQ,QAAQ,QAAQ;AAC9B,QAAI,CAAC,MAAO,MAAK,MAAM,gCAAgC,MAAM;IAC7D,MAAM,WAAW,OAAO,OAAO,KAAK;IACpC,MAAM,YAAY,MAAM,KAAK,MAAM;AACnC,UAAM,QAAQ,IAAI,UAAU,IAAI,OAAM,aAAY;KAChD,MAAM,WAAW,KAAK,MAAM,SAAS,CAAC,KAAK,WAAW,KAAK,IAAI;AAC/D,cAAS,YAAY,MAAM,YAAY,SAAS;MAChD,CAAC;AACH,WAAO,iBAAiB,SAAS;;GAEpC;EAGD,MAAM,iBAAiB;GAGrB,MAAM,EAAE,WAAW,4BAA4B,WAAW,mBAAmB,gBAAgB;GAG7F,MAAM,WAAW,MAAM,iBAAiB;IAAE,OAAO;IAAU,SAAS;IAAa,CAAC;AAGlF,OAAK,SAAS,OAAO,KAAM,CAAC,SAAS,SAAS,cAAc,CAC1D,MAAK,MAAM,yGAAyG;AAItH,QAAK,MAAM,CAAC,WAAW,WAAW,UAAU;IAC1C,MAAM,WAAW,SAAS,WAAW,eAAe,UAAU;AAC9D,SAAK,SAAS;KAAE,MAAM;KAAS;KAAU;KAAQ,CAAC;;;EAGvD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["\nimport type { Plugin, GeneralHookFilter } from 'rolldown'\nimport { createJsonModule } from '@open-xchange/rolldown-utils'\nimport { parsePoFile, parseSourceFiles } from '@open-xchange/i18next-po-parser'\n\n// types ======================================================================\n\n/**\n * Configuration options for the plugin '@open-xchange/rolldown-plugin-i18next-gettext'.\n */\nexport interface PluginI18nextGettextOptions {\n\n  /**\n   * Glob pattern(s) for all PO files to be converted when imported in source\n   * code.\n   *\n   * @default\n   *  '**\\/*.po'\n   */\n  poFiles?: string | readonly string[]\n\n  /**\n   * Glob pattern(s) for all source files to be scanned for UI strings for the\n   * POT file generator.\n   *\n   * @default\n   *  'src/**\\/*.{js,jsx,ts,tsx}'\n   */\n  srcFiles?: string | readonly string[]\n\n  /**\n   * Path to and filename of the generated POT files, relative to the build\n   * output directory. Must contain the placeholder `[NAMESPACE]` if the\n   * project contains translation strings in different i18next namespaces.\n   *\n   * @default\n   *  '[NAMESPACE].pot'\n   */\n  potFiles?: string\n\n  /**\n   * The project name to be inserted into the POT files under the key\n   * 'Project-Id-Version'. May contain the placeholder `[NAMESPACE]`.\n   */\n  projectName: string\n}\n\n// constants ==================================================================\n\n/**\n * Identifier of this plugin.\n */\nexport const PROJECT_NAME = '@open-xchange/rolldown-plugin-i18next-gettext'\n\n// plugin =====================================================================\n\n/**\n * Rolldown plugin for using i18next with gettext `.po` files under the hood.\n *\n * @param options\n *  Plugin configuration.\n *\n * @returns\n *  The rolldown plugin object.\n */\nexport default function pluginI18nextGettext(options: PluginI18nextGettextOptions): Plugin {\n\n  // resolve default options\n  const {\n    poFiles = '**/*.po',\n    srcFiles = 'src/**/*.{js,jsx,ts,tsx}',\n    potFiles = '[NAMESPACE].pot',\n    projectName,\n  } = options\n\n  return {\n    name: PROJECT_NAME,\n\n    // convert PO files to i18next namespace records\n    load: {\n      filter: { id: poFiles as GeneralHookFilter },\n      async handler(id) {\n        return createJsonModule(await parsePoFile(id))\n      },\n    },\n\n    // parse source files and create POT files per namespace\n    async generateBundle() {\n\n      // parse all source files and extract translations\n      const catalogs = await parseSourceFiles({ files: srcFiles, project: projectName })\n\n      // warn when writing multiple POT files to same file location\n      if ((catalogs.size > 1) && !potFiles.includes('[NAMESPACE]')) {\n        this.error('multiple POT files written to same file location (missing placeholder `[NAMESPACE]` in option potFile)')\n      }\n\n      // add all POT files as assets to the bundle\n      for (const [namespace, source] of catalogs) {\n        const fileName = potFiles.replaceAll('[NAMESPACE]', namespace)\n        this.emitFile({ type: 'asset', fileName, source })\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;AAoDA,MAAa,eAAe;;;;;;;;;;AAa5B,SAAwB,qBAAqB,SAA8C;CAGzF,MAAM,EACJ,UAAU,WACV,WAAW,4BACX,WAAW,mBACX,gBACE;AAEJ,QAAO;EACL,MAAM;EAGN,MAAM;GACJ,QAAQ,EAAE,IAAI,SAA8B;GAC5C,MAAM,QAAQ,IAAI;AAChB,WAAO,iBAAiB,MAAM,YAAY,GAAG,CAAC;;GAEjD;EAGD,MAAM,iBAAiB;GAGrB,MAAM,WAAW,MAAM,iBAAiB;IAAE,OAAO;IAAU,SAAS;IAAa,CAAC;AAGlF,OAAK,SAAS,OAAO,KAAM,CAAC,SAAS,SAAS,cAAc,CAC1D,MAAK,MAAM,yGAAyG;AAItH,QAAK,MAAM,CAAC,WAAW,WAAW,UAAU;IAC1C,MAAM,WAAW,SAAS,WAAW,eAAe,UAAU;AAC9D,SAAK,SAAS;KAAE,MAAM;KAAS;KAAU;KAAQ,CAAC;;;EAGvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/rolldown-plugin-i18next-gettext",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Rolldown integration of i18next using gettext PO files",
   "repository": {
     "type": "git",
@@ -15,8 +15,8 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./package.json": "./package.json",
-    "./virtual": {
-      "types": "./dist/virtual.d.ts"
+    "./client": {
+      "types": "./dist/client.d.ts"
     }
   },
   "files": [
@@ -25,22 +25,31 @@
   ],
   "dependencies": {
     "@open-xchange/i18next-po-parser": "^1.4.0",
-    "tinyglobby": "^0.2.16",
     "@open-xchange/rolldown-utils": "^1.0.0"
   },
   "devDependencies": {
+    "@open-xchange/rolldown-plugin-dynamic-import-vars": "^1.0.2",
     "@vitest/coverage-v8": "^4.1.3",
     "i18next": "^26.0.4",
     "rolldown": "^1.0.0-rc.15",
-    "tsdown": "^0.21.7",
+    "tsdown": "^0.21.8",
     "vitest": "^4.1.3",
+    "@open-xchange/vitest-plugin-extended": "^1.6.0",
+    "@open-xchange/vitest-plugin-utils": "^1.1.1",
     "@open-xchange/linter-presets": "^1.22.0",
-    "@open-xchange/tsconfig": "^0.0.3",
-    "@open-xchange/vitest-plugin-utils": "^1.0.0",
-    "@open-xchange/vitest-plugin-extended": "^1.6.0"
+    "@open-xchange/tsconfig": "^0.0.3"
   },
   "peerDependencies": {
-    "rolldown": "*"
+    "rolldown": "*",
+    "tsdown": "*"
+  },
+  "peerDependenciesMeta": {
+    "rolldown": {
+      "optional": true
+    },
+    "tsdown": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsdown",

package/dist/virtual.d.ts

@@ -1,18 +0,0 @@
-
-declare module 'virtual:i18next-namespace:*' {
-
-  /**
-   * Shape of an i18next JSON translation catalog (mapping from source keys to
-   * translations) for a single language, converted from a gettext PO file.
-   */
-  export type Catalog = Record<string, string>
-
-  /**
-   * Shape of an i18next JSON translation namespace (mapping from language
-   * codes to translation catalogs), converted from multiple gettext PO files.
-   */
-  export type Namespace = Record<string, Catalog>
-
-  const namespace: Namespace
-  export default namespace
-}