@flyingrobots/bijou-i18n-tools-xlsx 4.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 James Ross
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,15 @@
+# @flyingrobots/bijou-i18n-tools-xlsx
+
+XLSX workbook adapters for Bijou localization exchange workflows.
+
+`@flyingrobots/bijou-i18n-tools-xlsx` builds on `@flyingrobots/bijou-i18n-tools` and provides:
+
+- `ExchangeWorkbook` -> XLSX byte serialization
+- XLSX byte parsing back into `ExchangeWorkbook`
+- explicit translation-workbook header validation
+- deterministic workbook sheet ordering
+
+This package intentionally keeps spreadsheet-provider logic out of the pure `@flyingrobots/bijou-i18n-tools` package.
+
+Dependency note:
+As of 2026-04-02, `xlsx` is installed from the official SheetJS CDN tarball rather than the npm registry release, which is stale and carries known security advisories. See https://docs.sheetjs.com/docs/getting-started/installation/nodejs/ for the current upstream installation guidance.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { parseExchangeWorkbookXlsx, serializeExchangeWorkbookXlsx, } from './xlsx.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { parseExchangeWorkbookXlsx, serializeExchangeWorkbookXlsx, } from './xlsx.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,WAAW,CAAC"}

package/dist/xlsx.d.ts

@@ -0,0 +1,4 @@
+import type { ExchangeWorkbook } from '@flyingrobots/bijou-i18n-tools';
+export declare function serializeExchangeWorkbookXlsx(workbook: ExchangeWorkbook): Uint8Array;
+export declare function parseExchangeWorkbookXlsx(input: Uint8Array | ArrayBuffer): ExchangeWorkbook;
+//# sourceMappingURL=xlsx.d.ts.map

package/dist/xlsx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.d.ts","sourceRoot":"","sources":["../src/xlsx.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAA0B,MAAM,gCAAgC,CAAC;AA+D/F,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,UAAU,CAgBpF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,gBAAgB,CA4C3F"}

package/dist/xlsx.js

@@ -0,0 +1,105 @@
+import * as XLSX from 'xlsx';
+const REQUIRED_TRANSLATION_COLUMNS = [
+    'namespace',
+    'id',
+    'kind',
+    'sourceLocale',
+    'targetLocale',
+    'status',
+    'sourceHash',
+    'description',
+    'sourceValueKind',
+    'sourceValue',
+    'translatedValueKind',
+    'translatedValue',
+];
+function normalizeCell(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return String(value);
+}
+function toWorkbookInput(input) {
+    return input instanceof Uint8Array ? input : new Uint8Array(input);
+}
+function assertWorkbookHeaders(columns, sheetName) {
+    if (columns.length === 0) {
+        throw new Error(`Invalid XLSX workbook sheet: missing header row in ${sheetName}`);
+    }
+    const seen = new Set();
+    for (const [index, column] of columns.entries()) {
+        if (column.trim() === '') {
+            throw new Error(`Invalid XLSX workbook sheet: missing required header at column ${index + 1} in ${sheetName}`);
+        }
+        if (seen.has(column)) {
+            throw new Error(`Invalid XLSX workbook sheet: duplicate header ${column} in ${sheetName}`);
+        }
+        seen.add(column);
+    }
+    for (const required of REQUIRED_TRANSLATION_COLUMNS) {
+        if (!seen.has(required)) {
+            throw new Error(`Invalid XLSX workbook sheet: missing required header ${required} in ${sheetName}`);
+        }
+    }
+}
+function assertWorkbookRow(row, context) {
+    for (const key of REQUIRED_TRANSLATION_COLUMNS) {
+        if (typeof row[key] !== 'string') {
+            throw new Error(`Invalid XLSX workbook sheet: missing ${key} in ${context}`);
+        }
+    }
+    return row;
+}
+export function serializeExchangeWorkbookXlsx(workbook) {
+    const book = XLSX.utils.book_new();
+    for (const sheet of workbook.sheets) {
+        const rows = [
+            [...sheet.columns],
+            ...sheet.rows.map((row) => sheet.columns.map((column) => {
+                const value = row[column];
+                return typeof value === 'string' ? value : '';
+            })),
+        ];
+        const worksheet = XLSX.utils.aoa_to_sheet(rows);
+        XLSX.utils.book_append_sheet(book, worksheet, sheet.name);
+    }
+    return new Uint8Array(XLSX.write(book, { bookType: 'xlsx', type: 'array' }));
+}
+export function parseExchangeWorkbookXlsx(input) {
+    const workbook = XLSX.read(toWorkbookInput(input), { type: 'array' });
+    const sheets = workbook.SheetNames.map((sheetName) => {
+        const worksheet = workbook.Sheets[sheetName];
+        if (worksheet === undefined) {
+            throw new Error(`Invalid XLSX workbook: missing sheet ${sheetName}`);
+        }
+        const matrix = XLSX.utils.sheet_to_json(worksheet, {
+            header: 1,
+            raw: false,
+            defval: '',
+        });
+        if (matrix.length === 0) {
+            throw new Error(`Invalid XLSX workbook sheet: missing header row in ${sheetName}`);
+        }
+        const header = matrix[0];
+        if (!Array.isArray(header)) {
+            throw new Error(`Invalid XLSX workbook sheet: malformed header row in ${sheetName}`);
+        }
+        const columns = header.map((value) => normalizeCell(value));
+        assertWorkbookHeaders(columns, sheetName);
+        const rows = matrix.slice(1).map((entry, rowIndex) => {
+            const cells = Array.isArray(entry) ? entry : [];
+            const record = Object.fromEntries(columns.map((column, index) => [column, normalizeCell(cells[index])]));
+            return assertWorkbookRow(record, `${sheetName}:${rowIndex + 2}`);
+        });
+        return {
+            name: sheetName,
+            columns,
+            rows,
+        };
+    });
+    return {
+        version: 1,
+        sheets,
+    };
+}
+//# sourceMappingURL=xlsx.js.map

package/dist/xlsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.js","sourceRoot":"","sources":["../src/xlsx.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@flyingrobots/bijou-i18n-tools-xlsx",
+  "version": "4.1.0",
+  "description": "XLSX workbook adapters for Bijou localization exchange workflows.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "tsc -b",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@flyingrobots/bijou-i18n-tools": "4.1.0",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "i18n",
+    "localization",
+    "translation",
+    "xlsx",
+    "spreadsheet",
+    "bijou"
+  ],
+  "author": "James Ross <james@flyingrobots.dev>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flyingrobots/bijou.git",
+    "directory": "packages/bijou-i18n-tools-xlsx"
+  },
+  "homepage": "https://github.com/flyingrobots/bijou",
+  "bugs": "https://github.com/flyingrobots/bijou/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}