@nexpress/xliff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexpress
+
+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,23 @@
+# @nexpress/xliff
+
+XLIFF translation export/import for
+[NexPress](https://github.com/nexpress-cms/nexpress) i18n.
+
+Round-trips translation strings between the NexPress i18n surface and
+XLIFF 2.x — the format the major translation memory tools (memoQ,
+Trados, Smartcat, Crowdin's XLIFF connector) understand.
+
+## Install
+
+```bash
+pnpm add @nexpress/xliff
+```
+
+## Usage
+
+See the i18n guide:
+[docs/i18n.md](https://github.com/nexpress-cms/nexpress/blob/main/docs/i18n.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import { NpAuthUser } from '@nexpress/core';
+
+interface XliffExportOptions {
+    /**
+     * Restrict to specific collection slugs. Defaults to every
+     * registered i18n-enabled collection. Non-i18n collections are
+     * always skipped — they have no `locale` / `translation_group_id`
+     * to round-trip.
+     */
+    collections?: string[];
+    /**
+     * Locale to treat as the source. Defaults to the configured
+     * `defaultLocale`. Translators don't usually translate from a
+     * non-default locale, but the option is here for sites that
+     * author primarily in another language.
+     */
+    sourceLocale?: string;
+    /**
+     * Target locales to emit a file for. Defaults to every
+     * configured locale except the source.
+     */
+    targetLocales?: string[];
+    /**
+     * Operator running the export. Threaded into `findDocuments` so
+     * private-visibility rows still surface to a translator's bundle
+     * (#383). Without it, the pipeline's anonymous-visibility guard
+     * silently filters every `visibility = "private"` document out
+     * of both the source scan and the existing-target scan, so
+     * private docs can't round-trip through XLIFF at all.
+     */
+    user?: NpAuthUser;
+}
+interface XliffExportFile {
+    /** Suggested filename, e.g. `discussions-en-ko.xliff`. */
+    name: string;
+    collection: string;
+    sourceLocale: string;
+    targetLocale: string;
+    /** Number of (doc × translatable field) units in this file. */
+    unitCount: number;
+    xml: string;
+}
+interface XliffExportBundle {
+    files: XliffExportFile[];
+    summary: {
+        /** Number of source-locale documents seen across all files. */
+        docCount: number;
+        /** Sum of `unitCount` across `files`. */
+        fieldCount: number;
+        sourceLocale: string;
+        targetLocales: string[];
+    };
+}
+/**
+ * Walk every i18n-enabled collection (or the subset the caller
+ * named), pull every published source-locale row, and emit one
+ * XLIFF 1.2 file per (collection, target locale). Each file's
+ * `<file original=…>` attribute encodes routing back as
+ * `{collectionSlug}/{translationGroupId}` so the import path can
+ * resolve siblings without rescanning the registry.
+ *
+ * Pre-existing target translations (sibling rows already in the
+ * target locale) are loaded so their values populate `<target>`
+ * — this lets translators see what's already done and edit
+ * incrementally rather than re-translating from scratch on each
+ * round-trip.
+ */
+declare function exportXliff(options?: XliffExportOptions): Promise<XliffExportBundle>;
+declare class XliffExportError extends Error {
+    readonly name = "XliffExportError";
+}
+
+interface XliffImportOptions {
+    /** XLIFF 1.2 XML body to apply. */
+    xml: string;
+    /** Actor recorded on writes (createdBy / updatedBy / audit). */
+    user: NpAuthUser;
+    /**
+     * When true, parses + resolves siblings + reports what would
+     * happen, but writes nothing. Useful for previewing a
+     * translator's bundle before applying.
+     */
+    dryRun?: boolean;
+}
+interface XliffImportApplied {
+    collection: string;
+    /** Document id that was created or updated. */
+    docId: string;
+    locale: string;
+    operation: "create" | "update";
+    /** Number of trans-units actually written for this doc. */
+    unitCount: number;
+}
+interface XliffImportSkip {
+    reason: string;
+    collection?: string;
+    groupId?: string;
+    locale?: string;
+}
+interface XliffImportResult {
+    applied: XliffImportApplied[];
+    skipped: XliffImportSkip[];
+    /**
+     * Whether this run actually touched the database. False when
+     * `dryRun: true` or when every file matched a `skipped` rule.
+     */
+    wrote: boolean;
+}
+/**
+ * Apply a translator's XLIFF bundle. For each `<file>`:
+ *
+ *   1. Parse `original` as `{collectionSlug}/{translationGroupId}`.
+ *   2. Look up the source-locale sibling (used as the canonical
+ *      shape when creating a new target row — non-translatable
+ *      fields are copied across).
+ *   3. Look up the target-locale sibling. If found, UPDATE its
+ *      translatable fields with each unit's `<target>`. If not,
+ *      CREATE a new sibling using the source data + `<target>`
+ *      values for translatable fields.
+ *
+ * Empty `<target>` text is skipped — a translator who hasn't yet
+ * translated that unit shouldn't blank out an existing target.
+ * If every unit in a file has an empty target, the file is
+ * recorded as skipped rather than landing an empty draft.
+ *
+ * Errors per file are isolated: a malformed `original` or a
+ * missing source sibling adds a `skipped` entry but the rest of
+ * the bundle still applies. Throwing is reserved for global
+ * problems (i18n not configured, malformed XML).
+ */
+declare function importXliff(options: XliffImportOptions): Promise<XliffImportResult>;
+declare class XliffImportError extends Error {
+    readonly name = "XliffImportError";
+}
+
+/**
+ * XLIFF 1.2 reader/writer scoped to the subset we round-trip.
+ *
+ * Shape contract:
+ *   - One `<xliff version="1.2">` root with the standard namespace.
+ *   - One or more `<file>` elements, each with `source-language`,
+ *     `target-language`, `datatype="plaintext"`, and an `original`
+ *     attribute that encodes the routing back to a NexPress doc:
+ *       original = "{collectionSlug}/{translationGroupId}"
+ *   - Each `<file>` contains a single `<body>` with a flat list of
+ *     `<trans-unit>` elements:
+ *       <trans-unit id="{fieldName}">
+ *         <source>...</source>
+ *         <target>...</target>   // optional / empty pre-translation
+ *       </trans-unit>
+ *
+ * We deliberately ignore segmentation (`<seg-source>`), inline
+ * markup (`<g>`, `<x>`, etc.), groups, alt-trans, and notes — XLIFF
+ * supports them but the round-trip we ship handles atomic-string
+ * fields only. Files that come back from a SaaS with extra inline
+ * markup will round-trip as if the markup were part of the target
+ * text; that's acceptable for v1 since we only export simple text.
+ */
+interface XliffTransUnit {
+    id: string;
+    source: string;
+    target: string;
+}
+interface XliffFile {
+    /** `original` attribute — `{collectionSlug}/{translationGroupId}` */
+    original: string;
+    sourceLocale: string;
+    targetLocale: string;
+    units: XliffTransUnit[];
+}
+interface XliffDocument {
+    files: XliffFile[];
+}
+/**
+ * Render an XLIFF 1.2 XML document. Output is deterministic
+ * (stable element + attribute order, two-space indentation, LF
+ * line endings) so a round-tripped file compares clean against
+ * the original except for the translator's `<target>` edits.
+ */
+declare function renderXliff(doc: XliffDocument): string;
+/**
+ * Parse an XLIFF 1.2 XML body into the document shape. Throws on
+ * malformed XML or missing required attributes (`source-language`,
+ * `target-language`, `original`); per-unit `target` may be empty
+ * but the element itself must exist (XLIFF spec allows `<target>`
+ * to be omitted but our round-trip emits it always).
+ */
+declare function parseXliff(xml: string): XliffDocument;
+declare class XliffParseError extends Error {
+    readonly name = "XliffParseError";
+}
+
+/**
+ * IO seam — tests inject capture hooks; the apps/web shim wires
+ * `process.stdout` / `process.stderr` directly.
+ */
+interface CliIo {
+    out(message: string): void;
+    err(message: string): void;
+}
+interface CliRunResult {
+    /** 0 = success, non-zero = failure (mirrors process exit codes). */
+    exitCode: number;
+}
+/**
+ * Parse the raw argv and execute. Returns an exit code rather
+ * than calling `process.exit` directly so the apps/web shim can
+ * decide how to surface errors (and tests can drive it without
+ * killing the runner).
+ */
+declare function runCli(io: CliIo, args: string[], options: {
+    user: NpAuthUser;
+}): Promise<CliRunResult>;
+
+export { type CliIo, type CliRunResult, type XliffDocument, type XliffExportBundle, XliffExportError, type XliffExportFile, type XliffExportOptions, type XliffFile, type XliffImportApplied, XliffImportError, type XliffImportOptions, type XliffImportResult, type XliffImportSkip, XliffParseError, type XliffTransUnit, exportXliff, importXliff, parseXliff, renderXliff, runCli };

package/dist/index.js

@@ -0,0 +1,565 @@
+// src/export.ts
+import {
+  findDocuments,
+  getAllCollectionSlugs,
+  getCollectionConfig,
+  getI18nConfig
+} from "@nexpress/core";
+
+// src/format.ts
+import { XMLParser } from "fast-xml-parser";
+function renderXliff(doc) {
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">'
+  ];
+  for (const file of doc.files) {
+    lines.push(
+      `  <file source-language="${escapeAttr(file.sourceLocale)}" target-language="${escapeAttr(file.targetLocale)}" datatype="plaintext" original="${escapeAttr(file.original)}">`
+    );
+    lines.push("    <body>");
+    for (const unit of file.units) {
+      lines.push(`      <trans-unit id="${escapeAttr(unit.id)}">`);
+      lines.push(`        <source>${escapeText(unit.source)}</source>`);
+      lines.push(`        <target>${escapeText(unit.target)}</target>`);
+      lines.push("      </trans-unit>");
+    }
+    lines.push("    </body>");
+    lines.push("  </file>");
+  }
+  lines.push("</xliff>");
+  return lines.join("\n");
+}
+var PARSER = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  // Preserve whitespace inside <source> / <target> — translators
+  // may want leading/trailing space for things like " — " or
+  // newlines between paragraphs.
+  trimValues: false,
+  // Keep elements parsed as objects even when there's only one
+  // child, so `file.body.trans-unit` is always an array we can
+  // iterate without runtime branching.
+  isArray: (name, jpath) => {
+    return jpath === "xliff.file" || jpath === "xliff.file.body.trans-unit";
+  }
+});
+function parseXliff(xml) {
+  let parsed;
+  try {
+    parsed = PARSER.parse(xml);
+  } catch (error) {
+    throw new XliffParseError(
+      `Malformed XLIFF XML: ${error.message}`
+    );
+  }
+  const root = parsed.xliff;
+  if (!root) {
+    throw new XliffParseError("Missing root <xliff> element");
+  }
+  const files = root.file ?? [];
+  const out = [];
+  for (const f of files) {
+    const sourceLocale = f["@_source-language"];
+    const targetLocale = f["@_target-language"];
+    const original = f["@_original"];
+    if (!sourceLocale || !targetLocale || !original) {
+      throw new XliffParseError(
+        "Each <file> must declare source-language, target-language, and original"
+      );
+    }
+    const units = [];
+    for (const u of f.body?.["trans-unit"] ?? []) {
+      const id = u["@_id"];
+      if (!id) {
+        throw new XliffParseError(
+          `<trans-unit> in file "${original}" is missing the id attribute`
+        );
+      }
+      units.push({
+        id,
+        source: extractText(u.source),
+        target: extractText(u.target)
+      });
+    }
+    out.push({ original, sourceLocale, targetLocale, units });
+  }
+  return { files: out };
+}
+var XliffParseError = class extends Error {
+  name = "XliffParseError";
+};
+function extractText(node) {
+  if (node === void 0 || node === null) return "";
+  if (typeof node === "string") return node;
+  if (typeof node === "object" && typeof node["#text"] === "string") {
+    return node["#text"];
+  }
+  return "";
+}
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeText(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// src/export.ts
+var TRANSLATABLE_TYPES = /* @__PURE__ */ new Set(["text", "textarea", "email"]);
+async function exportXliff(options = {}) {
+  const i18n = getI18nConfig();
+  if (!i18n) {
+    throw new XliffExportError(
+      "i18n is not configured \u2014 call setI18nConfig() before exporting XLIFF"
+    );
+  }
+  const sourceLocale = options.sourceLocale ?? i18n.defaultLocale;
+  if (!i18n.locales.includes(sourceLocale)) {
+    throw new XliffExportError(
+      `sourceLocale "${sourceLocale}" is not in the configured locale list`
+    );
+  }
+  const targetLocales = (options.targetLocales ?? i18n.locales.filter((l) => l !== sourceLocale)).filter((l) => l !== sourceLocale);
+  for (const t of targetLocales) {
+    if (!i18n.locales.includes(t)) {
+      throw new XliffExportError(
+        `targetLocale "${t}" is not in the configured locale list`
+      );
+    }
+  }
+  const slugs = options.collections ?? getAllCollectionSlugs();
+  const files = [];
+  let totalDocCount = 0;
+  let totalFieldCount = 0;
+  for (const slug of slugs) {
+    let config;
+    try {
+      config = getCollectionConfig(slug);
+    } catch {
+      continue;
+    }
+    if (!config.i18n) continue;
+    const translatableFields = config.fields.filter((f) => "name" in f && TRANSLATABLE_TYPES.has(f.type)).map((f) => f.name);
+    if (translatableFields.length === 0) continue;
+    const sourceResult = await findDocuments(
+      slug,
+      {
+        limit: 5e3,
+        page: 1,
+        where: { status: "published" },
+        locale: sourceLocale
+      },
+      options.user
+    );
+    const sourceDocs = sourceResult.docs;
+    if (sourceDocs.length === 0) continue;
+    totalDocCount += sourceDocs.length;
+    for (const targetLocale of targetLocales) {
+      const targetResult = await findDocuments(
+        slug,
+        {
+          limit: 5e3,
+          page: 1,
+          locale: targetLocale
+        },
+        options.user
+      );
+      const targetByGroupId = /* @__PURE__ */ new Map();
+      for (const doc of targetResult.docs) {
+        const groupId = doc.translationGroupId;
+        if (groupId) targetByGroupId.set(groupId, doc);
+      }
+      const fileUnits = [];
+      const filesByGroup = [];
+      for (const sourceDoc of sourceDocs) {
+        const groupId = sourceDoc.translationGroupId;
+        if (!groupId) continue;
+        const targetDoc = targetByGroupId.get(groupId) ?? null;
+        const docUnits = [];
+        for (const fieldName of translatableFields) {
+          const sourceValue = stringField(sourceDoc, fieldName);
+          if (sourceValue === "") continue;
+          const targetValue = targetDoc ? stringField(targetDoc, fieldName) : "";
+          docUnits.push({
+            id: fieldName,
+            source: sourceValue,
+            target: targetValue
+          });
+        }
+        if (docUnits.length === 0) continue;
+        filesByGroup.push({
+          original: `${slug}/${groupId}`,
+          sourceLocale,
+          targetLocale,
+          units: docUnits
+        });
+        fileUnits.push(...docUnits);
+      }
+      if (filesByGroup.length === 0) continue;
+      const xml = renderXliff({ files: filesByGroup });
+      files.push({
+        name: `${slug}-${sourceLocale}-${targetLocale}.xliff`,
+        collection: slug,
+        sourceLocale,
+        targetLocale,
+        unitCount: fileUnits.length,
+        xml
+      });
+      totalFieldCount += fileUnits.length;
+    }
+  }
+  return {
+    files,
+    summary: {
+      docCount: totalDocCount,
+      fieldCount: totalFieldCount,
+      sourceLocale,
+      targetLocales
+    }
+  };
+}
+var XliffExportError = class extends Error {
+  name = "XliffExportError";
+};
+function stringField(doc, fieldName) {
+  const v = doc[fieldName];
+  return typeof v === "string" ? v : "";
+}
+
+// src/import.ts
+import {
+  findDocuments as findDocuments2,
+  getCollectionConfig as getCollectionConfig2,
+  getDocumentById,
+  getI18nConfig as getI18nConfig2,
+  saveDocument
+} from "@nexpress/core";
+var TRANSLATABLE_TYPES2 = /* @__PURE__ */ new Set(["text", "textarea", "email"]);
+async function importXliff(options) {
+  const i18n = getI18nConfig2();
+  if (!i18n) {
+    throw new XliffImportError(
+      "i18n is not configured \u2014 call setI18nConfig() before importing XLIFF"
+    );
+  }
+  const doc = parseXliff(options.xml);
+  const applied = [];
+  const skipped = [];
+  for (const file of doc.files) {
+    const parsed = parseOriginal(file.original);
+    if (!parsed) {
+      skipped.push({
+        reason: `Malformed file original "${file.original}" (expected "{collection}/{groupId}")`
+      });
+      continue;
+    }
+    const { collection, groupId } = parsed;
+    if (!i18n.locales.includes(file.targetLocale)) {
+      skipped.push({
+        reason: `Target locale "${file.targetLocale}" is not configured`,
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+      continue;
+    }
+    let config;
+    try {
+      config = getCollectionConfig2(collection);
+    } catch {
+      skipped.push({
+        reason: `Unknown collection "${collection}"`,
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+      continue;
+    }
+    if (!config.i18n) {
+      skipped.push({
+        reason: `Collection "${collection}" is not i18n-enabled`,
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+      continue;
+    }
+    const translatableNames = new Set(
+      config.fields.filter((f) => "name" in f && TRANSLATABLE_TYPES2.has(f.type)).map((f) => f.name)
+    );
+    const sourceSibling = await findSibling(
+      collection,
+      groupId,
+      file.sourceLocale,
+      options.user
+    );
+    if (!sourceSibling) {
+      skipped.push({
+        reason: `No source row for groupId=${groupId} locale=${file.sourceLocale}`,
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+      continue;
+    }
+    const targetSibling = await findSibling(
+      collection,
+      groupId,
+      file.targetLocale,
+      options.user
+    );
+    const overrides = {};
+    const rejectedFieldIds = [];
+    for (const unit of file.units) {
+      if (unit.target.length === 0) continue;
+      if (!translatableNames.has(unit.id)) {
+        rejectedFieldIds.push(unit.id);
+        continue;
+      }
+      overrides[unit.id] = unit.target;
+    }
+    if (rejectedFieldIds.length > 0) {
+      skipped.push({
+        reason: `Ignored ${rejectedFieldIds.length} unit${rejectedFieldIds.length === 1 ? "" : "s"} with non-translatable id: ${rejectedFieldIds.join(", ")}`,
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+    }
+    if (Object.keys(overrides).length === 0) {
+      skipped.push({
+        reason: "All <target> elements in this file were empty",
+        collection,
+        groupId,
+        locale: file.targetLocale
+      });
+      continue;
+    }
+    if (options.dryRun) {
+      applied.push({
+        collection,
+        docId: targetSibling ? targetSibling.id : "(would-create)",
+        locale: file.targetLocale,
+        operation: targetSibling ? "update" : "create",
+        unitCount: Object.keys(overrides).length
+      });
+      continue;
+    }
+    if (targetSibling) {
+      const merged = { ...targetSibling, ...overrides };
+      const cleaned = stripFrameworkFields(merged);
+      const result = await saveDocument(
+        collection,
+        targetSibling.id,
+        cleaned,
+        options.user
+      );
+      applied.push({
+        collection,
+        docId: result.doc.id,
+        locale: file.targetLocale,
+        operation: "update",
+        unitCount: Object.keys(overrides).length
+      });
+    } else {
+      const baseline = stripFrameworkFields({ ...sourceSibling });
+      baseline.locale = file.targetLocale;
+      baseline.translationGroupId = groupId;
+      const created = await saveDocument(
+        collection,
+        null,
+        baseline,
+        options.user,
+        { status: "draft" }
+      );
+      const newId = created.doc.id;
+      const result = await saveDocument(
+        collection,
+        newId,
+        { ...baseline, ...overrides },
+        options.user
+      );
+      applied.push({
+        collection,
+        docId: result.doc.id,
+        locale: file.targetLocale,
+        operation: "create",
+        unitCount: Object.keys(overrides).length
+      });
+    }
+  }
+  return {
+    applied,
+    skipped,
+    wrote: !options.dryRun && applied.length > 0
+  };
+}
+var XliffImportError = class extends Error {
+  name = "XliffImportError";
+};
+function parseOriginal(original) {
+  const idx = original.lastIndexOf("/");
+  if (idx <= 0 || idx === original.length - 1) return null;
+  const collection = original.slice(0, idx);
+  const groupId = original.slice(idx + 1);
+  if (!/^[a-z0-9_-]+$/.test(collection)) return null;
+  if (!isUuid(groupId)) return null;
+  return { collection, groupId };
+}
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+    value
+  );
+}
+async function findSibling(collection, groupId, locale, user) {
+  const result = await findDocuments2(
+    collection,
+    {
+      limit: 1,
+      page: 1,
+      where: { translationGroupId: groupId },
+      locale
+    },
+    user
+  );
+  const row = result.docs[0];
+  if (!row) return null;
+  const id = row.id;
+  if (!id) return null;
+  const full = await getDocumentById(collection, id, user);
+  return full ?? null;
+}
+var FRAMEWORK_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "status",
+  "_status",
+  "createdAt",
+  "updatedAt",
+  "createdBy",
+  "updatedBy",
+  "searchVector"
+]);
+function stripFrameworkFields(doc) {
+  const out = {};
+  for (const [key, value] of Object.entries(doc)) {
+    if (FRAMEWORK_FIELDS.has(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+// src/cli.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var USAGE = `Usage:
+  xliff export <out-dir>           Write one .xliff file per (collection, locale-pair).
+  xliff import <file> [--dry-run]  Apply a translator's XLIFF bundle.
+
+Options:
+  --dry-run                        Validate + report without writing.
+
+Notes:
+  - Source-locale rows must be \`status="published"\` to ship to translators.
+  - Imported targets land as \`status="draft"\` so a reviewer can publish.
+  - Run with apps/web's \`pnpm xliff\` shim so core services are wired.
+`;
+async function runCli(io, args, options) {
+  const [command, ...rest] = args;
+  if (!command || command === "--help" || command === "-h") {
+    io.out(USAGE);
+    return { exitCode: command ? 0 : 1 };
+  }
+  if (command === "export") {
+    return runExport(io, rest, options.user);
+  }
+  if (command === "import") {
+    return runImport(io, rest, options.user);
+  }
+  io.err(`Unknown command: ${command}
+
+${USAGE}`);
+  return { exitCode: 2 };
+}
+async function runExport(io, args, user) {
+  const outDir = args[0];
+  if (!outDir) {
+    io.err("xliff export: <out-dir> argument is required\n");
+    return { exitCode: 2 };
+  }
+  const bundle = await exportXliff({ user });
+  if (bundle.files.length === 0) {
+    io.out(
+      "xliff export: no i18n collections with translatable content \u2014 nothing written.\n"
+    );
+    return { exitCode: 0 };
+  }
+  for (const file of bundle.files) {
+    const path = join(outDir, file.name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, file.xml, "utf8");
+    io.out(`  wrote ${path} (${file.unitCount} unit${file.unitCount === 1 ? "" : "s"})
+`);
+  }
+  io.out(
+    `
+Exported ${bundle.files.length} file${bundle.files.length === 1 ? "" : "s"} (${bundle.summary.docCount} doc${bundle.summary.docCount === 1 ? "" : "s"}, ${bundle.summary.fieldCount} unit${bundle.summary.fieldCount === 1 ? "" : "s"}, targets: ${bundle.summary.targetLocales.join(", ")}).
+`
+  );
+  return { exitCode: 0 };
+}
+async function runImport(io, args, user) {
+  const positional = [];
+  let dryRun = false;
+  for (const arg of args) {
+    if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg.startsWith("--")) {
+      io.err(`xliff import: unknown flag ${arg}
+`);
+      return { exitCode: 2 };
+    } else {
+      positional.push(arg);
+    }
+  }
+  const filePath = positional[0];
+  if (!filePath) {
+    io.err("xliff import: <file> argument is required\n");
+    return { exitCode: 2 };
+  }
+  let xml;
+  try {
+    xml = readFileSync(filePath, "utf8");
+  } catch (error) {
+    io.err(`xliff import: cannot read ${filePath} \u2014 ${error.message}
+`);
+    return { exitCode: 1 };
+  }
+  const result = await importXliff({ xml, user, dryRun });
+  for (const a of result.applied) {
+    const verb = dryRun ? `would ${a.operation}` : a.operation;
+    io.out(
+      `  ${verb}  ${a.collection}/${a.docId}  locale=${a.locale}  units=${a.unitCount}
+`
+    );
+  }
+  for (const s of result.skipped) {
+    io.out(`  skip   ${s.reason}
+`);
+  }
+  io.out(
+    `
+${dryRun ? "(dry-run) " : ""}Applied ${result.applied.length}, skipped ${result.skipped.length}${result.wrote ? "" : " (no writes)"}.
+`
+  );
+  return { exitCode: 0 };
+}
+export {
+  XliffExportError,
+  XliffImportError,
+  XliffParseError,
+  exportXliff,
+  importXliff,
+  parseXliff,
+  renderXliff,
+  runCli
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nexpress/xliff",
+  "version": "0.1.0",
+  "description": "XLIFF translation export/import for NexPress i18n.",
+  "license": "MIT",
+  "author": "Nexpress",
+  "homepage": "https://github.com/nexpress-cms/nexpress#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nexpress-cms/nexpress.git",
+    "directory": "packages/xliff"
+  },
+  "bugs": {
+    "url": "https://github.com/nexpress-cms/nexpress/issues"
+  },
+  "keywords": [
+    "nexpress",
+    "i18n",
+    "xliff",
+    "translation"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.5.8",
+    "@nexpress/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch --no-clean",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --cache --cache-location node_modules/.cache/eslint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}