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

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.0.1] - 2024-07-26
+
+- initial release

package/README.md

@@ -0,0 +1,92 @@
+# @open-xchange/vite-plugin-i18next-gettext
+
+A Vite plugin that allows using [i18next](https://www.i18next.com/) in source code, while using gettext with `.po` and `.pot` files under the hood.
+
+This plugin has the following responsibilities:
+
+- Vite's development server will convert `.po` files imported in source code to i18next-compatible JSON data on-the-fly.
+- When building the project, `.po` files will be converted to and written as i18next-compatible JSON files into the bundle.
+- When building the project, 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.
+
+## Usage
+
+### Vite
+
+Add the plugin to your Vite configuration:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite" // or "vitest/config"
+import i18nextPlugin from "@open-xchange/vite-plugin-i18next-gettext"
+
+export default defineConfig(() => {
+
+  // ...
+
+  plugins: [
+    // ...
+
+    i18nextPlugin({
+      poFiles: "i18n/*.po",
+      srcFiles: "src/**/*.{js,jsx,ts,tsx}",
+      potFile: "main.pot",
+      projectName: "My Project",
+    }),
+  ],
+})
+```
+
+#### Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `poFiles` | `string\|string[]` | _required_ | Glob pattern(s) for all `.po` files containing the translations. |
+| `srcFiles` | `string\|string[]` | _required_ | Glob pattern(s) for all source files to be scanned for UI strings. |
+| `potFile` | `string` | _required_ | Path to the `.pot` file to be generated when building the project, relative to the build output directory. |
+| `projectName` | `string` | _required_ | The project name to be inserted into the `.pot` file under the key "Project-Id-Version". |
+
+### Source Code
+
+Import the `.po` files directly when setting up i18next, for example:
+
+```ts
+// src/@types/globals.d.ts
+
+declare module "*.po" {
+  import { ResourceKey } from "i18next"
+  const resource: ResourceKey
+  export default resource
+}
+```
+
+```ts
+// src/hooks/useTranslation.ts
+
+import i18next from "i18next"
+import type { BackendModule, ReadCallback } from "i18next"
+
+class POFileBackend implements BackendModule {
+
+  // type needs to be provided statically (expected by i18next runtime), and as instance prop (for typings only)
+  static readonly type = "backend"
+  readonly type = "backend"
+
+  init(): void {
+    // nothing to do
+  }
+
+  async read(lang: string, _ns: string, cb: ReadCallback): Promise<void> {
+    try {
+      const module = await import(`./i18n/${lang}.po`) as typeof import("*.po")
+      cb(null, module.default)
+    } catch (error) {
+      cb(error as Error, null)
+    }
+  }
+}
+
+i18next.use(POFileBackend)
+
+export default useTranslation
+```

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import type { Plugin } from "vite";
+export interface VitePluginI18nextGettextOptions {
+    /**
+     * Glob pattern(s) for all `.po` files containing the translations.
+     *
+     * @example
+     * {
+     *   poFiles: "i18n/*.po",
+     *   // ...
+     * }
+     */
+    poFiles: string | string[];
+    /**
+     * Glob pattern(s) for all source files to be scanned for UI strings.
+     *
+     * @example
+     * {
+     *   srcFiles: "src/*.{js,ts}",
+     *   // ...
+     * }
+     */
+    srcFiles: string | string[];
+    /**
+     * Path to the `.pot` file to be generated when building the project,
+     * relative to the build output directory.
+     *
+     * @example
+     * {
+     *   potFile: "i18n/main.pot",
+     *   // ...
+     * }
+     */
+    potFile: string;
+    /**
+     * The project name to be inserted into the `.pot` file under the key
+     * "Project-Id-Version".
+     */
+    projectName: string;
+}
+export declare const PROJECT_NAME = "@open-xchange/vite-plugin-i18next-gettext";
+/**
+ * Vite plugin for using i18next with gettext `.po` files under the hood.
+ *
+ * @param options
+ *  Plugin configuration.
+ *
+ * @returns
+ *  The Vite plugin object.
+ */
+export default function vitePluginI18nextGettext(options: VitePluginI18nextGettextOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,74 @@
+/*
+* Copyright (C) Open-Xchange GmbH, Germany <info@open-xchange.com>
+*
+* This program is proprietary software and licensed to you under Open-Xchange
+* GmbH's Software License Agreement.
+*/
+import { readFile } from "node:fs/promises";
+import pm from "picomatch";
+import converter from "gettext-converter";
+import { transform as Transformer } from "i18next-parser";
+import * as vfs from "vinyl-fs";
+// constants ==================================================================
+export const PROJECT_NAME = "@open-xchange/vite-plugin-i18next-gettext";
+// plugin =====================================================================
+/**
+ * Vite plugin for using i18next with gettext `.po` files under the hood.
+ *
+ * @param options
+ *  Plugin configuration.
+ *
+ * @returns
+ *  The Vite plugin object.
+ */
+export default function vitePluginI18nextGettext(options) {
+    return {
+        name: PROJECT_NAME,
+        // register esbuild loader for `.po` files (load as plain text)
+        config: () => ({
+            optimizeDeps: {
+                esbuildOptions: {
+                    loader: { ".po": "text" },
+                },
+            },
+        }),
+        // convert `.po` files to i18next JSON v4
+        async load(id) {
+            if (!pm.isMatch(id, options.poFiles)) {
+                return;
+            }
+            // read the `.po` file and convert it to i18next JSON
+            const data = await readFile(id, { encoding: "utf8" });
+            const json = converter.po2i18next(data, { compatibilityJSON: "v4" });
+            // generate a module that exports a _stringified_ JSON object
+            const code = `export default ${JSON.stringify(json)};`;
+            return { code, map: { mappings: "" } };
+        },
+        // parse source files and create a `.pot` file
+        async generateBundle() {
+            // parse all source files and collect the translatable strings
+            const json = await new Promise((resolve, reject) => {
+                // the transformer instance that parses all source files, and assembles the translation catalogue
+                const transformer = new Transformer({
+                    failOnWarnings: true,
+                    contextSeparator: "",
+                    keySeparator: false,
+                    lineEnding: "lf",
+                    namespaceSeparator: false,
+                    // locales to generate catalogue for
+                    locales: ["en"],
+                });
+                // warnings and errors
+                transformer.on("warning", (message) => reject(new Error(message)));
+                transformer.on("error", (message) => reject(new Error(message)));
+                // fulfil promise with the resulting JSON data
+                transformer.on("data", (file) => resolve(file.contents.toString("utf8")));
+                // pipe all source files to transformer
+                vfs.src(options.srcFiles).pipe(transformer);
+            });
+            // convert JSON data to `.pot` file
+            const source = converter.i18next2po("en", json, { project: options.projectName, compatibilityJSON: "v4" });
+            this.emitFile({ type: "asset", fileName: options.potFile, source });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@open-xchange/vite-plugin-i18next-gettext",
+    "version": "0.0.1",
+    "description": "Vite integration of i18next using gettext",
+    "repository": {
+        "url": "https://gitlab.open-xchange.com/fspd/npm-packages/vite-plugin-i18next-gettext"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": "18.18.0 || ^20.9.0 || >=21.1.0"
+    },
+    "packageManager": "yarn@4.3.1",
+    "type": "module",
+    "exports": "./dist/index.js",
+    "scripts": {
+        "prepare": "husky",
+        "prepack": "yarn build && yarn lint",
+        "build": "npx --yes rimraf dist && tsc",
+        "lint": "eslint ."
+    },
+    "lint-staged": {
+        "*.{js,ts,json}": "yarn lint"
+    },
+    "devDependencies": {
+        "@open-xchange/linter-presets": "0.1.9",
+        "@types/node": "20.14.12",
+        "@types/vinyl-fs": "3.0.5",
+        "eslint": "9.7.0",
+        "husky": "9.1.2",
+        "typescript": "5.5.4",
+        "vinyl": "3.0.0",
+        "vite": "5.3.5"
+    },
+    "peerDependencies": {
+        "vite": "^5.3"
+    },
+    "resolutions": {
+        "semver": "^7.6.2"
+    },
+    "dependencies": {
+        "gettext-converter": "1.3.0",
+        "i18next-parser": "9.0.0",
+        "picomatch": "4.0.2",
+        "vinyl-fs": "4.0.0"
+    }
+}