@open-xchange/rolldown-plugin-i18next-gettext 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## `0.0.1` – 2026-Apr-10
+
+- initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Open-Xchange GmbH, Germany <info@open-xchange.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @open-xchange/rolldown-plugin-i18next-gettext
+
+A [rolldown](https://rolldown.rs/) plugin that allows building libraries using [i18next](https://www.i18next.com/) in source code with gettext's `.po` and `.pot` files under the hood.
+
+This plugin has the following responsibilities:
+
+- All `.po` files imported in source code will be converted to i18next translation catalogs.
+- A virtual module import makes all translation catalogs from selected `.po` files available in a single dictionary to be able to pick translation languages dynamically.
+- The source code will be scanned for translation strings (`t` function calls), and a `.pot` file containing all strings will be generated into the output directory.
+
+## Configuration
+
+Add the plugin to your rolldown configuration (or compatible configurations like Vite or tsdown):
+
+```ts
+// rolldown.config.ts
+
+import { defineConfig } from 'rolldown'
+import i18nextPlugin from '@open-xchange/rolldown-plugin-i18next-gettext'
+
+export default defineConfig(() => {
+  plugins: [
+    i18nextPlugin({
+      poFiles: 'i18n/*.po',
+      potFiles: {
+        srcFiles: 'src/**/*.{js,jsx,ts,tsx}',
+        outputPath: '[NAMESPACE].pot',
+        projectName: 'My Project',
+      },
+    }),
+  ],
+})
+```
+
+### Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `poFiles` | `string\|string[]` | _required_ | Glob pattern(s) for all PO files containing the translations. |
+| `potFiles` | | | Configuration for the source code scanner and POT file generator. If omitted, no POT files will be generated. |
+| `potFiles.srcFiles` | `string\|string[]` | `src/**/*.{js,jsx,ts,tsx}` | Glob pattern(s) for all source files to be scanned for UI strings. |
+| `potFiles.outputPath` | `string` | `[NAMESPACE].pot` | Path to and filename of the generated POT files, relative to the build output directory. Should contain the placeholder `[NAMESPACE]` if the project contains translation strings in different i18next namespaces. |
+| `potFiles.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:i18next-po-catalogs` module import:
+
+```json
+// tsconfig.json
+{
+  "types": [
+    "@open-xchange/rolldown-plugin-i18next-gettext/virtual"
+  ],
+}
+```
+
+Use the virtual modules in your code:
+
+```ts
+// import catalogs for all languages
+import catalogs from 'virtual:i18next-po-catalogs'
+console.log(catalogs.de_DE)
+
+// import catalog for one language
+import catalog from 'i18n/de_DE.po'
+console.log(catalog)
+```

package/dist/index.d.mts

@@ -0,0 +1,65 @@
+import { Plugin } from "rolldown";
+
+//#region src/index.d.ts
+/**
+ * Configuration options for the plugin '@open-xchange/rolldown-plugin-i18next-gettext'.
+ */
+interface RolldownPluginI18nextGettextOptions {
+  /**
+   * Glob pattern(s) for all PO files containing the translations. Matching PO
+   * files will be converted to i18next translation catalogs when imported in
+   * source code directly, and will be included in the virtual module providing
+   * a dictionary of all translation catalogs, mapped by the base names of the
+   * PO files.
+   */
+  poFiles: string | readonly string[];
+  /**
+   * Configuration for the source code scanner and POT file generator. If
+   * omitted, no POT files will be generated.
+   */
+  potFiles?: {
+    /**
+     * Glob pattern(s) for all source files to be scanned for UI strings.
+     *
+     * @default
+     *  'src/**\/*.{js,jsx,ts,tsx}'
+     */
+    srcFiles?: string | readonly string[];
+    /**
+     * Path to and filename of the generated POT files, relative to the build
+     * output directory. Should contain the placeholder `[NAMESPACE]` if the
+     * project contains translation strings in different i18next namespaces.
+     *
+     * @default
+     *  '[NAMESPACE].pot'
+     */
+    outputPath?: string;
+    /**
+     * The project name to be inserted into the POT files under the key
+     * 'Project-Id-Version'. May contain the placeholder `[NAMESPACE]`.
+     */
+    projectName: string;
+  };
+}
+/**
+ * Identifier of this plugin.
+ */
+declare const PROJECT_NAME = "@open-xchange/rolldown-plugin-i18next-gettext";
+/**
+ * Identifier of the virtual module providing all translation catalogs in a
+ * single object.
+ */
+declare const VIRTUAL_MODULE_ID = "virtual:i18next-po-catalogs";
+/**
+ * Rolldown plugin for using i18next with gettext `.po` files under the hood.
+ *
+ * @param options
+ *  Plugin configuration.
+ *
+ * @returns
+ *  The rolldown plugin object.
+ */
+declare function rolldownPluginI18nextGettext(options: RolldownPluginI18nextGettextOptions): Plugin;
+//#endregion
+export { PROJECT_NAME, RolldownPluginI18nextGettextOptions, VIRTUAL_MODULE_ID, rolldownPluginI18nextGettext as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;AAaA;UAAiB,mCAAA;;;;;;;;EASf,OAAA;EA8Ba;AASf;;;EAjCE,QAAA;IAiCuB;AAMzB;;;;;IA/BI,QAAA;IA6DgD;;;;;;;;IAnDhD,UAAA;;;;;IAMA,WAAA;EAAA;AAAA;;;;cASS,YAAA;;;;;cAMA,iBAAA;;;;;;;;;;iBA8BW,4BAAA,CAA6B,OAAA,EAAS,mCAAA,GAAsC,MAAA"}

package/dist/index.mjs

@@ -0,0 +1,82 @@
+import * as path from "node:path";
+import pm from "picomatch";
+import { glob } from "tinyglobby";
+import { parsePoFile, parseSourceFiles } from "@open-xchange/i18next-po-parser";
+//#region src/index.ts
+/**
+* Identifier of this plugin.
+*/
+const PROJECT_NAME = "@open-xchange/rolldown-plugin-i18next-gettext";
+/**
+* Identifier of the virtual module providing all translation catalogs in a
+* single object.
+*/
+const VIRTUAL_MODULE_ID = "virtual:i18next-po-catalogs";
+/**
+* Creates the source code of a module with a default export with the passed
+* stringified JSON data.
+*
+* @param json
+*  The JSON data to be exported from the generated source file.
+*
+* @returns
+*  The generated source file.
+*/
+function createModule(json) {
+	return {
+		code: `export default ${JSON.stringify(json)}`,
+		map: { mappings: "" }
+	};
+}
+/**
+* Rolldown plugin for using i18next with gettext `.po` files under the hood.
+*
+* @param options
+*  Plugin configuration.
+*
+* @returns
+*  The rolldown plugin object.
+*/
+function rolldownPluginI18nextGettext(options) {
+	const RESOLVED_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+	return {
+		name: PROJECT_NAME,
+		resolveId(id) {
+			return id === "virtual:i18next-po-catalogs" ? RESOLVED_MODULE_ID : null;
+		},
+		async load(id) {
+			if (id === RESOLVED_MODULE_ID) {
+				const map = {};
+				for (const entry of await glob(options.poFiles)) {
+					const basename = path.parse(entry).name;
+					map[basename] = await parsePoFile(entry);
+				}
+				return createModule(map);
+			}
+			const relPath = path.relative(process.cwd(), id).replaceAll(path.sep, path.posix.sep);
+			if (!pm.isMatch(relPath, options.poFiles)) return;
+			return createModule(await parsePoFile(id));
+		},
+		async generateBundle() {
+			if (!options.potFiles) return;
+			const { srcFiles = "src/**/*.{js,jsx,ts,tsx}", outputPath = "[NAMESPACE].pot", projectName } = options.potFiles;
+			const catalogs = await parseSourceFiles({
+				files: srcFiles,
+				project: projectName
+			});
+			if (catalogs.size > 1 && !outputPath.includes("[NAMESPACE]")) this.error("multiple POT files written to same file location (missing placeholder `[NAMESPACE]` in option potFile)");
+			for (const [namespace, source] of catalogs) {
+				const fileName = outputPath.replaceAll("[NAMESPACE]", namespace);
+				this.emitFile({
+					type: "asset",
+					fileName,
+					source
+				});
+			}
+		}
+	};
+}
+//#endregion
+export { PROJECT_NAME, VIRTUAL_MODULE_ID, rolldownPluginI18nextGettext as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["\nimport * as path from 'node:path'\n\nimport type { LoadResult, Plugin } from 'rolldown'\nimport pm from 'picomatch'\nimport { glob } from 'tinyglobby'\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 RolldownPluginI18nextGettextOptions {\n\n  /**\n   * Glob pattern(s) for all PO files containing the translations. Matching PO\n   * files will be converted to i18next translation catalogs when imported in\n   * source code directly, and will be included in the virtual module providing\n   * a dictionary of all translation catalogs, mapped by the base names of the\n   * PO files.\n   */\n  poFiles: string | readonly string[]\n\n  /**\n   * Configuration for the source code scanner and POT file generator. If\n   * omitted, no POT files will be generated.\n   */\n  potFiles?: {\n\n    /**\n     * Glob pattern(s) for all source files to be scanned for UI strings.\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. Should contain the placeholder `[NAMESPACE]` if the\n     * project contains translation strings in different i18next namespaces.\n     *\n     * @default\n     *  '[NAMESPACE].pot'\n     */\n    outputPath?: 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\n// constants ==================================================================\n\n/**\n * Identifier of this plugin.\n */\nexport const PROJECT_NAME = '@open-xchange/rolldown-plugin-i18next-gettext'\n\n/**\n * Identifier of the virtual module providing all translation catalogs in a\n * single object.\n */\nexport const VIRTUAL_MODULE_ID = 'virtual:i18next-po-catalogs'\n\n// functions ==================================================================\n\n/**\n * Creates the source code of a module with a default export with the passed\n * stringified JSON data.\n *\n * @param json\n *  The JSON data to be exported from the generated source file.\n *\n * @returns\n *  The generated source file.\n */\nfunction createModule(json: unknown): LoadResult {\n  const code = `export default ${JSON.stringify(json)}`\n  return { code, map: { mappings: '' } }\n}\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 rolldownPluginI18nextGettext(options: RolldownPluginI18nextGettextOptions): Plugin {\n\n  const RESOLVED_MODULE_ID = `\\0${VIRTUAL_MODULE_ID}`\n\n  return {\n    name: PROJECT_NAME,\n\n    // recognize virtual module identifier\n    resolveId(id) {\n      return (id === VIRTUAL_MODULE_ID) ? RESOLVED_MODULE_ID : null\n    },\n\n    // convert PO files to i18next JSON v4\n    async load(id) {\n\n      // virtual module: build single dictionary with all languages from PO files\n      if (id === RESOLVED_MODULE_ID) {\n        const map = {} as Record<string, unknown>\n        for (const entry of await glob(options.poFiles)) {\n          const basename = path.parse(entry).name\n          map[basename] = await parsePoFile(entry)\n        }\n        return createModule(map)\n      }\n\n      // try to find a matching PO file\n      const relPath = path.relative(process.cwd(), id).replaceAll(path.sep, path.posix.sep)\n      if (!pm.isMatch(relPath, options.poFiles as pm.Glob)) { return }\n\n      // read the PO file and convert it to i18next JSON\n      return createModule(await parsePoFile(id))\n    },\n\n    // parse source files and create POT files per namespace\n    async generateBundle() {\n\n      // early exit if no POT files will be generated\n      if (!options.potFiles) return\n      const { srcFiles = 'src/**/*.{js,jsx,ts,tsx}', outputPath = '[NAMESPACE].pot', projectName } = options.potFiles\n\n      // parse all source files and extract translations\n      const catalogs = await parseSourceFiles({ files: srcFiles as pm.Glob, project: projectName })\n\n      // warn when writing multiple POT files to same file location\n      if ((catalogs.size > 1) && !outputPath.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 = outputPath.replaceAll('[NAMESPACE]', namespace)\n        this.emitFile({ type: 'asset', fileName, source })\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;;;AA6DA,MAAa,eAAe;;;;;AAM5B,MAAa,oBAAoB;;;;;;;;;;;AAcjC,SAAS,aAAa,MAA2B;AAE/C,QAAO;EAAE,MADI,kBAAkB,KAAK,UAAU,KAAK;EACpC,KAAK,EAAE,UAAU,IAAI;EAAE;;;;;;;;;;;AAcxC,SAAwB,6BAA6B,SAAsD;CAEzG,MAAM,qBAAqB,KAAK;AAEhC,QAAO;EACL,MAAM;EAGN,UAAU,IAAI;AACZ,UAAQ,OAAA,gCAA4B,qBAAqB;;EAI3D,MAAM,KAAK,IAAI;AAGb,OAAI,OAAO,oBAAoB;IAC7B,MAAM,MAAM,EAAE;AACd,SAAK,MAAM,SAAS,MAAM,KAAK,QAAQ,QAAQ,EAAE;KAC/C,MAAM,WAAW,KAAK,MAAM,MAAM,CAAC;AACnC,SAAI,YAAY,MAAM,YAAY,MAAM;;AAE1C,WAAO,aAAa,IAAI;;GAI1B,MAAM,UAAU,KAAK,SAAS,QAAQ,KAAK,EAAE,GAAG,CAAC,WAAW,KAAK,KAAK,KAAK,MAAM,IAAI;AACrF,OAAI,CAAC,GAAG,QAAQ,SAAS,QAAQ,QAAmB,CAAI;AAGxD,UAAO,aAAa,MAAM,YAAY,GAAG,CAAC;;EAI5C,MAAM,iBAAiB;AAGrB,OAAI,CAAC,QAAQ,SAAU;GACvB,MAAM,EAAE,WAAW,4BAA4B,aAAa,mBAAmB,gBAAgB,QAAQ;GAGvG,MAAM,WAAW,MAAM,iBAAiB;IAAE,OAAO;IAAqB,SAAS;IAAa,CAAC;AAG7F,OAAK,SAAS,OAAO,KAAM,CAAC,WAAW,SAAS,cAAc,CAC5D,MAAK,MAAM,yGAAyG;AAItH,QAAK,MAAM,CAAC,WAAW,WAAW,UAAU;IAC1C,MAAM,WAAW,WAAW,WAAW,eAAe,UAAU;AAChE,SAAK,SAAS;KAAE,MAAM;KAAS;KAAU;KAAQ,CAAC;;;EAGvD"}

package/dist/virtual.d.ts

@@ -0,0 +1,18 @@
+
+declare module '*.po' {
+
+  export type Catalog = Record<string, string>
+
+  const catalog: Catalog
+  export default catalog
+}
+
+declare module 'virtual:i18next-po-catalogs' {
+
+  // eslint-disable-next-line n/no-missing-import
+  import { Catalog } from 'test.po'
+  export { Catalog }
+
+  const catalogs: Record<string, Catalog>
+  export default catalogs
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@open-xchange/rolldown-plugin-i18next-gettext",
+  "version": "0.0.1",
+  "description": "Rolldown integration of i18next using gettext",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.open-xchange.com/fspd/commons/plugins.git",
+    "directory": "packages/rolldown-plugin-i18next-gettext"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.18"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./virtual": {
+      "types": "./dist/virtual.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.*"
+  ],
+  "dependencies": {
+    "@open-xchange/i18next-po-parser": "^1.4.0",
+    "picomatch": "^4.0.4",
+    "tinyglobby": "^0.2.16"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.3",
+    "i18next": "^26.0.4",
+    "rolldown": "1.0.0-rc.15",
+    "tsdown": "^0.21.7",
+    "vitest": "^4.1.3",
+    "@open-xchange/linter-presets": "^1.22.0",
+    "@open-xchange/vitest-plugin-extended": "^1.6.0",
+    "@open-xchange/tsconfig": "^0.0.3",
+    "@open-xchange/vitest-plugin-utils": "^0.0.3"
+  },
+  "peerDependencies": {
+    "rolldown": "*"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "coverage": "vitest run --coverage",
+    "lint": "tsc && tsc --project src && tsc --project test && eslint .",
+    "test": "vitest run",
+    "verify": "pnpm build && pnpm lint && pnpm test"
+  }
+}