@jskit-ai/workspaces-core 0.1.226 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.2.0 - 2026-10-29
+
+- Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".
+- Workspace invitation emails are rendered in the recipient's saved locale (`createServerI18n`); `WorkspacesFeature` requires the `runtime.app-root` capability.
+
+### New message keys (34)
+
+All keys in `locales/en.json` (exported as `./locales/en.json`) are new in this version.
+
+<details><summary>Key list</summary>
+
+- `jskit.workspaces.auth.required`
+- `jskit.workspaces.user.invalidPayload`
+- `jskit.workspaces.workspace.slugUnavailable`
+- `jskit.workspaces.workspace.creationDisabled`
+- `jskit.workspaces.workspace.nameRequired`
+- `jskit.workspaces.workspace.contextDisabled`
+- `jskit.workspaces.workspace.slugRequired`
+- `jskit.workspaces.workspace.notFound`
+- `jskit.workspaces.workspace.accessDenied`
+- `jskit.workspaces.member.roleNotAssignable`
+- `jskit.workspaces.member.notFound`
+- `jskit.workspaces.member.ownerRoleLocked`
+- `jskit.workspaces.member.ownerNotRemovable`
+- `jskit.workspaces.invite.disabled`
+- `jskit.workspaces.invite.notFound`
+- `jskit.workspaces.invite.notFoundOrHandled`
+- `jskit.workspaces.invite.invitationNotFoundOrHandled`
+- `jskit.workspaces.invite.workspaceMissing`
+- `jskit.workspaces.invite.expired`
+- `jskit.workspaces.invite.tokenMismatch`
+- `jskit.workspaces.invite.tokenRequired`
+- `jskit.workspaces.invite.tokenInvalid`
+- `jskit.workspaces.invite.emailMismatchUser`
+- `jskit.workspaces.invite.emailMismatchAccount`
+- `jskit.workspaces.invite.notAvailable`
+- `jskit.workspaces.invite.mailerUnconfigured`
+- `jskit.workspaces.invite.sendFailed`
+- `jskit.workspaces.inviteEmail.subject`
+- `jskit.workspaces.inviteEmail.intro`
+- `jskit.workspaces.inviteEmail.introFromInviter`
+- `jskit.workspaces.inviteEmail.expiry`
+- `jskit.workspaces.inviteEmail.openLink`
+- `jskit.workspaces.inviteEmail.accept`
+- `jskit.workspaces.inviteEmail.workspaceFallback`
+
+</details>
+
+### Codes (27)
+
+Error, field-error and message codes this package sends, with their English. Undotted codes kept their existing values and render from `jskit.errors.<code>`.
+
+| Code | English |
+| --- | --- |
+| `workspaces.auth.required` | Authentication required. |
+| `workspaces.user.invalidPayload` | Invalid authenticated user payload. |
+| `workspaces.workspace.slugUnavailable` | Unable to generate unique workspace slug. |
+| `workspaces.workspace.creationDisabled` | Workspace creation is disabled for this tenancy mode. |
+| `workspaces.workspace.nameRequired` | Workspace name is required. |
+| `workspaces.workspace.contextDisabled` | Workspace context is disabled. |
+| `workspaces.workspace.slugRequired` | workspaceSlug is required. |
+| `workspaces.workspace.notFound` | Workspace not found. |
+| `workspaces.workspace.accessDenied` | You do not have access to this workspace. |
+| `workspaces.member.roleNotAssignable` | Role is not assignable. |
+| `workspaces.member.notFound` | Member not found. |
+| `workspaces.member.ownerRoleLocked` | Cannot change workspace owner role. |
+| `workspaces.member.ownerNotRemovable` | Cannot remove workspace owner. |
+| `workspaces.invite.disabled` | Workspace invitations are disabled. |
+| `workspaces.invite.notFound` | Invite not found. |
+| `workspaces.invite.notFoundOrHandled` | Invite not found or already handled. |
+| `workspaces.invite.invitationNotFoundOrHandled` | Invitation not found or already handled. |
+| `workspaces.invite.workspaceMissing` | Invitation workspace no longer exists. |
+| `workspaces.invite.expired` | Invitation has expired. |
+| `workspaces.invite.tokenMismatch` | Invitation token does not match the saved invitation. |
+| `workspaces.invite.tokenRequired` | Invite token is required. |
+| `workspaces.invite.tokenInvalid` | Invite token is invalid. |
+| `workspaces.invite.emailMismatchUser` | Invitation email does not match authenticated user. |
+| `workspaces.invite.emailMismatchAccount` | Invitation email does not match account email. |
+| `workspaces.invite.notAvailable` | Invitation is not available. |
+| `workspaces.invite.mailerUnconfigured` | No workspace invite mailer is configured. |
+| `workspaces.invite.sendFailed` | Unable to send workspace invite email. |

package/locales/en.json

@@ -0,0 +1,52 @@
+{
+  "jskit": {
+    "workspaces": {
+      "auth": {
+        "required": "Authentication required."
+      },
+      "user": {
+        "invalidPayload": "Invalid authenticated user payload."
+      },
+      "workspace": {
+        "slugUnavailable": "Unable to generate unique workspace slug.",
+        "creationDisabled": "Workspace creation is disabled for this tenancy mode.",
+        "nameRequired": "Workspace name is required.",
+        "contextDisabled": "Workspace context is disabled.",
+        "slugRequired": "workspaceSlug is required.",
+        "notFound": "Workspace not found.",
+        "accessDenied": "You do not have access to this workspace."
+      },
+      "member": {
+        "roleNotAssignable": "Role is not assignable.",
+        "notFound": "Member not found.",
+        "ownerRoleLocked": "Cannot change workspace owner role.",
+        "ownerNotRemovable": "Cannot remove workspace owner."
+      },
+      "invite": {
+        "disabled": "Workspace invitations are disabled.",
+        "notFound": "Invite not found.",
+        "notFoundOrHandled": "Invite not found or already handled.",
+        "invitationNotFoundOrHandled": "Invitation not found or already handled.",
+        "workspaceMissing": "Invitation workspace no longer exists.",
+        "expired": "Invitation has expired.",
+        "tokenMismatch": "Invitation token does not match the saved invitation.",
+        "tokenRequired": "Invite token is required.",
+        "tokenInvalid": "Invite token is invalid.",
+        "emailMismatchUser": "Invitation email does not match authenticated user.",
+        "emailMismatchAccount": "Invitation email does not match account email.",
+        "notAvailable": "Invitation is not available.",
+        "mailerUnconfigured": "No workspace invite mailer is configured.",
+        "sendFailed": "Unable to send workspace invite email."
+      },
+      "inviteEmail": {
+        "subject": "You're invited to {workspace}",
+        "intro": "You have been invited to join {workspace} as {role}.",
+        "introFromInviter": "{inviter} invited you to join {workspace} as {role}.",
+        "expiry": "This invitation expires at {expiresAt}.",
+        "openLink": "Open this link to accept the invitation:",
+        "accept": "Accept invitation",
+        "workspaceFallback": "the workspace"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/workspaces-core",
-  "version": "0.1.226",
+  "version": "0.2.1",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -15,14 +15,15 @@
     "./shared/tenancyProfile": "./src/shared/tenancyProfile.js",
     "./shared/support/workspacePathModel": "./src/shared/support/workspacePathModel.js",
     "./shared/resources/workspaceResource": "./src/shared/resources/workspaceResource.js",
-    "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js"
+    "./shared/resources/workspaceSettingsResource": "./src/shared/resources/workspaceSettingsResource.js",
+    "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.248",
-    "@jskit-ai/json-rest-api-core": "0.1.192",
-    "@jskit-ai/resource-core": "0.1.190",
-    "@jskit-ai/resource-crud-core": "0.1.190",
-    "@jskit-ai/users-core": "0.1.261",
+    "@jskit-ai/database-runtime": "0.1.250",
+    "@jskit-ai/json-rest-api-core": "0.2.1",
+    "@jskit-ai/resource-core": "0.1.192",
+    "@jskit-ai/resource-crud-core": "0.1.192",
+    "@jskit-ai/users-core": "0.2.1",
     "json-rest-schema": "^1.0.17"
   },
   "description": "Workspace tenancy runtime plus HTTP routes, role catalog, and workspace config scaffolding.",
@@ -35,6 +36,7 @@
       "requires": [
         "auth.extensions",
         "runtime.actions",
+        "runtime.app-root",
         "runtime.bootstrap",
         "runtime.config",
         "runtime.database",
@@ -169,8 +171,8 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.1.246",
-    "@jskit-ai/http-runtime": "0.1.246",
-    "@jskit-ai/kernel": "0.1.248"
+    "@jskit-ai/auth-core": "0.2.1",
+    "@jskit-ai/http-runtime": "0.2.1",
+    "@jskit-ai/kernel": "0.2.1"
   }
 }

package/patterns/workspace-server/PATTERN.md

@@ -49,6 +49,13 @@ responses expose optional `roleLabel` alongside the unchanged `roleSid`.
 Applications with their own invitation renderer may use its optional
 `roleLabel` input; `roleSid` remains the stored role id.
 
+Invitation emails use the recipient's language: `locale` is the saved
+`user_settings.locale` of an existing account with the invited email, else `en`.
+Renderers receive `locale` and `t(key, params)`, which renders a
+`jskit.workspaces.inviteEmail.*` message from the app's
+`src/locales/<code>/jskit.json` (exact locale, then language, then English); the
+mailer's `sendWorkspaceInvite` receives `locale` too.
+
 Keep existing permissions, inheritance, assignability and
 `workspace.defaultInviteRole` when adding a label. `owner` remains
 nonassignable. Custom roles, including specialised Training roles, are ordinary

package/src/server/WorkspacesFeature.js

@@ -15,6 +15,7 @@ import { createRepository as createWorkspaceInvitesRepository } from "./common/r
 import { createRepository as createWorkspaceMembershipsRepository } from "./common/repositories/workspaceMembershipsRepository.js";
 import { createRepository as createWorkspacesRepository } from "./common/repositories/workspacesRepository.js";
 import { createService as createWorkspaceService } from "./common/services/workspaceContextService.js";
+import { createWorkspacesServerI18n } from "./i18n.js";
 import { createWorkspaceBootstrapContributor } from "./workspaceBootstrapContributor.js";
 import { registerWorkspaceDirectoryRoutes } from "./workspaceDirectory/bootWorkspaceDirectoryRoutes.js";
 import { buildWorkspaceDirectoryActions } from "./workspaceDirectory/workspaceDirectoryActions.js";
@@ -98,7 +99,7 @@ async function installWorkspaceResources(jsonRestApi) {
   );
 }
 
-function createWorkspacesRuntime({ config, env, jsonRestApi } = {}) {
+function createWorkspacesRuntime({ appRoot = "", config, env, jsonRestApi, users = null } = {}) {
   const tenancyProfile = resolveTenancyProfile(config);
   const invitationsPolicy = resolveWorkspaceInvitationsPolicy({ config, appConfig: config, tenancyProfile });
   const invitationsEnabled = invitationsPolicy.enabled === true;
@@ -136,7 +137,10 @@ function createWorkspacesRuntime({ config, env, jsonRestApi } = {}) {
     workspaceInvitationsEnabled: invitationsEnabled,
     inviteUrlBuilder: createWorkspaceInviteUrlBuilder({ appConfig: config, env }),
     workspaceInviteMailer: config?.workspaceInviteMailer || null,
-    workspaceInviteEmailTemplate: resolveInviteEmailTemplate(config)
+    workspaceInviteEmailTemplate: resolveInviteEmailTemplate(config),
+    i18n: createWorkspacesServerI18n({ appRoot }),
+    userProfilesRepository: users?.repositories?.userProfiles || null,
+    userSettingsRepository: users?.repositories?.userSettings || null
   });
   const workspaceSettingsService = createWorkspaceSettingsService({
     workspaceSettingsRepository,
@@ -174,6 +178,7 @@ const WorkspacesFeature = defineFeature({
   id: "workspaces.core",
   domain: "workspace",
   requires: {
+    appRoot: "runtime.app-root",
     bootstrap: "runtime.bootstrap",
     config: "runtime.config",
     env: "runtime.env",
@@ -184,9 +189,9 @@ const WorkspacesFeature = defineFeature({
   provides: {
     workspaces: "workspaces.core"
   },
-  async setup({ bootstrap, config, env, http, jsonRestApi, users }) {
+  async setup({ appRoot, bootstrap, config, env, http, jsonRestApi, users }) {
     await installWorkspaceResources(jsonRestApi);
-    const workspaces = createWorkspacesRuntime({ config, env, jsonRestApi });
+    const workspaces = createWorkspacesRuntime({ appRoot, config, env, jsonRestApi, users });
 
     bootstrap.register({
       id: "workspaces.bootstrap",

package/src/server/common/repositories/workspaceInvitesRepository.js

@@ -146,7 +146,7 @@ function createRepository({ api } = {}) {
     }
     const row = await options.trx("workspaces").where({ id }).forUpdate().first("id");
     if (!row) {
-      throw new AppError(404, "Invitation workspace no longer exists.");
+      throw new AppError(404, "Invitation workspace no longer exists.", { code: "workspaces.invite.workspaceMissing" });
     }
   }
 
@@ -335,7 +335,9 @@ function createRepository({ api } = {}) {
     if (!workspaceId) {
       const candidate = await queryInvites({ id }, { ...options, lock: false });
       if (!candidate[0]) {
-        throw new AppError(404, "Invitation not found or already handled.");
+        throw new AppError(404, "Invitation not found or already handled.", {
+          code: "workspaces.invite.invitationNotFoundOrHandled"
+        });
       }
       workspaceId = normalizeInviteRecord(candidate[0]).workspaceId;
     }
@@ -344,7 +346,9 @@ function createRepository({ api } = {}) {
     }
     const invite = await findPendingByIdForWorkspace(id, workspaceId, { ...options, lock: true });
     if (!invite) {
-      throw new AppError(404, "Invitation not found or already handled.");
+      throw new AppError(404, "Invitation not found or already handled.", {
+        code: "workspaces.invite.invitationNotFoundOrHandled"
+      });
     }
     const updatedAt = new Date().toISOString();
     await api.resources.workspaceInvites.patch(

package/src/server/common/services/workspaceContextService.js

@@ -96,7 +96,7 @@ function createService({
         return candidate;
       }
     }
-    throw new AppError(500, "Unable to generate unique workspace slug.");
+    throw new AppError(500, "Unable to generate unique workspace slug.", { code: "workspaces.workspace.slugUnavailable" });
   }
 
   async function ensureWorkspaceSettingsForWorkspace(workspace, options = {}) {
@@ -109,7 +109,7 @@ function createService({
   async function ensurePersonalWorkspaceForUser(user, options = {}) {
     const normalizedUserId = normalizeRecordId(user?.id, { fallback: null });
     if (!normalizedUserId) {
-      throw new AppError(400, "Invalid authenticated user payload.");
+      throw new AppError(400, "Invalid authenticated user payload.", { code: "workspaces.user.invalidPayload" });
     }
 
     const existing = await workspacesRepository.findPersonalByOwnerUserId(normalizedUserId, options);
@@ -166,7 +166,7 @@ function createService({
   async function ensureProvisionedWorkspaceForAuthenticatedUser(user, options = {}) {
     const normalizedUserId = normalizeRecordId(user?.id, { fallback: null });
     if (!normalizedUserId) {
-      throw new AppError(400, "Invalid authenticated user payload.");
+      throw new AppError(400, "Invalid authenticated user payload.", { code: "workspaces.user.invalidPayload" });
     }
 
     if (workspacePolicy.autoProvision !== true) {
@@ -182,16 +182,18 @@ function createService({
   async function createWorkspaceForAuthenticatedUser(user, payload = {}, options = {}) {
     const normalizedUserId = normalizeRecordId(user?.id, { fallback: null });
     if (!normalizedUserId) {
-      throw new AppError(401, "Authentication required.");
+      throw new AppError(401, "Authentication required.", { code: "workspaces.auth.required" });
     }
 
     if (workspacePolicy.allowSelfCreate !== true) {
-      throw new AppError(403, "Workspace creation is disabled for this tenancy mode.");
+      throw new AppError(403, "Workspace creation is disabled for this tenancy mode.", {
+        code: "workspaces.workspace.creationDisabled"
+      });
     }
 
     const createInput = normalizeWorkspaceCreationInput(payload);
     if (!createInput.name) {
-      throw new AppError(400, "Workspace name is required.");
+      throw new AppError(400, "Workspace name is required.", { code: "workspaces.workspace.nameRequired" });
     }
 
     const slugBase = createInput.requestedSlug || toSlugPart(createInput.name);
@@ -226,22 +228,22 @@ function createService({
     const requireMembership = options?.requireMembership !== false;
     const normalizedUserId = normalizeRecordId(user?.id, { fallback: null });
     if (!normalizedUserId) {
-      throw new AppError(401, "Authentication required.");
+      throw new AppError(401, "Authentication required.", { code: "workspaces.auth.required" });
     }
 
     if (resolvedTenancyMode === TENANCY_MODE_NONE) {
-      throw new AppError(403, "Workspace context is disabled.");
+      throw new AppError(403, "Workspace context is disabled.", { code: "workspaces.workspace.contextDisabled" });
     }
 
     const normalizedWorkspaceSlug = normalizeLowerText(workspaceSlug);
     if (!normalizedWorkspaceSlug) {
-      throw new AppError(400, "workspaceSlug is required.");
+      throw new AppError(400, "workspaceSlug is required.", { code: "workspaces.workspace.slugRequired" });
     }
 
     const workspace = await workspacesRepository.findBySlug(normalizedWorkspaceSlug, options);
 
     if (!workspace) {
-      throw new AppError(404, "Workspace not found.");
+      throw new AppError(404, "Workspace not found.", { code: "workspaces.workspace.notFound" });
     }
 
     let membership = await workspaceMembershipsRepository.findByWorkspaceIdAndUserId(
@@ -259,7 +261,7 @@ function createService({
     }
 
     if ((!membership || normalizeLowerText(membership.status) !== "active") && requireMembership) {
-      throw new AppError(403, "You do not have access to this workspace.");
+      throw new AppError(403, "You do not have access to this workspace.", { code: "workspaces.workspace.accessDenied" });
     }
 
     if (!membership || normalizeLowerText(membership.status) !== "active") {

package/src/server/i18n.js

@@ -0,0 +1,10 @@
+import { createServerI18n } from "@jskit-ai/kernel/server/i18n";
+import en from "../../locales/en.json" with { type: "json" };
+
+// Workspace texts rendered on the server (invitation emails) in the recipient's
+// language, from the app's translations under appRoot, or English.
+function createWorkspacesServerI18n({ appRoot = "" } = {}) {
+  return createServerI18n({ appRoot, catalogs: [en] });
+}
+
+export { createWorkspacesServerI18n };

package/src/server/workspaceMembers/defaultWorkspaceInviteEmail.js

@@ -1,3 +1,11 @@
+import { createWorkspacesServerI18n } from "../i18n.js";
+
+const englishI18n = createWorkspacesServerI18n();
+
+function english(key, params) {
+  return englishI18n.t("en", key, params);
+}
+
 function escapeHtml(value = "") {
   return String(value ?? "")
     .replaceAll("&", "&")
@@ -7,29 +15,33 @@ function escapeHtml(value = "") {
     .replaceAll("'", "'");
 }
 
+// t renders a message in the recipient's language. The markup stays here; each
+// translated fragment, parameters included, is escaped before it enters the HTML.
 function renderDefaultWorkspaceInviteEmail({
   inviteUrl = "",
   workspace = {},
   inviter = null,
   roleSid = "member",
   roleLabel = "",
-  expiresAt = ""
+  expiresAt = "",
+  t = english
 } = {}) {
-  const workspaceName = String(workspace?.name || workspace?.slug || "the workspace").trim() || "the workspace";
+  const workspaceName =
+    String(workspace?.name || workspace?.slug || "").trim() || t("jskit.workspaces.inviteEmail.workspaceFallback");
   const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
   const roleName = (typeof roleLabel === "string" ? roleLabel.trim() : "") || String(roleSid || "member").trim() || "member";
-  const expiryText = expiresAt ? `This invitation expires at ${expiresAt}.` : "";
+  const expiryText = expiresAt ? t("jskit.workspaces.inviteEmail.expiry", { expiresAt }) : "";
   const intro = inviterName
-    ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`
-    : `You have been invited to join ${workspaceName} as ${roleName}.`;
-  const subject = `You're invited to ${workspaceName}`;
-  const text = [intro, expiryText, `Open this link to accept the invitation:`, inviteUrl]
+    ? t("jskit.workspaces.inviteEmail.introFromInviter", { inviter: inviterName, workspace: workspaceName, role: roleName })
+    : t("jskit.workspaces.inviteEmail.intro", { workspace: workspaceName, role: roleName });
+  const subject = t("jskit.workspaces.inviteEmail.subject", { workspace: workspaceName });
+  const text = [intro, expiryText, t("jskit.workspaces.inviteEmail.openLink"), inviteUrl]
     .filter(Boolean)
     .join("\n\n");
   const html = [
     `<p>${escapeHtml(intro)}</p>`,
     expiryText ? `<p>${escapeHtml(expiryText)}</p>` : "",
-    `<p><a href="${escapeHtml(inviteUrl)}">Accept invitation</a></p>`,
+    `<p><a href="${escapeHtml(inviteUrl)}">${escapeHtml(t("jskit.workspaces.inviteEmail.accept"))}</a></p>`,
     `<p>${escapeHtml(inviteUrl)}</p>`
   ].filter(Boolean).join("\n");
 

package/src/server/workspaceMembers/workspaceMembersService.js

@@ -2,10 +2,19 @@ import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeLowerText, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { encodeInviteTokenHash } from "@jskit-ai/auth-core/shared/inviteTokens";
 import { resolveInviteTokenHash, buildInviteToken, hashInviteToken } from "@jskit-ai/auth-core/server/inviteTokens";
-import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { AppError, createValidationError } from "@jskit-ai/kernel/server/runtime/errors";
 import { OWNER_ROLE_ID, createWorkspaceRoleCatalog, cloneWorkspaceRoleCatalog } from "../../shared/roles.js";
+import { createWorkspacesServerI18n } from "../i18n.js";
 import { renderDefaultWorkspaceInviteEmail } from "./defaultWorkspaceInviteEmail.js";
 
+const DEFAULT_LOCALE = "en";
+
+function roleNotAssignableError() {
+  return createValidationError({
+    roleSid: { code: "workspaces.member.roleNotAssignable", message: "Role is not assignable." }
+  });
+}
+
 function createService({
   workspaceMembershipsRepository,
   workspaceInvitesRepository,
@@ -14,7 +23,10 @@ function createService({
   workspaceInvitationsEnabled = true,
   inviteUrlBuilder = null,
   workspaceInviteMailer = null,
-  workspaceInviteEmailTemplate = renderDefaultWorkspaceInviteEmail
+  workspaceInviteEmailTemplate = renderDefaultWorkspaceInviteEmail,
+  i18n = createWorkspacesServerI18n(),
+  userProfilesRepository = null,
+  userSettingsRepository = null
 } = {}) {
   if (!workspaceMembershipsRepository || !workspaceInvitesRepository) {
     throw new Error("workspaceMembersService requires membership and invite repositories.");
@@ -43,7 +55,7 @@ function createService({
     if (resolvedWorkspaceInvitationsEnabled) {
       return;
     }
-    throw new AppError(403, "Workspace invitations are disabled.");
+    throw new AppError(403, "Workspace invitations are disabled.", { code: "workspaces.invite.disabled" });
   }
 
   function withRoleCatalog(payload = {}) {
@@ -100,17 +112,36 @@ function createService({
     };
   }
 
+  // The saved locale of an existing account with the invited email, else English.
+  // A failed lookup must not stop the invitation, so it also falls back to English.
+  async function resolveRecipientLocale(email, options = {}) {
+    if (typeof userProfilesRepository?.findByEmail !== "function" ||
+      typeof userSettingsRepository?.findByUserId !== "function") {
+      return DEFAULT_LOCALE;
+    }
+    try {
+      const profile = await userProfilesRepository.findByEmail(email, options);
+      const settings = profile?.id ? await userSettingsRepository.findByUserId(profile.id, options) : null;
+      return normalizeText(settings?.locale) || DEFAULT_LOCALE;
+    } catch {
+      return DEFAULT_LOCALE;
+    }
+  }
+
   async function deliverInviteEmail({ workspace, user, invite, inviteUrl } = {}, options = {}) {
     if (!resolvedWorkspaceInviteMailer || typeof resolvedWorkspaceInviteMailer.sendWorkspaceInvite !== "function") {
       return {
         status: "mailer_unconfigured",
         message: "No workspace invite mailer is configured.",
+        messageCode: "workspaces.invite.mailerUnconfigured",
+        messageParams: {},
         providerMessageId: ""
       };
     }
 
     try {
       const roleLabel = resolvedRoleCatalog.roles?.find((role) => role.id === invite.roleSid)?.label;
+      const locale = await resolveRecipientLocale(invite.email, options);
       const message = await resolvedWorkspaceInviteEmailTemplate({
         email: invite.email,
         inviteUrl,
@@ -118,7 +149,9 @@ function createService({
         inviter: user || null,
         roleSid: invite.roleSid,
         ...(roleLabel ? { roleLabel } : {}),
-        expiresAt: invite.expiresAt
+        expiresAt: invite.expiresAt,
+        locale,
+        t: (key, params) => i18n.t(locale, key, params)
       });
       const result = await resolvedWorkspaceInviteMailer.sendWorkspaceInvite({
         email: invite.email,
@@ -127,6 +160,7 @@ function createService({
         inviter: user || null,
         roleSid: invite.roleSid,
         expiresAt: invite.expiresAt,
+        locale,
         message
       }, options);
       return normalizeInviteDeliveryResult(result || { status: "sent" });
@@ -135,6 +169,8 @@ function createService({
         status: "failed",
         // Provider errors can contain the secret invitation URL.
         message: "Unable to send workspace invite email.",
+        messageCode: "workspaces.invite.sendFailed",
+        messageParams: {},
         providerMessageId: ""
       };
     }
@@ -164,24 +200,18 @@ function createService({
     const memberUserId = normalizeRecordId(payload.memberUserId, { fallback: null });
     const roleSid = normalizeLowerText(payload.roleSid || "");
     if (!memberUserId) {
-      throw new AppError(400, "Validation failed.");
+      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
     }
     if (!assignableRoleIds.includes(roleSid)) {
-      throw new AppError(400, "Validation failed.", {
-        details: {
-          fieldErrors: {
-            roleSid: "Role is not assignable."
-          }
-        }
-      });
+      throw roleNotAssignableError();
     }
 
     const existingMembership = await workspaceMembershipsRepository.findByWorkspaceIdAndUserId(workspace.id, memberUserId, options);
     if (!existingMembership || existingMembership.status !== "active") {
-      throw new AppError(404, "Member not found.");
+      throw new AppError(404, "Member not found.", { code: "workspaces.member.notFound" });
     }
     if (memberUserId === normalizeRecordId(workspace.ownerUserId, { fallback: null }) || existingMembership.roleSid === OWNER_ROLE_ID) {
-      throw new AppError(409, "Cannot change workspace owner role.");
+      throw new AppError(409, "Cannot change workspace owner role.", { code: "workspaces.member.ownerRoleLocked" });
     }
 
     await workspaceMembershipsRepository.upsertMembership(
@@ -200,15 +230,15 @@ function createService({
   async function removeMember(workspace, payload = {}, options = {}) {
     const memberUserId = normalizeRecordId(payload.memberUserId, { fallback: null });
     if (!memberUserId) {
-      throw new AppError(400, "Validation failed.");
+      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
     }
 
     const existingMembership = await workspaceMembershipsRepository.findByWorkspaceIdAndUserId(workspace.id, memberUserId, options);
     if (!existingMembership || existingMembership.status !== "active") {
-      throw new AppError(404, "Member not found.");
+      throw new AppError(404, "Member not found.", { code: "workspaces.member.notFound" });
     }
     if (memberUserId === normalizeRecordId(workspace.ownerUserId, { fallback: null }) || existingMembership.roleSid === OWNER_ROLE_ID) {
-      throw new AppError(409, "Cannot remove workspace owner.");
+      throw new AppError(409, "Cannot remove workspace owner.", { code: "workspaces.member.ownerNotRemovable" });
     }
 
     await workspaceMembershipsRepository.upsertMembership(
@@ -246,13 +276,7 @@ function createService({
     const email = normalizeLowerText(payload.email);
     const roleSid = normalizeLowerText(payload.roleSid || "member") || "member";
     if (!assignableRoleIds.includes(roleSid)) {
-      throw new AppError(400, "Validation failed.", {
-        details: {
-          fieldErrors: {
-            roleSid: "Role is not assignable."
-          }
-        }
-      });
+      throw roleNotAssignableError();
     }
 
     const token = buildInviteToken();
@@ -291,16 +315,18 @@ function createService({
       { ...options, includeWorkspace: true, lock: false }
     );
     if (!invite) {
-      throw new AppError(404, "Invite not found or already handled.");
+      throw new AppError(404, "Invite not found or already handled.", { code: "workspaces.invite.notFoundOrHandled" });
     }
     if (invite.expiresAt && new Date(invite.expiresAt).getTime() < Date.now()) {
-      throw new AppError(409, "Invitation has expired.");
+      throw new AppError(409, "Invitation has expired.", { code: "workspaces.invite.expired" });
     }
     const token = Object.hasOwn(prepared, "inviteTokenPreview")
       ? normalizeText(prepared.inviteTokenPreview)
       : encodeInviteTokenHash(invite.tokenHash);
     if (!token || resolveInviteTokenHash(token) !== invite.tokenHash) {
-      throw new AppError(400, "Invitation token does not match the saved invitation.");
+      throw new AppError(400, "Invitation token does not match the saved invitation.", {
+        code: "workspaces.invite.tokenMismatch"
+      });
     }
     const savedWorkspace = {
       ...workspace,
@@ -336,7 +362,7 @@ function createService({
     ensureWorkspaceInvitationsEnabled();
     const normalizedInviteId = normalizeRecordId(inviteId, { fallback: null });
     if (!normalizedInviteId) {
-      throw new AppError(400, "Validation failed.");
+      throw new AppError(400, "Validation failed.", { code: "validation_failed" });
     }
 
     const revoke = async (trx) => {
@@ -347,7 +373,7 @@ function createService({
         transactionOptions
       );
       if (!invite) {
-        throw new AppError(404, "Invite not found.");
+        throw new AppError(404, "Invite not found.", { code: "workspaces.invite.notFound" });
       }
       await workspaceInvitesRepository.revokeById(normalizedInviteId, transactionOptions);
       return normalizeRecordId(invite.id, { fallback: null });

package/src/server/workspacePendingInvitations/workspacePendingInvitationsService.js

@@ -52,14 +52,14 @@ function createService({
     }));
     // Commit expiry revocation before reporting the rejection.
     if (result.expired) {
-      throw Object.assign(new AppError(409, "Invitation has expired."), { transactionOutcome: "committed" });
+      throw Object.assign(new AppError(409, "Invitation has expired.", { code: "workspaces.invite.expired" }), { transactionOutcome: "committed" });
     }
     return result;
   }
 
   function requireAuthenticatedInviteUser(user) {
     if (!normalizeRecordId(user?.id, { fallback: null })) {
-      throw new AppError(401, "Authentication required.");
+      throw new AppError(401, "Authentication required.", { code: "workspaces.auth.required" });
     }
 
     return user;
@@ -68,12 +68,12 @@ function createService({
   function requireInviteTokenHash(token) {
     const normalizedToken = normalizeText(token);
     if (!normalizedToken) {
-      throw new AppError(400, "Invite token is required.");
+      throw new AppError(400, "Invite token is required.", { code: "workspaces.invite.tokenRequired" });
     }
 
     const tokenHash = resolveInviteTokenHash(normalizedToken);
     if (!tokenHash) {
-      throw new AppError(400, "Invite token is invalid.");
+      throw new AppError(400, "Invite token is invalid.", { code: "workspaces.invite.tokenInvalid" });
     }
 
     return tokenHash;
@@ -170,11 +170,15 @@ function createService({
 
     const invite = await workspaceInvitesRepository.findPendingByTokenHash(tokenHash, options);
     if (!invite) {
-      throw new AppError(404, "Invitation not found or already handled.");
+      throw new AppError(404, "Invitation not found or already handled.", {
+        code: "workspaces.invite.invitationNotFoundOrHandled"
+      });
     }
 
     if (normalizeLowerText(invite.email) !== normalizeLowerText(actor?.email)) {
-      throw new AppError(403, "Invitation email does not match authenticated user.");
+      throw new AppError(403, "Invitation email does not match authenticated user.", {
+        code: "workspaces.invite.emailMismatchUser"
+      });
     }
 
     return {
@@ -206,10 +210,12 @@ function createService({
   async function resolveInviteContextForAuth({ token, email } = {}, options = {}) {
     const resolved = await resolveInviteByToken(token, options);
     if (resolved.status !== "pending") {
-      throw new AppError(409, "Invitation is not available.");
+      throw new AppError(409, "Invitation is not available.", { code: "workspaces.invite.notAvailable" });
     }
     if (normalizeLowerText(resolved.email) !== normalizeLowerText(email)) {
-      throw new AppError(403, "Invitation email does not match account email.");
+      throw new AppError(403, "Invitation email does not match account email.", {
+        code: "workspaces.invite.emailMismatchAccount"
+      });
     }
 
     return {

package/src/shared/resources/workspaceMembersResource.js

@@ -105,6 +105,15 @@ const workspaceInviteCreateOutputSchema = createSchema({
         type: "string",
         required: true
       },
+      messageCode: {
+        type: "string",
+        required: false
+      },
+      messageParams: {
+        type: "object",
+        required: false,
+        additionalProperties: true
+      },
       providerMessageId: {
         type: "string",
         required: true

package/test/exportsContract.test.js

@@ -19,7 +19,9 @@ test("workspaces-core exports are explicit and aligned with production usage", (
       "./server/validators/routeParamsValidator",
       "./server/support/workspaceRouteInput",
       "./shared/resources/workspaceResource",
-      "./shared/resources/workspaceSettingsResource"
+      "./shared/resources/workspaceSettingsResource",
+      // The generated client bootstrap registers it so clients render these server codes.
+      "./locales/en.json"
     ]
   });
 

package/test/featureRuntime.test.js

@@ -73,6 +73,7 @@ test("WorkspacesFeature assembles workspace behavior and explicit integrations",
   const runtime = createCapabilityRuntime({
     inputs: {
       "auth.extensions": authExtensions,
+      "runtime.app-root": process.cwd(),
       "runtime.bootstrap": bootstrap,
       "runtime.config": runtimeConfig(),
       "runtime.env": {},

package/test/i18nCatalog.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+
+test("workspaces-core English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: path.join(REPO_ROOT, "packages", "workspaces-core")
+  });
+  assert.deepEqual(problems, []);
+});

package/test/repositories.integration.test.js

@@ -182,7 +182,7 @@ describe(`users and workspaces repositories on migrated ${databaseLabel}`, () =>
       locale: " EN-AU ", currencyCode: "aud", timeZone: " Australia/Perth ",
       avatarSize: 96, theme: " dark ", ignoredField: "must not reach storage"
     });
-    assert.equal(preferences.locale, "en-au");
+    assert.equal(preferences.locale, "en-AU");
     assert.equal(preferences.currencyCode, "AUD");
     assert.equal(preferences.timeZone, "Australia/Perth");
     assert.equal(preferences.avatarSize, 96);

package/test/workspaceMembersService.test.js

@@ -1,5 +1,9 @@
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import test from "node:test";
+import { createWorkspacesServerI18n } from "../src/server/i18n.js";
 import { createService } from "../src/server/workspaceMembers/workspaceMembersService.js";
 import { createWorkspaceRoleCatalog } from "../src/shared/roles.js";
 
@@ -155,6 +159,8 @@ test("workspaceMembersService.createInvite uses configured inviteExpiresInMs", a
   assert.deepEqual(response.inviteDelivery, {
     status: "mailer_unconfigured",
     message: "No workspace invite mailer is configured.",
+    messageCode: "workspaces.invite.mailerUnconfigured",
+    messageParams: {},
     providerMessageId: ""
   });
 });
@@ -245,7 +251,9 @@ test("workspaceMembersService.createInvite sends generated invite URLs through t
   assert.equal(templateCalls[0].email, "invitee@example.com");
   assert.equal(templateCalls[0].workspace.name, "Acme");
   assert.equal(templateCalls[0].inviteUrl, response.inviteUrl);
+  assert.equal(templateCalls[0].locale, "en");
   assert.equal(mailerCalls.length, 1);
+  assert.equal(mailerCalls[0].payload.locale, "en");
   assert.equal(mailerCalls[0].payload.email, "invitee@example.com");
   assert.equal(mailerCalls[0].payload.inviteUrl, response.inviteUrl);
   assert.equal(mailerCalls[0].payload.message.subject, "Join Acme");
@@ -529,3 +537,141 @@ test("workspaceMembersService.removeMember rejects removing the owner", async ()
     /Cannot remove workspace owner/
   );
 });
+
+function createMailingService({ accounts = {}, appRoot = "", mailer } = {}) {
+  let savedInvite;
+  return createService({
+    workspaceMembershipsRepository: {
+      async listActiveByWorkspaceId() {
+        return [];
+      }
+    },
+    workspaceInvitesRepository: {
+      async withTransaction(work) {
+        return work({});
+      },
+      async lockWorkspaceForInvitations() {},
+      async expirePendingByWorkspaceIdAndEmail() {},
+      async insert(payload) {
+        savedInvite = { ...payload, id: "88", workspaceSlug: "acme", workspaceName: "Acme & Co" };
+        return savedInvite;
+      },
+      async listPendingByWorkspaceIdWithWorkspace() {
+        return [];
+      },
+      async findPendingByIdForWorkspace() {
+        return savedInvite;
+      }
+    },
+    inviteExpiresInMs: 30 * 60 * 1000,
+    roleCatalog: createRoleCatalog(),
+    inviteUrlBuilder: ({ token }) => `https://app.example.test/invite/${token}`,
+    workspaceInviteMailer: mailer,
+    i18n: createWorkspacesServerI18n({ appRoot }),
+    userProfilesRepository: {
+      async findByEmail(email) {
+        return accounts[email] ? { id: accounts[email].id } : null;
+      }
+    },
+    userSettingsRepository: {
+      async findByUserId(userId) {
+        const account = Object.values(accounts).find((entry) => entry.id === userId);
+        if (account?.fail) {
+          throw new Error("settings unavailable");
+        }
+        return account ? { locale: account.locale } : null;
+      }
+    }
+  });
+}
+
+test("workspaceMembersService renders the default invitation email in the recipient's saved locale", async (t) => {
+  const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), "workspaces-invite-i18n-"));
+  t.after(() => fs.rmSync(appRoot, { recursive: true, force: true }));
+  fs.mkdirSync(path.join(appRoot, "src", "locales", "it"), { recursive: true });
+  fs.writeFileSync(path.join(appRoot, "src", "locales", "it", "jskit.json"), JSON.stringify({
+    jskit: {
+      workspaces: {
+        inviteEmail: {
+          subject: "Sei invitato in {workspace}",
+          introFromInviter: "{inviter} ti ha invitato in {workspace} come {role}.",
+          accept: "Accetta l'invito"
+        }
+      }
+    }
+  }));
+  const sent = [];
+  const service = createMailingService({
+    appRoot,
+    accounts: {
+      "rossi@example.com": { id: "21", locale: "it-it" },
+      "ada@example.com": { id: "22", locale: "en" },
+      "broken@example.com": { id: "23", fail: true }
+    },
+    mailer: {
+      async sendWorkspaceInvite(payload) {
+        sent.push(payload);
+        return { status: "sent", providerMessageId: `msg-${sent.length}` };
+      }
+    }
+  });
+  const workspace = { id: "7", slug: "acme", name: "Acme & Co", ownerUserId: "9", avatarUrl: "" };
+  const owner = { id: "9", displayName: "Tony <Owner>" };
+  const invite = (email) => service.createInvite(workspace, owner, { email, roleSid: "member" }, authorizedOptions());
+
+  await invite("rossi@example.com");
+  assert.equal(sent[0].locale, "it-it");
+  assert.equal(sent[0].message.subject, "Sei invitato in Acme & Co");
+  assert.match(sent[0].message.text, /^Tony <Owner> ti ha invitato in Acme & Co come member\./u);
+  assert.match(sent[0].message.text, /Open this link to accept the invitation:/u, "missing translations stay English");
+  assert.match(sent[0].message.html, /<p>Tony &lt;Owner&gt; ti ha invitato in Acme &amp; Co come member\.<\/p>/u);
+  assert.match(sent[0].message.html, />Accetta l&#39;invito<\/a>/u);
+
+  for (const email of ["ada@example.com", "stranger@example.com", "broken@example.com"]) {
+    await invite(email);
+    const { locale, message } = sent.at(-1);
+    assert.equal(locale, "en", email);
+    assert.equal(message.subject, "You're invited to Acme & Co", email);
+    assert.match(message.text, /^Tony <Owner> invited you to join Acme & Co as member\./u, email);
+  }
+});
+
+test("workspaceMembersService reports a failed delivery with a message code", async () => {
+  const service = createMailingService({
+    mailer: {
+      async sendWorkspaceInvite() {
+        throw new Error("provider rejected https://app.example.test/invite/secret");
+      }
+    }
+  });
+  const response = await service.createInvite(
+    { id: "7", slug: "acme", name: "Acme", ownerUserId: "9", avatarUrl: "" },
+    { id: "9" },
+    { email: "invitee@example.com", roleSid: "member" },
+    authorizedOptions()
+  );
+  assert.deepEqual(response.inviteDelivery, {
+    status: "failed",
+    message: "Unable to send workspace invite email.",
+    messageCode: "workspaces.invite.sendFailed",
+    messageParams: {},
+    providerMessageId: ""
+  });
+});
+
+test("workspaceMembersService codes a role that cannot be assigned", async () => {
+  const { service, workspace } = createFixture();
+  await assert.rejects(
+    () => service.updateMemberRole(workspace, { memberUserId: "11", roleSid: "owner" }, authorizedOptions()),
+    (error) => {
+      assert.equal(error.status, 400);
+      assert.equal(error.message, "Validation failed.");
+      assert.equal(error.code, "validation_failed");
+      assert.deepEqual(error.details, {
+        fieldErrors: { roleSid: "Role is not assignable." },
+        fieldErrorCodes: { roleSid: { code: "workspaces.member.roleNotAssignable", params: {} } }
+      });
+      return true;
+    }
+  );
+});