@orthacms/i18n-server 0.4.3 → 0.5.1

package/dist/lib/content/services/entry-locale-extension.service.d.ts

@@ -1,5 +1,5 @@
 import { type SQL } from 'drizzle-orm';
-import { type Database } from '@orthacms/database';
+import { UnitOfWork, type Database } from '@orthacms/database';
 import { EntryValidationService, RelationLinkService, type AnyContentType, type ContentEntryExtension, type EntryFilterExtension, type EntryScopeParams, type EntryTransaction, type EntryWriteContext, type EntryWriteFanout } from '@orthacms/content-server';
 import { LocaleRegistryService } from '../../locales/services/locale-registry.service';
 /**
@@ -30,7 +30,8 @@ export declare class EntryLocaleExtensionService implements ContentEntryExtensio
     private readonly locales;
     private readonly validation;
     private readonly relations;
-    constructor(db: Database, locales: LocaleRegistryService, validation: EntryValidationService, relations: RelationLinkService);
+    private readonly uow;
+    constructor(db: Database, locales: LocaleRegistryService, validation: EntryValidationService, relations: RelationLinkService, uow: UnitOfWork);
     /** @inheritdoc */
     listScope(type: AnyContentType, workspaceId: string, params: EntryScopeParams): SQL | undefined;
     /**
@@ -45,9 +46,11 @@ export declare class EntryLocaleExtensionService implements ContentEntryExtensio
     createColumns(type: AnyContentType, workspaceId: string, params: EntryScopeParams): Promise<Record<string, unknown>>;
     /**
      * Assert a translation group has ≥1 live row in this workspace, so a
-     * sibling attaches to a real group. Runs before the create transaction —
-     * the (benign) TOCTOU window is covered by the row staying valid and the
-     * `(locale_group_id, locale)` unique index still guarding duplicates.
+     * sibling attaches to a real group. Runs before the create's own
+     * transaction — the (benign) TOCTOU window is covered by the row staying
+     * valid and the `(locale_group_id, locale)` unique index still guarding
+     * duplicates — but *inside* any enclosing unit of work, which is why it
+     * reads through {@link UnitOfWork.current} rather than the base pool.
      */
     private assertGroupExists;
     /**

package/dist/lib/content/services/entry-locale-extension.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry-locale-extension.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/content/services/entry-locale-extension.service.ts"],"names":[],"mappings":"AAMA,OAAO,EAYH,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACH,sBAAsB,EACtB,mBAAmB,EAMnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACxB,MAAM,0BAA0B,CAAC;AASlC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAuCvF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,2BAA4B,YAAW,qBAAqB;IAE/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAK3B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAPS,EAAE,EAAE,QAAQ,EAC9B,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,sBAAsB,EAKlC,SAAS,EAAE,mBAAmB;IAGnD,kBAAkB;IAClB,SAAS,CACL,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,gBAAgB,GACzB,GAAG,GAAG,SAAS;IAmClB;;;;;;;;OAQG;IACG,aAAa,CACf,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAgBnC;;;;;OAKG;YACW,iBAAiB;IAwB/B;;;;;;;;;;;;OAYG;IACG,WAAW,CACb,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC;IAKhB,kBAAkB;IACZ,WAAW,CACb,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,cAAc,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAmBrC,kBAAkB;IACZ,cAAc,CAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAkDxC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAiMjC;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,yBAAyB;IAmEvC;;;;;;;;;OASG;YACW,uBAAuB;IA0CrC;;;;;;;;;;OAUG;YACW,gBAAgB;IA6C9B,kBAAkB;IAClB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,GAAG,SAAS;IAcvE;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,iBAAiB;IAmE/B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;CAoBxB"}
+{"version":3,"file":"entry-locale-extension.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/content/services/entry-locale-extension.service.ts"],"names":[],"mappings":"AAMA,OAAO,EAYH,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAkB,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EACH,sBAAsB,EACtB,mBAAmB,EAMnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAE1B,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACxB,MAAM,0BAA0B,CAAC;AASlC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAuCvF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,2BAA4B,YAAW,qBAAqB;IAE/C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAK3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBARe,EAAE,EAAE,QAAQ,EAC9B,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,sBAAsB,EAKlC,SAAS,EAAE,mBAAmB,EAC9B,GAAG,EAAE,UAAU;IAGpC,kBAAkB;IAClB,SAAS,CACL,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,gBAAgB,GACzB,GAAG,GAAG,SAAS;IAmClB;;;;;;;;OAQG;IACG,aAAa,CACf,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAgBnC;;;;;;;OAOG;YACW,iBAAiB;IAmC/B;;;;;;;;;;;;OAYG;IACG,WAAW,CACb,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC;IAKhB,kBAAkB;IACZ,WAAW,CACb,EAAE,EAAE,gBAAgB,EACpB,IAAI,EAAE,cAAc,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAmBrC,kBAAkB;IACZ,cAAc,CAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAkDxC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAiMjC;;;;;;;;;;;;;;;;;;;;;OAqBG;YACW,yBAAyB;IAmEvC;;;;;;;;;OASG;YACW,uBAAuB;IA0CrC;;;;;;;;;;OAUG;YACW,gBAAgB;IA6C9B,kBAAkB;IAClB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,GAAG,SAAS;IAcvE;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,iBAAiB;IAmE/B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;CAoBxB"}

package/dist/lib/content/services/entry-locale-extension.service.js

@@ -70,16 +70,18 @@ let EntryLocaleExtensionService = class EntryLocaleExtensionService {
     locales;
     validation;
     relations;
+    uow;
     constructor(db, locales, validation, 
     // Relation storage is content's, not ours: reading a link set and
     // replacing one are the same operations the entries pipeline performs,
     // and a second implementation here is how the join table's ordering
     // and de-duplication rules would drift.
-    relations) {
+    relations, uow) {
         this.db = db;
         this.locales = locales;
         this.validation = validation;
         this.relations = relations;
+        this.uow = uow;
     }
     /** @inheritdoc */
     listScope(type, workspaceId, params) {
@@ -127,13 +129,26 @@ let EntryLocaleExtensionService = class EntryLocaleExtensionService {
     }
     /**
      * Assert a translation group has ≥1 live row in this workspace, so a
-     * sibling attaches to a real group. Runs before the create transaction —
-     * the (benign) TOCTOU window is covered by the row staying valid and the
-     * `(locale_group_id, locale)` unique index still guarding duplicates.
+     * sibling attaches to a real group. Runs before the create's own
+     * transaction — the (benign) TOCTOU window is covered by the row staying
+     * valid and the `(locale_group_id, locale)` unique index still guarding
+     * duplicates — but *inside* any enclosing unit of work, which is why it
+     * reads through {@link UnitOfWork.current} rather than the base pool.
      */
     async assertGroupExists(type, localeGroupId, workspaceId) {
         const table = type.table;
-        const [row] = await this.db
+        // `uow.current()`, not `this.db` — the same distinction
+        // `EntryWriterService` draws for its relation-target probe. Outside a
+        // unit of work the two are one connection and an ordinary save is
+        // unaffected. Inside one they are not, and the difference decides
+        // whether a *group* can be built in a single transaction: a content
+        // import writes the `en` row and then its `de` sibling in one unit of
+        // work, and a probe on the base pool cannot see the uncommitted `en`
+        // row — so the sibling was refused with "no translation group" for a
+        // group created moments earlier in the same transaction, and an
+        // imported locale pair arrived as one row plus an error.
+        const [row] = await this.uow
+            .current()
             .select({ one: (0, drizzle_orm_1.sql) `1` })
             .from(type.table)
             .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(table['localeGroupId'], localeGroupId), (0, drizzle_orm_1.eq)(table['workspaceId'], workspaceId), ...(type.paranoid ? [(0, drizzle_orm_1.isNull)(table['deletedAt'])] : [])))
@@ -658,5 +673,6 @@ exports.EntryLocaleExtensionService = EntryLocaleExtensionService = tslib_1.__de
     tslib_1.__param(0, (0, database_1.InjectDatabase)()),
     tslib_1.__metadata("design:paramtypes", [Object, locale_registry_service_1.LocaleRegistryService,
         content_server_1.EntryValidationService,
-        content_server_1.RelationLinkService])
+        content_server_1.RelationLinkService,
+        database_1.UnitOfWork])
 ], EntryLocaleExtensionService);

package/dist/lib/copilot/translation-proposal.applier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translation-proposal.applier.d.ts","sourceRoot":"","sources":["../../../src/lib/copilot/translation-proposal.applier.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACH,kBAAkB,EAElB,oBAAoB,EAIpB,KAAK,mBAAmB,EAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACR,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,cAAc,EACjB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,0BAA2B,YAAW,eAAe;IAK1D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPzC,QAAQ,CAAC,IAAI,yBAAyC;gBAIjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EACV,EAAE,EAAE,QAAQ;IAG7C,KAAK,CACP,KAAK,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACjE,KAAK,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,CAAC;CAkDlC;AA0DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,8BAA+B,YAAW,eAAe;IAK9D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPzC,QAAQ,CAAC,IAAI,8BAAuC;gBAI/B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EACV,EAAE,EAAE,QAAQ;IAG7C,KAAK,CACP,KAAK,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACjE,KAAK,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,CAAC;CA8FlC"}
+{"version":3,"file":"translation-proposal.applier.d.ts","sourceRoot":"","sources":["../../../src/lib/copilot/translation-proposal.applier.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACH,kBAAkB,EAElB,oBAAoB,EAIpB,KAAK,mBAAmB,EAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACR,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,cAAc,EACjB,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,0BAA2B,YAAW,eAAe;IAK1D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPzC,QAAQ,CAAC,IAAI,yBAAyC;gBAIjC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EACV,EAAE,EAAE,QAAQ;IAG7C,KAAK,CACP,KAAK,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACjE,KAAK,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,CAAC;CAkDlC;AA0DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,8BAA+B,YAAW,eAAe;IAK9D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPzC,QAAQ,CAAC,IAAI,8BAAuC;gBAI/B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,oBAAoB,EACV,EAAE,EAAE,QAAQ;IAG7C,KAAK,CACP,KAAK,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACjE,KAAK,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,CAAC;CA8FlC"}

package/dist/lib/copilot/translation-proposal.applier.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BulkTranslationProposalApplier = exports.TranslationProposalApplier = void 0;
 const tslib_1 = require("tslib");
+const copilot_server_1 = require("@orthacms/copilot-server");
 const common_1 = require("@nestjs/common");
 const drizzle_orm_1 = require("drizzle-orm");
 const database_1 = require("@orthacms/database");
@@ -80,7 +81,7 @@ let TranslationProposalApplier = class TranslationProposalApplier {
         }
         const translated = (input.patch['values'] ?? {});
         const inherited = await sharedValues(this.db, type, sourceId, actor.workspaceId);
-        const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, { id: actor.userId, email: actor.actorEmail });
+        const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, (0, copilot_server_1.proposalEventActor)(actor));
         return {
             entityId: entry.id,
             detail: { typeName: type.name, locale, localeGroupId }
@@ -207,7 +208,7 @@ let BulkTranslationProposalApplier = class BulkTranslationProposalApplier {
                 // a stale copy of itself.
                 const inherited = await sharedValues(this.db, type, sourceId, actor.workspaceId);
                 const translated = (item.values ?? {});
-                const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, { id: actor.userId, email: actor.actorEmail });
+                const entry = await this.writer.create(type, { ...inherited, ...translated }, actor.workspaceId, undefined, locale, localeGroupId, (0, copilot_server_1.proposalEventActor)(actor));
                 created.push(entry.id);
                 locales.push(locale);
             }

package/dist/lib/docs/describe-i18n-api.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The i18n plugin's pass over the host's OpenAPI document.
+ *
+ * Three read routes, all of them answering a hand-written `interface` that
+ * `@nestjs/swagger` cannot see (`packages/bootstrap/server/AGENTS.md` → "The
+ * response-schema gap"). This is the mechanism content-server already uses:
+ * plain schema objects written onto the finished document, no decorator and no
+ * runtime-referenceable class.
+ *
+ * Pure: it takes the document and the configured locale slugs, and touches only
+ * the paths this plugin owns.
+ */
+import type { OpenApiDocument } from '@orthacms/bootstrap-server';
+/**
+ * Adds this plugin's schemas to `document` and attaches them to its own three
+ * operations.
+ */
+export declare function describeI18nApi(document: OpenApiDocument, localeSlugs: readonly string[]): void;
+//# sourceMappingURL=describe-i18n-api.d.ts.map

package/dist/lib/docs/describe-i18n-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-i18n-api.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/describe-i18n-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA2HlE;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC/B,IAAI,CAgBN"}

package/dist/lib/docs/describe-i18n-api.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * The i18n plugin's pass over the host's OpenAPI document.
+ *
+ * Three read routes, all of them answering a hand-written `interface` that
+ * `@nestjs/swagger` cannot see (`packages/bootstrap/server/AGENTS.md` → "The
+ * response-schema gap"). This is the mechanism content-server already uses:
+ * plain schema objects written onto the finished document, no decorator and no
+ * runtime-referenceable class.
+ *
+ * Pure: it takes the document and the configured locale slugs, and touches only
+ * the paths this plugin owns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeI18nApi = describeI18nApi;
+const i18n_schemas_1 = require("./i18n-schemas");
+/**
+ * The locales route, matched on its own full suffix.
+ *
+ * `/i18n/locales` and not a looser `/i18n` prefix: the insights plugin serves
+ * `/api/insights/i18n/coverage`, which a pattern anchored on the bare segment
+ * would also match. It would fall out of the route table below and describe
+ * nothing — but only by luck, and the next route either plugin adds is where
+ * luck runs out.
+ */
+const LOCALES_ROUTE_RE = /\/i18n\/locales$/;
+/** Matches `<prefix>/i18n/content/{typeName}<rest>`. */
+const CONTENT_ROUTE_RE = /\/i18n\/content\/\{typeName\}(.*)$/;
+/** Content-scoped routes, keyed by what follows `/i18n/content/{typeName}`. */
+const CONTENT_ROUTES = {
+    '/{id}/locales': {
+        get: {
+            schema: 'I18nEntryLocalesView',
+            description: 'The entry’s translation group, one slot per configured locale.'
+        }
+    },
+    '/locale-summary': {
+        post: {
+            schema: 'I18nLocaleSummaryView',
+            description: 'The requested groups and their live members. A read, so it answers 200 rather than a 201 claiming it created something.'
+        }
+    }
+};
+/** The locales route's one operation. */
+const LOCALES_OPERATION = {
+    schema: 'I18nLocalesView',
+    description: 'The configured locales, in display order.'
+};
+/**
+ * Writes a success schema onto whichever 2xx key the scanner already emitted,
+ * so this never invents a status code the API does not return. `POST
+ * /locale-summary` carries `@HttpCode(200)`, which is why the key is read
+ * rather than assumed.
+ */
+function setSuccessResponse(operation, schema, description) {
+    const responses = operation.responses ?? {};
+    const key = Object.keys(responses).find((code) => /^2\d\d$/.test(code));
+    if (!key || key === '204') {
+        return;
+    }
+    responses[key] = {
+        description,
+        content: { 'application/json': { schema } }
+    };
+    operation.responses = responses;
+}
+/** Adds a documented failure response, leaving any existing one alone. */
+function addErrorResponse(operation, code, description) {
+    const responses = operation.responses ?? {};
+    if (responses[code]) {
+        return;
+    }
+    responses[code] = { description };
+    operation.responses = responses;
+}
+/** Applies one route table entry to a path item. */
+function describeItem(item, byMethod, contentScoped) {
+    for (const [method, operation] of Object.entries(item)) {
+        const spec = byMethod[method];
+        if (!spec || !operation || typeof operation !== 'object') {
+            continue;
+        }
+        const typed = operation;
+        setSuccessResponse(typed, (0, i18n_schemas_1.ref)(spec.schema), spec.description);
+        if (contentScoped) {
+            // Both content routes resolve `:typeName` through the same
+            // `resolveI18nType`, which draws exactly this line: a name nobody
+            // registered is a missing resource, a registered type that is not
+            // localized is a caller bug.
+            addErrorResponse(typed, '400', 'The content type exists but is not localized (`i18n: false`), so it has no translation groups.');
+            addErrorResponse(typed, '404', 'Unknown content type — or, for the per-entry panel, no live entry with this id in the open workspace.');
+        }
+    }
+}
+/**
+ * Adds this plugin's schemas to `document` and attaches them to its own three
+ * operations.
+ */
+function describeI18nApi(document, localeSlugs) {
+    document.components ??= {};
+    document.components.schemas ??= {};
+    Object.assign(document.components.schemas, (0, i18n_schemas_1.buildI18nSchemas)(localeSlugs));
+    for (const [route, item] of Object.entries(document.paths)) {
+        if (LOCALES_ROUTE_RE.test(route)) {
+            describeItem(item, { get: LOCALES_OPERATION }, false);
+            continue;
+        }
+        const match = CONTENT_ROUTE_RE.exec(route);
+        const byMethod = match ? CONTENT_ROUTES[match[1]] : undefined;
+        if (byMethod) {
+            describeItem(item, byMethod, true);
+        }
+    }
+}

package/dist/lib/docs/i18n-schemas.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The response schemas of the i18n plugin's three read routes, as plain
+ * OpenAPI objects.
+ *
+ * They are built rather than reflected because the shapes they describe are
+ * TypeScript `interface`s (`LocalesView`, `EntryLocalesView`,
+ * `LocaleSummaryView`) — erased at compile time, invisible to
+ * `@nestjs/swagger`'s scanner, and impossible to decorate. See
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap".
+ *
+ * Pure: locale slugs in, schema objects out. No document, no Nest, no
+ * registry.
+ */
+/** A JSON Schema fragment, as it appears in the OpenAPI document. */
+export type OpenApiSchema = Record<string, unknown>;
+/** A `$ref` to one of the schemas registered by {@link buildI18nSchemas}. */
+export declare function ref(name: string): OpenApiSchema;
+/**
+ * The i18n plugin's response schemas, keyed by component name.
+ *
+ * `locale` / `slug` carry the **configured** slugs as an enum, which is a fact
+ * about every response rather than a guess: the locales route maps the
+ * registry, the per-entry panel iterates the configured set, and the batch
+ * summary drops any row whose slug the host no longer declares. A locale the
+ * config does not name cannot appear in any of the three.
+ */
+export declare function buildI18nSchemas(localeSlugs: readonly string[]): Record<string, OpenApiSchema>;
+//# sourceMappingURL=i18n-schemas.d.ts.map

package/dist/lib/docs/i18n-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/i18n-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,6EAA6E;AAC7E,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE/C;AAqED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAoG/B"}

package/dist/lib/docs/i18n-schemas.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * The response schemas of the i18n plugin's three read routes, as plain
+ * OpenAPI objects.
+ *
+ * They are built rather than reflected because the shapes they describe are
+ * TypeScript `interface`s (`LocalesView`, `EntryLocalesView`,
+ * `LocaleSummaryView`) — erased at compile time, invisible to
+ * `@nestjs/swagger`'s scanner, and impossible to decorate. See
+ * `packages/bootstrap/server/AGENTS.md` → "The response-schema gap".
+ *
+ * Pure: locale slugs in, schema objects out. No document, no Nest, no
+ * registry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ref = ref;
+exports.buildI18nSchemas = buildI18nSchemas;
+const content_server_1 = require("@orthacms/content-server");
+const i18n_constants_1 = require("../i18n.constants");
+/** A `$ref` to one of the schemas registered by {@link buildI18nSchemas}. */
+function ref(name) {
+    return { $ref: `#/components/schemas/${name}` };
+}
+/**
+ * The text direction of a locale. Always present on the wire even though it is
+ * optional in config: the registry resolves a declared or inferred value before
+ * anything is serialized, so no consumer has to decide for itself whether
+ * Arabic is right-to-left.
+ */
+const DIR_SCHEMA = {
+    type: 'string',
+    enum: [...i18n_constants_1.LOCALE_DIR],
+    description: 'Resolved text direction for content in this locale — the HTML `dir` value to set alongside `lang`.'
+};
+/**
+ * The publish state of one row. Present **only on a publishable content type**,
+ * which is why it appears in no `required` list: the services spread
+ * `status`/`publishedAt` in conditionally, so on a non-publishable type the keys
+ * are absent rather than null.
+ */
+const STATUS_SCHEMA = {
+    type: 'string',
+    enum: Object.values(content_server_1.ENTRY_STATUS),
+    description: 'Publish state. Present on publishable content types only — absent, not null, on the rest.'
+};
+/** When this row last went live, or `null` if it never has. */
+const PUBLISHED_AT_SCHEMA = {
+    type: 'string',
+    format: 'date-time',
+    nullable: true,
+    description: 'When this row last went live, or `null` if it never has. Publishable content types only. Paired with `status` it separates a never-published draft from one carrying unpublished edits over live content.'
+};
+/**
+ * The group's row in one locale — the `entry` member of a locale panel item.
+ *
+ * **Inlined rather than a `$ref`**, because this is the one nullable object in
+ * the plugin's responses and OpenAPI 3.0 has no way to spell a nullable
+ * reference: every sibling of `$ref` is ignored, so `{ $ref, nullable: true }`
+ * reads as if it works and silently drops the null, and `nullable` beside a
+ * bare `allOf`/`oneOf` is adjunct to `type` and equally inert. `type: 'object'`
+ * with `nullable: true` is the form that actually says what the route returns.
+ */
+const ENTRY_ROW_SCHEMA = {
+    type: 'object',
+    nullable: true,
+    description: 'The group’s row in this locale, or `null` when it has not been translated yet. Enough to route to the row and render its state — not its values.',
+    properties: {
+        id: {
+            type: 'string',
+            format: 'uuid',
+            description: 'The entry id of this locale’s row.'
+        },
+        status: STATUS_SCHEMA,
+        publishedAt: PUBLISHED_AT_SCHEMA,
+        updatedAt: {
+            type: 'string',
+            format: 'date-time',
+            description: 'When this row was last written.'
+        }
+    },
+    required: ['id', 'updatedAt']
+};
+/**
+ * The i18n plugin's response schemas, keyed by component name.
+ *
+ * `locale` / `slug` carry the **configured** slugs as an enum, which is a fact
+ * about every response rather than a guess: the locales route maps the
+ * registry, the per-entry panel iterates the configured set, and the batch
+ * summary drops any row whose slug the host no longer declares. A locale the
+ * config does not name cannot appear in any of the three.
+ */
+function buildI18nSchemas(localeSlugs) {
+    const slugSchema = {
+        type: 'string',
+        enum: [...localeSlugs],
+        description: 'A configured locale slug — a BCP-47 language tag, usable verbatim as an HTML `lang` value.'
+    };
+    return {
+        I18nLocale: {
+            type: 'object',
+            description: 'One configured locale.',
+            properties: {
+                slug: slugSchema,
+                name: {
+                    type: 'string',
+                    description: 'Human display name, e.g. "English".'
+                },
+                isDefault: {
+                    type: 'boolean',
+                    description: 'The locale applied when a request names none. Exactly one locale in the list sets it.'
+                },
+                dir: DIR_SCHEMA
+            },
+            required: ['slug', 'name', 'isDefault', 'dir']
+        },
+        I18nLocalesView: {
+            type: 'object',
+            description: 'The configured locales, in display order. Every field is resolved server-side, so a client needs no locale table of its own.',
+            properties: {
+                items: { type: 'array', items: ref('I18nLocale') }
+            },
+            required: ['items']
+        },
+        I18nEntryLocaleItem: {
+            type: 'object',
+            description: 'One configured locale’s slot in the translation group.',
+            properties: {
+                locale: slugSchema,
+                dir: DIR_SCHEMA,
+                isDefault: {
+                    type: 'boolean',
+                    description: 'Whether this is the configured default locale.'
+                },
+                entry: ENTRY_ROW_SCHEMA
+            },
+            required: ['locale', 'dir', 'isDefault', 'entry']
+        },
+        I18nEntryLocalesView: {
+            type: 'object',
+            description: 'The locale panel of one entry: every configured locale, in config order, with the group’s row in it or `null`.',
+            properties: {
+                localeGroupId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'The translation group this entry belongs to — the stable identity of the record across languages.'
+                },
+                items: { type: 'array', items: ref('I18nEntryLocaleItem') }
+            },
+            required: ['localeGroupId', 'items']
+        },
+        I18nLocaleSummaryItem: {
+            type: 'object',
+            description: 'One live member of a translation group.',
+            properties: {
+                locale: slugSchema,
+                entryId: {
+                    type: 'string',
+                    format: 'uuid',
+                    description: 'The member row’s entry id.'
+                },
+                status: STATUS_SCHEMA,
+                publishedAt: PUBLISHED_AT_SCHEMA
+            },
+            required: ['locale', 'entryId']
+        },
+        I18nLocaleSummaryView: {
+            type: 'object',
+            description: 'Per requested translation-group id, that group’s live members in config order.',
+            properties: {
+                groups: {
+                    type: 'object',
+                    description: 'Keyed by the group ids the request asked for — **exactly** those, no more and no fewer. A group in another workspace and one that names nothing at all both come back as an empty array, so a caller learns nothing it did not already supply.',
+                    additionalProperties: {
+                        type: 'array',
+                        items: ref('I18nLocaleSummaryItem')
+                    }
+                }
+            },
+            required: ['groups']
+        }
+    };
+}

package/dist/lib/insights/docs/describe-i18n-insights-api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The localization-coverage widget's pass over the host's OpenAPI document.
+ *
+ * One route, one shape — and the shape needs saying, because its unit is not
+ * the obvious one. Every figure here counts **translation groups**, not rows:
+ * a localized entry is one row per language sharing a `locale_group_id`, so
+ * counting rows would report a workspace of 40 stories in 3 languages as 120
+ * things and make every percentage meaningless.
+ *
+ * Pure: it takes the document and mutates only this plugin's own operation.
+ */
+import type { OpenApiDocument } from '@orthacms/bootstrap-server';
+/** Adds the coverage schema and describes the one operation that returns it. */
+export declare function describeI18nInsightsApi(document: OpenApiDocument): void;
+//# sourceMappingURL=describe-i18n-insights-api.d.ts.map

package/dist/lib/insights/docs/describe-i18n-insights-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-i18n-insights-api.d.ts","sourceRoot":"","sources":["../../../../src/lib/insights/docs/describe-i18n-insights-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA2HlE,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAkCvE"}

package/dist/lib/insights/docs/describe-i18n-insights-api.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * The localization-coverage widget's pass over the host's OpenAPI document.
+ *
+ * One route, one shape — and the shape needs saying, because its unit is not
+ * the obvious one. Every figure here counts **translation groups**, not rows:
+ * a localized entry is one row per language sharing a `locale_group_id`, so
+ * counting rows would report a workspace of 40 stories in 3 languages as 120
+ * things and make every percentage meaningless.
+ *
+ * Pure: it takes the document and mutates only this plugin's own operation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeI18nInsightsApi = describeI18nInsightsApi;
+/**
+ * The four per-type figures, reused for the workspace envelope.
+ *
+ * `notLocalized` is a **subset** of `requiresLocalization`, not a second slice
+ * of it — a record in one language of four both has no translations and needs
+ * some. They are separate because they are separate jobs: starting a
+ * translation, and finishing one. A client that adds them double-counts.
+ */
+function coverageCounts() {
+    return {
+        records: {
+            type: 'integer',
+            description: 'Translation groups of this type.'
+        },
+        localized: {
+            type: 'integer',
+            description: 'Of those, the ones present in **every** configured locale.'
+        },
+        notLocalized: {
+            type: 'integer',
+            description: 'Of those, the ones present in exactly one locale. Always 0 in a single-locale deployment, where a record would otherwise be both fully localized and not localized at all.'
+        },
+        requiresLocalization: {
+            type: 'integer',
+            description: 'Of those, the ones missing at least one locale (`records - localized`). Includes every `notLocalized` one.'
+        }
+    };
+}
+/** The coverage response. */
+const COVERAGE = {
+    type: 'object',
+    description: 'Localization coverage across every `i18n: true` content type. The unit is a translation group, never a row.',
+    required: [
+        'locales',
+        'records',
+        'localized',
+        'notLocalized',
+        'requiresLocalization',
+        'types'
+    ],
+    properties: {
+        locales: {
+            type: 'array',
+            description: 'One entry per configured locale, in config order.',
+            items: {
+                type: 'object',
+                required: [
+                    'locale',
+                    'name',
+                    'isDefault',
+                    'translated',
+                    'missing'
+                ],
+                properties: {
+                    locale: {
+                        type: 'string',
+                        description: 'The configured locale slug.',
+                        example: 'de'
+                    },
+                    name: {
+                        type: 'string',
+                        description: 'Its display name, from the host’s config.'
+                    },
+                    isDefault: { type: 'boolean' },
+                    translated: {
+                        type: 'integer',
+                        description: 'Records that have a row in this locale.'
+                    },
+                    missing: {
+                        type: 'integer',
+                        description: 'Records that do not.'
+                    }
+                }
+            }
+        },
+        ...coverageCounts(),
+        types: {
+            type: 'array',
+            description: 'Per-type coverage, most records first. A type the workspace has never used is omitted rather than listed at zero — a permanently empty row would push the types that hold work further down.',
+            items: {
+                type: 'object',
+                required: [
+                    'name',
+                    'label',
+                    'records',
+                    'localized',
+                    'notLocalized',
+                    'requiresLocalization'
+                ],
+                properties: {
+                    name: { type: 'string' },
+                    label: { type: 'string' },
+                    ...coverageCounts()
+                }
+            }
+        }
+    }
+};
+/**
+ * Matches `<prefix>/insights/i18n/coverage`.
+ *
+ * The prefix is matched as segments carrying no `{`, so a nested route ending
+ * in the same segments is not described with this shape.
+ */
+const ROUTE_RE = /^(?:\/[^/{}]+)*\/insights\/i18n\/coverage$/;
+/** Adds the coverage schema and describes the one operation that returns it. */
+function describeI18nInsightsApi(document) {
+    document.components ??= {};
+    document.components.schemas ??= {};
+    document.components.schemas['InsightsI18nCoverage'] = COVERAGE;
+    for (const [route, item] of Object.entries(document.paths)) {
+        if (!ROUTE_RE.test(route)) {
+            continue;
+        }
+        const operation = item['get'];
+        if (!operation || typeof operation !== 'object') {
+            continue;
+        }
+        // Onto whichever 2xx key the scanner emitted — never a new one.
+        const responses = operation.responses ?? {};
+        const key = Object.keys(responses).find((code) => /^2\d\d$/.test(code));
+        if (!key || key === '204') {
+            continue;
+        }
+        responses[key] = {
+            description: 'Coverage per locale and per localized content type, counted in translation groups.',
+            content: {
+                'application/json': {
+                    schema: {
+                        $ref: '#/components/schemas/InsightsI18nCoverage'
+                    }
+                }
+            }
+        };
+        operation.responses = responses;
+    }
+}

package/dist/lib/utils/i18n-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/i18n-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,0CAA0C;IAC1C,UAAU,EAAE,gBAAgB,CAAC;CAChC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,gBAAgB,GACzB,oBAAoB,CAOtB"}
+{"version":3,"file":"i18n-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/i18n-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,0CAA0C;IAC1C,UAAU,EAAE,gBAAgB,CAAC;CAChC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,gBAAgB,GACzB,oBAAoB,CAyBtB"}

package/dist/lib/utils/i18n-plugin.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.I18nServerPlugin = I18nServerPlugin;
 const locale_set_1 = require("../domain/value-objects/locale-set");
+const describe_i18n_api_1 = require("../docs/describe-i18n-api");
 const i18n_module_1 = require("../i18n.module");
+const describe_i18n_insights_api_1 = require("../insights/docs/describe-i18n-insights-api");
 /**
  * Validate the locale config **eagerly** (like `ContentPlugin`'s registry):
  * a misconfigured host fails at construction — before boot, before the first
@@ -48,6 +50,21 @@ function I18nServerPlugin(config) {
     return {
         name: 'i18n',
         module: i18n_module_1.I18nModule.forRoot(config),
-        i18nConfig: config
+        i18nConfig: config,
+        // The three read routes answer plain `interface`s, which the OpenAPI
+        // scanner cannot see and ADR-0003 would not let us decorate anyway.
+        // The configured slugs go in with them: which locales exist is runtime
+        // data held right here, and it is the one thing that makes the
+        // described `locale` fields exact rather than "some string".
+        docs: {
+            decorate: (document) => {
+                (0, describe_i18n_api_1.describeI18nApi)(document, config.locales.map((locale) => locale.slug));
+                // `/insights/i18n/coverage` is this plugin's route too, but it
+                // belongs to the Insights surface — a different tag, a
+                // different audience — so it is described from its own module
+                // rather than folded into the locale/content pass above.
+                (0, describe_i18n_insights_api_1.describeI18nInsightsApi)(document);
+            }
+        }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@orthacms/i18n-server",
-    "version": "0.4.3",
+    "version": "0.5.1",
     "description": "@orthacms/i18n-server — part of Ortha CMS.",
     "license": "MIT",
     "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/i18n/server",
@@ -27,15 +27,15 @@
     "dependencies": {
         "@nestjs/common": "^11.0.0",
         "@nestjs/swagger": "^11.4.6",
-        "@orthacms/bootstrap-server": "^0.4.3",
-        "@orthacms/content-server": "^0.4.3",
-        "@orthacms/copilot-domain": "^0.4.3",
-        "@orthacms/copilot-server": "^0.4.3",
-        "@orthacms/database": "^0.4.3",
-        "@orthacms/identity-server": "^0.4.3",
-        "@orthacms/tools-server": "^0.4.3",
-        "@orthacms/utils-server": "^0.4.3",
-        "@orthacms/workspaces-server": "^0.4.3",
+        "@orthacms/bootstrap-server": "^0.5.1",
+        "@orthacms/content-server": "^0.5.1",
+        "@orthacms/copilot-domain": "^0.5.1",
+        "@orthacms/copilot-server": "^0.5.1",
+        "@orthacms/database": "^0.5.1",
+        "@orthacms/identity-server": "^0.5.1",
+        "@orthacms/tools-server": "^0.5.1",
+        "@orthacms/utils-server": "^0.5.1",
+        "@orthacms/workspaces-server": "^0.5.1",
         "class-transformer": "^0.5.1",
         "class-validator": "^0.15.1",
         "drizzle-orm": "^0.45.0",