From f9285ab69e1ae33a42af874b4cb4ddf822e13bd0 Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sat, 1 Aug 2026 09:27:41 +0800
Subject: [PATCH 1/3] fix(environment): localize the entitlement dialog + read
 cloud's nested error envelope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The free-plan "Development environments are a paid feature" prompt is a
paid-conversion surface, and it was hardcoded English in an otherwise
localized console (cloud#959). Two separate defects behind that:

**Copy was English literals.** `upgradeDialogSpec` built the sentence users
actually reported — including its lowercase `your free plan`, which came from
string concatenation here, not from the control plane. Both spec builders now
take a translator and resolve `environment.entitlement.*`; all ten locale
packs carry the strings (objectui#2872 parity). `entitlements.ts` stays
dependency-free — `t` is passed in, not imported, and defaults to the English
copy with local `{{token}}` interpolation.

The dialog now renders the CONSOLE's copy rather than the server's prose. A
control plane upgrades independently of the console and only localizes these
messages from cloud#959 on, so preferring the server string would have left
the reactive path English against every older deployment — and the two paths
are meant to read identically anyway.

**The reactive dialog had stopped firing.** cloud#948 moved coded errors into
a nested envelope (`{ success, error: { code, message, … } }`);
`entitlementDialogFromError` read `code` off the top level, so it returned
null for every entitlement 403 and the friendly upgrade dialog silently
degraded to a generic red error toast. It now reads both shapes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../environment/EnvironmentListToolbar.tsx    |   4 +-
 .../__tests__/entitlements.test.ts            |  90 +++++++++-
 .../app-shell/src/environment/entitlements.ts | 154 ++++++++++++++----
 .../useConsoleActionRuntime.test.tsx          |   9 +
 .../src/hooks/useConsoleActionRuntime.tsx     |   9 +-
 packages/i18n/src/locales/ar.ts               |  14 ++
 packages/i18n/src/locales/de.ts               |  14 ++
 packages/i18n/src/locales/en.ts               |  19 +++
 packages/i18n/src/locales/es.ts               |  14 ++
 packages/i18n/src/locales/fr.ts               |  14 ++
 packages/i18n/src/locales/ja.ts               |  14 ++
 packages/i18n/src/locales/ko.ts               |  14 ++
 packages/i18n/src/locales/pt.ts               |  14 ++
 packages/i18n/src/locales/ru.ts               |  14 ++
 packages/i18n/src/locales/zh.ts               |  16 ++
 15 files changed, 374 insertions(+), 39 deletions(-)

diff --git a/packages/app-shell/src/environment/EnvironmentListToolbar.tsx b/packages/app-shell/src/environment/EnvironmentListToolbar.tsx
index 1b0b59a7f6..ca967220e8 100644
--- a/packages/app-shell/src/environment/EnvironmentListToolbar.tsx
+++ b/packages/app-shell/src/environment/EnvironmentListToolbar.tsx
@@ -93,7 +93,7 @@ export function EnvironmentListToolbar({ actions, entitlements, onUpgrade }: Pro
   // onUpgrade sets parent state.
   useEffect(() => {
     if (autoRunCreate && ctaKind === 'upgrade_for_development' && entitlements) {
-      onUpgrade(upgradeDialogSpec(entitlements));
+      onUpgrade(upgradeDialogSpec(entitlements, t));
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [autoRunCreate, ctaKind]);
@@ -114,7 +114,7 @@ export function EnvironmentListToolbar({ actions, entitlements, onUpgrade }: Pro
         )}
         <Button
           size="sm"
-          onClick={() => onUpgrade(upgradeDialogSpec(entitlements!))}
+          onClick={() => onUpgrade(upgradeDialogSpec(entitlements!, t))}
           className="shadow-none gap-1.5 sm:gap-2 h-8 sm:h-9"
           data-testid="environment-add-upgrade"
         >
diff --git a/packages/app-shell/src/environment/__tests__/entitlements.test.ts b/packages/app-shell/src/environment/__tests__/entitlements.test.ts
index c525fcac40..d8ad1b771b 100644
--- a/packages/app-shell/src/environment/__tests__/entitlements.test.ts
+++ b/packages/app-shell/src/environment/__tests__/entitlements.test.ts
@@ -49,14 +49,74 @@ describe('entitlementDialogFromError', () => {
     expect(spec).not.toBeNull();
     expect(spec!.code).toBe('DEV_ENV_PLAN_LOCKED');
     expect(spec!.title).toBe('Development environments are a paid feature');
-    expect(spec!.message).toContain('paid feature'); // server message preserved
+    expect(spec!.message).toContain('Your free plan includes one production environment');
     expect(spec!.cta).toEqual({ label: 'Upgrade plan', url: '/settings/billing' });
   });
 
+  it('names a paid plan in the plan-locked copy', () => {
+    const spec = entitlementDialogFromError({ code: 'DEV_ENV_PLAN_LOCKED', plan: 'team' });
+    expect(spec!.message).toContain('Your team plan includes');
+  });
+
   it('maps DEV_ENV_LIMIT to an upgrade dialog (limit-reached title)', () => {
     const spec = entitlementDialogFromError({ code: 'DEV_ENV_LIMIT', upgrade_url: '/u' });
     expect(spec!.title).toBe('Development environment limit reached');
     expect(spec!.cta!.url).toBe('/u');
+    expect(spec!.message).toContain('Capacity scales with AI seats');
+  });
+
+  it('quotes the seat-pool usage when the server reports counts', () => {
+    const spec = entitlementDialogFromError({ code: 'DEV_ENV_LIMIT', current: 3, limit: 3 });
+    expect(spec!.message).toContain('using 3 of 3 development environments');
+  });
+
+  // cloud#948 nested every coded error under `error: { … }`. Reading `code` off
+  // the top level made this mapper return null against an up-to-date control
+  // plane, degrading the friendly dialog to a generic red toast.
+  it('reads the nested cloud#948 error envelope', () => {
+    const spec = entitlementDialogFromError({
+      success: false,
+      error: {
+        code: 'DEV_ENV_PLAN_LOCKED',
+        message: 'Development environments are a paid feature. …',
+        httpStatus: 403,
+        plan: 'free',
+        upgrade_url: '/settings/billing',
+      },
+    });
+    expect(spec).not.toBeNull();
+    expect(spec!.code).toBe('DEV_ENV_PLAN_LOCKED');
+    expect(spec!.cta).toEqual({ label: 'Upgrade plan', url: '/settings/billing' });
+  });
+
+  it('still reads the legacy flat body (older control planes)', () => {
+    const spec = entitlementDialogFromError({
+      success: false,
+      error: 'Development environments are a paid feature. …',
+      code: 'DEV_ENV_PLAN_LOCKED',
+      upgrade_url: '/legacy',
+    });
+    expect(spec!.cta!.url).toBe('/legacy');
+  });
+
+  // cloud#959 — the dialog is a paid-conversion surface, so its copy comes from
+  // the Console's own locale bundle rather than the (possibly older, possibly
+  // English-only) control plane.
+  it('renders localized copy when a translator is supplied, ignoring server prose', () => {
+    const zh = (key: string, o?: any) =>
+      ({
+        'environment.entitlement.planLockedTitle': '开发环境是付费功能',
+        'environment.entitlement.planLockedBody': `${o?.plan}包含一个生产环境。升级后即可添加开发环境。`,
+        'environment.entitlement.freePlan': '免费版',
+        'environment.entitlement.upgradeCta': '升级套餐',
+      })[key] ?? key;
+    const spec = entitlementDialogFromError(
+      { error: { code: 'DEV_ENV_PLAN_LOCKED', message: 'Development environments are a paid feature.' } },
+      zh,
+    );
+    expect(spec!.title).toBe('开发环境是付费功能');
+    expect(spec!.message).toBe('免费版包含一个生产环境。升级后即可添加开发环境。');
+    expect(spec!.cta!.label).toBe('升级套餐');
   });
 
   it('maps PRODUCTION_ENV_LIMIT to a contact-sales dialog (no upgrade CTA)', () => {
@@ -97,4 +157,32 @@ describe('upgradeDialogSpec', () => {
     expect(spec.cta).toEqual({ label: 'Upgrade plan', url: '/settings/billing' });
     expect(spec.message).toContain('free plan');
   });
+
+  // The lowercase-`your` sentence users reported (cloud#959) came from this
+  // builder, not from the control plane.
+  it('opens the sentence with a capital letter', () => {
+    const spec = upgradeDialogSpec(base({ plan: 'free' }));
+    expect(spec.message.startsWith('Your ')).toBe(true);
+  });
+
+  it('reads identically to the reactive DEV_ENV_PLAN_LOCKED dialog', () => {
+    const proactive = upgradeDialogSpec(base({ plan: 'free', upgradeUrl: '/settings/billing' }));
+    const reactive = entitlementDialogFromError({
+      error: { code: 'DEV_ENV_PLAN_LOCKED', plan: 'free', upgrade_url: '/settings/billing' },
+    });
+    expect(reactive).toEqual(proactive);
+  });
+
+  it('localizes through the supplied translator', () => {
+    const zh = (key: string, o?: any) =>
+      ({
+        'environment.entitlement.planLockedTitle': '开发环境是付费功能',
+        'environment.entitlement.planLockedBody': `${o?.plan}包含一个生产环境。`,
+        'environment.entitlement.freePlan': '免费版',
+        'environment.entitlement.upgradeCta': '升级套餐',
+      })[key] ?? key;
+    const spec = upgradeDialogSpec(base({ plan: 'free' }), zh);
+    expect(spec.title).toBe('开发环境是付费功能');
+    expect(spec.message).toBe('免费版包含一个生产环境。');
+  });
 });
diff --git a/packages/app-shell/src/environment/entitlements.ts b/packages/app-shell/src/environment/entitlements.ts
index 0a57e75645..6eba4692af 100644
--- a/packages/app-shell/src/environment/entitlements.ts
+++ b/packages/app-shell/src/environment/entitlements.ts
@@ -48,45 +48,122 @@ export interface EntitlementDialogSpec {
 export const DEFAULT_UPGRADE_URL = '/settings/billing';
 
 /**
- * Map a cloud env-create 403 body
- * (`{ error, code, upgrade_url, contact_url, plan, current, limit }`) to a
- * dialog spec. Returns `null` for any non-entitlement error so the caller falls
- * back to its normal error handling (a red toast). This is the safety net: it
- * fires regardless of whether the up-front state-aware presentation was right.
+ * Minimal translator — structurally `useObjectTranslation()`'s `t`, passed IN
+ * rather than imported so this module stays dependency-free and the specs stay
+ * unit-testable without an i18n provider. Omit it and the English defaults are
+ * used (with `{{token}}` interpolation applied locally).
  */
-export function entitlementDialogFromError(body: any): EntitlementDialogSpec | null {
-  const code = body?.code;
+export type EntitlementTranslate = (key: string, options?: Record<string, any>) => string;
+
+/** English default + `{{token}}` interpolation, for callers with no `t`. */
+function fallbackTranslate(key: string, options?: Record<string, any>): string {
+  const raw = typeof options?.defaultValue === 'string' ? options.defaultValue : key;
+  return raw.replace(/\{\{(\w+)\}\}/g, (_m, name: string) => String(options?.[name] ?? ''));
+}
+
+/**
+ * The plan phrase interpolated into the plan-locked copy — "free plan" /
+ * "team plan" in English, 「免费版」/「team 版」in Chinese.
+ */
+function planPhrase(t: EntitlementTranslate, plan: unknown): string {
+  return typeof plan === 'string' && plan && plan !== 'free'
+    ? t('environment.entitlement.namedPlan', { plan, defaultValue: '{{plan}} plan' })
+    : t('environment.entitlement.freePlan', { defaultValue: 'free plan' });
+}
+
+/**
+ * Read the coded-error fields off a cloud error body, tolerating BOTH shapes:
+ *
+ *   • nested (cloud#948 and later) — `{ success, error: { code, message, … } }`
+ *   • flat (older control planes)  — `{ success, error: '…', code, … }`
+ *
+ * The nested envelope moved `code` a level down, which made this mapper return
+ * `null` for every entitlement 403 — so the friendly upgrade dialog silently
+ * degraded to a generic red toast against an up-to-date control plane. Control
+ * planes upgrade independently of the Console, so both shapes stay supported.
+ */
+function entitlementErrorFields(body: any): any {
+  const nested = body?.error;
+  return nested && typeof nested === 'object' ? nested : body;
+}
+
+/**
+ * Map a cloud env-create 403 body to a dialog spec. Returns `null` for any
+ * non-entitlement error so the caller falls back to its normal error handling
+ * (a red toast). This is the safety net: it fires regardless of whether the
+ * up-front state-aware presentation was right.
+ *
+ * The copy is the CONSOLE's, not the server's: a control plane may be older
+ * than the Console (or newer), and its prose is only localized from cloud#959
+ * on. Rendering our own localized strings — from the same code + counts the
+ * server reports — keeps this dialog in the user's language either way, and
+ * keeps it identical to the proactive prompt in {@link upgradeDialogSpec}.
+ */
+export function entitlementDialogFromError(body: any, t: EntitlementTranslate = fallbackTranslate): EntitlementDialogSpec | null {
+  const fields = entitlementErrorFields(body);
+  const code = fields?.code;
   if (!isEntitlementErrorCode(code)) return null;
-  const serverMessage =
-    typeof body?.error === 'string' && body.error ? body.error
-      : typeof body?.message === 'string' ? body.message : '';
   const upgradeUrl =
-    typeof body?.upgrade_url === 'string' && body.upgrade_url ? body.upgrade_url : DEFAULT_UPGRADE_URL;
-  const contactUrl = typeof body?.contact_url === 'string' && body.contact_url ? body.contact_url : '';
+    typeof fields?.upgrade_url === 'string' && fields.upgrade_url ? fields.upgrade_url : DEFAULT_UPGRADE_URL;
+  const contactUrl = typeof fields?.contact_url === 'string' && fields.contact_url ? fields.contact_url : '';
 
   if (code === 'PRODUCTION_ENV_LIMIT') {
     return {
       code,
-      title: 'You already have your production environment',
-      message:
-        serverMessage ||
-        'Each organization includes exactly one production environment. Create a separate organization for another, or contact us about an Enterprise arrangement.',
-      cta: contactUrl ? { label: 'Contact sales', url: contactUrl } : undefined,
+      title: t('environment.entitlement.productionLimitTitle', {
+        defaultValue: 'You already have your production environment',
+      }),
+      message: t('environment.entitlement.productionLimitBody', {
+        defaultValue:
+          'Each organization includes exactly one production environment. Create a separate organization for another, or contact us about an Enterprise arrangement.',
+      }),
+      cta: contactUrl
+        ? { label: t('environment.entitlement.contactSalesCta', { defaultValue: 'Contact sales' }), url: contactUrl }
+        : undefined,
+    };
+  }
+
+  const upgradeCta = {
+    label: t('environment.entitlement.upgradeCta', { defaultValue: 'Upgrade plan' }),
+    url: upgradeUrl,
+  };
+
+  if (code === 'DEV_ENV_PLAN_LOCKED') {
+    return {
+      code,
+      title: t('environment.entitlement.planLockedTitle', {
+        defaultValue: 'Development environments are a paid feature',
+      }),
+      message: t('environment.entitlement.planLockedBody', {
+        plan: planPhrase(t, fields?.plan),
+        defaultValue:
+          'Your {{plan}} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.',
+      }),
+      cta: upgradeCta,
     };
   }
-  // DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT — both resolve via an upgrade CTA.
+
+  // DEV_ENV_LIMIT — a paid org that exhausted its seat-scaled pool. Quote the
+  // usage when the server reported it; the counts carry the same information
+  // the server's own prose did.
+  const used = Number(fields?.current);
+  const limit = Number(fields?.limit);
+  const hasCounts = Number.isFinite(used) && Number.isFinite(limit);
   return {
     code,
-    title:
-      code === 'DEV_ENV_PLAN_LOCKED'
-        ? 'Development environments are a paid feature'
-        : 'Development environment limit reached',
-    message:
-      serverMessage ||
-      (code === 'DEV_ENV_PLAN_LOCKED'
-        ? 'Your free plan includes one production environment. Upgrade to add development environments — build in dev, then publish to production.'
-        : 'Capacity scales with AI seats. Add an AI seat, or archive an unused development environment to free one up.'),
-    cta: { label: 'Upgrade plan', url: upgradeUrl },
+    title: t('environment.entitlement.limitTitle', { defaultValue: 'Development environment limit reached' }),
+    message: hasCounts
+      ? t('environment.entitlement.limitBodyWithCount', {
+          used,
+          limit,
+          defaultValue:
+            'You are using {{used}} of {{limit}} development environments. Capacity scales with AI seats — add an AI seat, or archive an unused development environment to free one up.',
+        })
+      : t('environment.entitlement.limitBody', {
+          defaultValue:
+            'Capacity scales with AI seats. Add an AI seat, or archive an unused development environment to free one up.',
+        }),
+    cta: upgradeCta,
   };
 }
 
@@ -136,12 +213,23 @@ export function decideEnvironmentCta(state: EnvironmentEntitlementsState): Envir
  * "Add environment" but development envs aren't in its plan. Mirrors the copy
  * of the reactive DEV_ENV_PLAN_LOCKED error so both paths read identically.
  */
-export function upgradeDialogSpec(state: EnvironmentEntitlementsState): EntitlementDialogSpec {
-  const planLabel = state.plan && state.plan !== 'free' ? `your ${state.plan} plan` : 'your free plan';
+export function upgradeDialogSpec(
+  state: EnvironmentEntitlementsState,
+  t: EntitlementTranslate = fallbackTranslate,
+): EntitlementDialogSpec {
   return {
     code: 'DEV_ENV_PLAN_LOCKED',
-    title: 'Development environments are a paid feature',
-    message: `${planLabel} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.`,
-    cta: { label: 'Upgrade plan', url: state.upgradeUrl || DEFAULT_UPGRADE_URL },
+    title: t('environment.entitlement.planLockedTitle', {
+      defaultValue: 'Development environments are a paid feature',
+    }),
+    message: t('environment.entitlement.planLockedBody', {
+      plan: planPhrase(t, state.plan),
+      defaultValue:
+        'Your {{plan}} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.',
+    }),
+    cta: {
+      label: t('environment.entitlement.upgradeCta', { defaultValue: 'Upgrade plan' }),
+      url: state.upgradeUrl || DEFAULT_UPGRADE_URL,
+    },
   };
 }
diff --git a/packages/app-shell/src/hooks/__tests__/useConsoleActionRuntime.test.tsx b/packages/app-shell/src/hooks/__tests__/useConsoleActionRuntime.test.tsx
index 1c8cfdca04..3167fca57d 100644
--- a/packages/app-shell/src/hooks/__tests__/useConsoleActionRuntime.test.tsx
+++ b/packages/app-shell/src/hooks/__tests__/useConsoleActionRuntime.test.tsx
@@ -35,6 +35,15 @@ vi.mock('@object-ui/i18n', () => ({
     actionParamOptionLabel: (_o: any, _a: any, _p: any, _v: any, fallback: any) => fallback,
     actionDescription: (_o: any, _a: any, fallback: any) => fallback,
   }),
+  // The entitlement dialog localizes its own copy — stand in with the English
+  // defaults (+ `{{token}}` interpolation) the real `t` would resolve to.
+  useObjectTranslation: () => ({
+    t: (key: string, options?: any) =>
+      String(options?.defaultValue ?? key).replace(
+        /\{\{(\w+)\}\}/g,
+        (_m: string, name: string) => String(options?.[name] ?? ''),
+      ),
+  }),
 }));
 
 // The client modal transport is stubbed for the same reason — importing it for
diff --git a/packages/app-shell/src/hooks/useConsoleActionRuntime.tsx b/packages/app-shell/src/hooks/useConsoleActionRuntime.tsx
index 961669c99c..6c6b8e979a 100644
--- a/packages/app-shell/src/hooks/useConsoleActionRuntime.tsx
+++ b/packages/app-shell/src/hooks/useConsoleActionRuntime.tsx
@@ -25,7 +25,7 @@ import React, { useCallback, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useAuth, createAuthenticatedFetch } from '@object-ui/auth';
 import { usePermissions } from '@object-ui/permissions';
-import { useObjectLabel } from '@object-ui/i18n';
+import { useObjectLabel, useObjectTranslation } from '@object-ui/i18n';
 import { ActionProvider, useGlobalUndo } from '@object-ui/react';
 import { toast } from 'sonner';
 import type {
@@ -126,6 +126,9 @@ export function useConsoleActionRuntime(opts: ConsoleActionRuntimeOptions): Cons
   // when no PermissionProvider is mounted — usePermissions returns []).
   const { systemPermissions } = usePermissions();
   const { fieldLabel, fieldOptionLabel, actionParamText, actionParamOptionLabel, actionDescription, actionResultDialog } = useObjectLabel();
+  // Entitlement 403s render as a dialog, not a toast — its copy is localized
+  // here rather than taken from the server (objectui#2458 / cloud#959).
+  const { t } = useObjectTranslation();
 
   const objectDef = useMemo(
     () => (objectName ? objects?.find((o: any) => o.name === objectName) : undefined),
@@ -343,7 +346,7 @@ export function useConsoleActionRuntime(opts: ConsoleActionRuntimeOptions): Cons
           // Returning success:false WITHOUT an `error` suppresses the runner's
           // error toast (ActionRunner.handlePostExecution); the dialog owns the
           // messaging.
-          const entitlementSpec = entitlementDialogFromError(body);
+          const entitlementSpec = entitlementDialogFromError(body, t);
           if (entitlementSpec) {
             openEntitlementDialog(entitlementSpec);
             return { success: false };
@@ -432,7 +435,7 @@ export function useConsoleActionRuntime(opts: ConsoleActionRuntimeOptions): Cons
     } catch (error) {
       return { success: false, error: (error as Error).message };
     }
-  }, [dataSource, objApiName, authFetch, activeOrganization, refresh, openEntitlementDialog]);
+  }, [dataSource, objApiName, authFetch, activeOrganization, refresh, openEntitlementDialog, t]);
 
   // Flow action handler — POST to /api/v1/automation/{name}/trigger.
   // `context` is the shared ActionRunner context (registered handlers are
diff --git a/packages/i18n/src/locales/ar.ts b/packages/i18n/src/locales/ar.ts
index 28c8dd8cbb..ea38a21fdc 100644
--- a/packages/i18n/src/locales/ar.ts
+++ b/packages/i18n/src/locales/ar.ts
@@ -2569,6 +2569,20 @@ const ar = {
     addEnvironment: "إضافة بيئة",
     setUpProduction: "إعداد بيئة الإنتاج",
     addDevelopment: "إضافة بيئة تطوير",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "لديك بالفعل بيئة الإنتاج الخاصة بك",
+      productionLimitBody: "تتضمّن كل مؤسسة بيئة إنتاج واحدة فقط. أنشئ مؤسسة منفصلة للحصول على بيئة أخرى، أو تواصل معنا بشأن ترتيبات الخطة المؤسسية.",
+      planLockedTitle: "بيئات التطوير ميزة مدفوعة",
+      planLockedBody: "تتضمّن {{plan}} بيئة إنتاج واحدة. قم بالترقية لإضافة بيئات تطوير — أنشئ في بيئة التطوير ثم انشر إلى الإنتاج.",
+      limitTitle: "تم بلوغ الحد الأقصى لبيئات التطوير",
+      limitBody: "تزداد السعة مع مقاعد الذكاء الاصطناعي. أضف مقعدًا، أو أرشف بيئة تطوير غير مستخدمة لتحرير مكان.",
+      limitBodyWithCount: "تستخدم {{used}} من أصل {{limit}} بيئة تطوير. تزداد السعة مع مقاعد الذكاء الاصطناعي — أضف مقعدًا، أو أرشف بيئة تطوير غير مستخدمة.",
+      freePlan: "الخطة المجانية",
+      namedPlan: "خطة {{plan}}",
+      upgradeCta: "ترقية الخطة",
+      contactSalesCta: "تواصل مع المبيعات",
+    },
   },
   cloudConnection: {
     checking: "جارٍ التحقق من الاتصال…",
diff --git a/packages/i18n/src/locales/de.ts b/packages/i18n/src/locales/de.ts
index d32ad619dc..5c1c8e6e01 100644
--- a/packages/i18n/src/locales/de.ts
+++ b/packages/i18n/src/locales/de.ts
@@ -2569,6 +2569,20 @@ const de = {
     addEnvironment: "Umgebung hinzufügen",
     setUpProduction: "Produktionsumgebung einrichten",
     addDevelopment: "Entwicklungsumgebung hinzufügen",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "Sie haben bereits Ihre Produktionsumgebung",
+      productionLimitBody: "Jede Organisation enthält genau eine Produktionsumgebung. Erstellen Sie für eine weitere eine separate Organisation, oder sprechen Sie uns auf eine Enterprise-Vereinbarung an.",
+      planLockedTitle: "Entwicklungsumgebungen sind eine kostenpflichtige Funktion",
+      planLockedBody: "Ihr {{plan}} enthält eine Produktionsumgebung. Führen Sie ein Upgrade durch, um Entwicklungsumgebungen hinzuzufügen — entwickeln Sie in der Entwicklungsumgebung und veröffentlichen Sie dann in der Produktion.",
+      limitTitle: "Limit für Entwicklungsumgebungen erreicht",
+      limitBody: "Die Kapazität wächst mit den KI-Lizenzen. Fügen Sie eine KI-Lizenz hinzu oder archivieren Sie eine ungenutzte Entwicklungsumgebung, um Platz zu schaffen.",
+      limitBodyWithCount: "Sie nutzen {{used}} von {{limit}} Entwicklungsumgebungen. Die Kapazität wächst mit den KI-Lizenzen — fügen Sie eine KI-Lizenz hinzu oder archivieren Sie eine ungenutzte Entwicklungsumgebung.",
+      freePlan: "kostenloser Tarif",
+      namedPlan: "Tarif {{plan}}",
+      upgradeCta: "Tarif upgraden",
+      contactSalesCta: "Vertrieb kontaktieren",
+    },
   },
   cloudConnection: {
     checking: "Verbindung wird geprüft…",
diff --git a/packages/i18n/src/locales/en.ts b/packages/i18n/src/locales/en.ts
index 5a0e78ddcd..2804e65f16 100644
--- a/packages/i18n/src/locales/en.ts
+++ b/packages/i18n/src/locales/en.ts
@@ -2670,6 +2670,25 @@ const en = {
     addEnvironment: 'Add environment',
     setUpProduction: 'Set up your production environment',
     addDevelopment: 'Add development environment',
+    // Plan/capacity dialog (EnvironmentEntitlementDialog). Shown on a paid
+    // conversion path, so it must read in the user's language — cloud#959.
+    entitlement: {
+      productionLimitTitle: 'You already have your production environment',
+      productionLimitBody:
+        'Each organization includes exactly one production environment. Create a separate organization for another, or contact us about an Enterprise arrangement.',
+      planLockedTitle: 'Development environments are a paid feature',
+      planLockedBody:
+        'Your {{plan}} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.',
+      limitTitle: 'Development environment limit reached',
+      limitBody:
+        'Capacity scales with AI seats. Add an AI seat, or archive an unused development environment to free one up.',
+      limitBodyWithCount:
+        'You are using {{used}} of {{limit}} development environments. Capacity scales with AI seats — add an AI seat, or archive an unused development environment to free one up.',
+      freePlan: 'free plan',
+      namedPlan: '{{plan}} plan',
+      upgradeCta: 'Upgrade plan',
+      contactSalesCta: 'Contact sales',
+    },
   },
   cloudConnection: {
     checking: 'Checking connection…',
diff --git a/packages/i18n/src/locales/es.ts b/packages/i18n/src/locales/es.ts
index a3693ebf44..ba8be91a3d 100644
--- a/packages/i18n/src/locales/es.ts
+++ b/packages/i18n/src/locales/es.ts
@@ -2569,6 +2569,20 @@ const es = {
     addEnvironment: "Añadir entorno",
     setUpProduction: "Configure su entorno de producción",
     addDevelopment: "Añadir entorno de desarrollo",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "Ya tiene su entorno de producción",
+      productionLimitBody: "Cada organización incluye exactamente un entorno de producción. Cree una organización aparte para tener otro, o contáctenos para conocer un acuerdo Enterprise.",
+      planLockedTitle: "Los entornos de desarrollo son una función de pago",
+      planLockedBody: "Su {{plan}} incluye un entorno de producción. Mejore su plan para añadir entornos de desarrollo: construya en desarrollo y luego publique en producción.",
+      limitTitle: "Límite de entornos de desarrollo alcanzado",
+      limitBody: "La capacidad crece con los puestos de IA. Añada un puesto de IA, o archive un entorno de desarrollo sin usar para liberar espacio.",
+      limitBodyWithCount: "Está usando {{used}} de {{limit}} entornos de desarrollo. La capacidad crece con los puestos de IA: añada un puesto de IA, o archive un entorno de desarrollo sin usar.",
+      freePlan: "plan gratuito",
+      namedPlan: "plan {{plan}}",
+      upgradeCta: "Mejorar plan",
+      contactSalesCta: "Contactar con ventas",
+    },
   },
   cloudConnection: {
     checking: "Comprobando la conexión…",
diff --git a/packages/i18n/src/locales/fr.ts b/packages/i18n/src/locales/fr.ts
index 47f8297c5d..df88d2644b 100644
--- a/packages/i18n/src/locales/fr.ts
+++ b/packages/i18n/src/locales/fr.ts
@@ -2569,6 +2569,20 @@ const fr = {
     addEnvironment: "Ajouter un environnement",
     setUpProduction: "Configurer votre environnement de production",
     addDevelopment: "Ajouter un environnement de développement",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "Vous avez déjà votre environnement de production",
+      productionLimitBody: "Chaque organisation comprend exactement un environnement de production. Créez une organisation distincte pour en avoir un autre, ou contactez-nous au sujet d'une offre Enterprise.",
+      planLockedTitle: "Les environnements de développement sont une fonctionnalité payante",
+      planLockedBody: "Votre {{plan}} comprend un environnement de production. Passez à une offre supérieure pour ajouter des environnements de développement — développez en dev, puis publiez en production.",
+      limitTitle: "Limite d'environnements de développement atteinte",
+      limitBody: "La capacité évolue avec les sièges IA. Ajoutez un siège IA, ou archivez un environnement de développement inutilisé pour libérer une place.",
+      limitBodyWithCount: "Vous utilisez {{used}} environnements de développement sur {{limit}}. La capacité évolue avec les sièges IA — ajoutez un siège IA, ou archivez un environnement de développement inutilisé.",
+      freePlan: "offre gratuite",
+      namedPlan: "offre {{plan}}",
+      upgradeCta: "Changer d'offre",
+      contactSalesCta: "Contacter le service commercial",
+    },
   },
   cloudConnection: {
     checking: "Vérification de la connexion…",
diff --git a/packages/i18n/src/locales/ja.ts b/packages/i18n/src/locales/ja.ts
index 94b4a6d866..3639e20e8a 100644
--- a/packages/i18n/src/locales/ja.ts
+++ b/packages/i18n/src/locales/ja.ts
@@ -2569,6 +2569,20 @@ const ja = {
     addEnvironment: "環境を追加",
     setUpProduction: "本番環境をセットアップ",
     addDevelopment: "開発環境を追加",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "本番環境はすでに作成済みです",
+      productionLimitBody: "各組織に含まれる本番環境は 1 つだけです。もう 1 つ必要な場合は別の組織を作成するか、エンタープライズ契約についてお問い合わせください。",
+      planLockedTitle: "開発環境は有料機能です",
+      planLockedBody: "{{plan}}には本番環境が 1 つ含まれます。アップグレードすると開発環境を追加できます（開発環境で構築し、本番環境に公開します）。",
+      limitTitle: "開発環境の上限に達しました",
+      limitBody: "上限は AI シート数に応じて増えます。AI シートを追加するか、使用していない開発環境をアーカイブして空きを作ってください。",
+      limitBodyWithCount: "開発環境を {{used}}/{{limit}} 使用中です。上限は AI シート数に応じて増えます。AI シートを追加するか、使用していない開発環境をアーカイブしてください。",
+      freePlan: "無料プラン",
+      namedPlan: "{{plan}} プラン",
+      upgradeCta: "プランをアップグレード",
+      contactSalesCta: "営業に問い合わせる",
+    },
   },
   cloudConnection: {
     checking: "接続を確認しています…",
diff --git a/packages/i18n/src/locales/ko.ts b/packages/i18n/src/locales/ko.ts
index be53557299..a5d598982a 100644
--- a/packages/i18n/src/locales/ko.ts
+++ b/packages/i18n/src/locales/ko.ts
@@ -2569,6 +2569,20 @@ const ko = {
     addEnvironment: "환경 추가",
     setUpProduction: "프로덕션 환경 설정",
     addDevelopment: "개발 환경 추가",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "이미 프로덕션 환경이 있습니다",
+      productionLimitBody: "조직마다 프로덕션 환경은 하나만 포함됩니다. 하나 더 필요하면 별도의 조직을 만들거나 엔터프라이즈 계약에 대해 문의해 주세요.",
+      planLockedTitle: "개발 환경은 유료 기능입니다",
+      planLockedBody: "{{plan}}에는 프로덕션 환경 하나가 포함됩니다. 업그레이드하면 개발 환경을 추가할 수 있습니다 — 개발 환경에서 만들고 프로덕션에 게시하세요.",
+      limitTitle: "개발 환경 한도에 도달했습니다",
+      limitBody: "한도는 AI 좌석 수에 따라 늘어납니다. AI 좌석을 추가하거나 사용하지 않는 개발 환경을 보관하여 자리를 확보하세요.",
+      limitBodyWithCount: "개발 환경을 {{used}}/{{limit}}개 사용 중입니다. 한도는 AI 좌석 수에 따라 늘어납니다 — AI 좌석을 추가하거나 사용하지 않는 개발 환경을 보관하세요.",
+      freePlan: "무료 요금제",
+      namedPlan: "{{plan}} 요금제",
+      upgradeCta: "요금제 업그레이드",
+      contactSalesCta: "영업팀 문의",
+    },
   },
   cloudConnection: {
     checking: "연결을 확인하는 중…",
diff --git a/packages/i18n/src/locales/pt.ts b/packages/i18n/src/locales/pt.ts
index c51b68ff8e..9c7989018a 100644
--- a/packages/i18n/src/locales/pt.ts
+++ b/packages/i18n/src/locales/pt.ts
@@ -2569,6 +2569,20 @@ const pt = {
     addEnvironment: "Adicionar ambiente",
     setUpProduction: "Configure seu ambiente de produção",
     addDevelopment: "Adicionar ambiente de desenvolvimento",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "Você já tem seu ambiente de produção",
+      productionLimitBody: "Cada organização inclui exatamente um ambiente de produção. Crie uma organização separada para ter outro, ou fale conosco sobre um acordo Enterprise.",
+      planLockedTitle: "Ambientes de desenvolvimento são um recurso pago",
+      planLockedBody: "Seu {{plan}} inclui um ambiente de produção. Faça upgrade para adicionar ambientes de desenvolvimento — construa em desenvolvimento e depois publique em produção.",
+      limitTitle: "Limite de ambientes de desenvolvimento atingido",
+      limitBody: "A capacidade cresce com os assentos de IA. Adicione um assento de IA, ou arquive um ambiente de desenvolvimento sem uso para liberar espaço.",
+      limitBodyWithCount: "Você está usando {{used}} de {{limit}} ambientes de desenvolvimento. A capacidade cresce com os assentos de IA — adicione um assento de IA, ou arquive um ambiente de desenvolvimento sem uso.",
+      freePlan: "plano gratuito",
+      namedPlan: "plano {{plan}}",
+      upgradeCta: "Fazer upgrade do plano",
+      contactSalesCta: "Falar com vendas",
+    },
   },
   cloudConnection: {
     checking: "Verificando a conexão…",
diff --git a/packages/i18n/src/locales/ru.ts b/packages/i18n/src/locales/ru.ts
index 719af917aa..cc3ac1c2e8 100644
--- a/packages/i18n/src/locales/ru.ts
+++ b/packages/i18n/src/locales/ru.ts
@@ -2569,6 +2569,20 @@ const ru = {
     addEnvironment: "Добавить окружение",
     setUpProduction: "Настройте продакшн-окружение",
     addDevelopment: "Добавить окружение разработки",
+    // Plan/capacity dialog (EnvironmentEntitlementDialog) — cloud#959.
+    entitlement: {
+      productionLimitTitle: "У вас уже есть продакшн-окружение",
+      productionLimitBody: "Каждая организация включает ровно одно продакшн-окружение. Создайте отдельную организацию для ещё одного или свяжитесь с нами по поводу условий Enterprise.",
+      planLockedTitle: "Окружения разработки — платная возможность",
+      planLockedBody: "{{plan}} включает одно продакшн-окружение. Перейдите на платный тариф, чтобы добавить окружения разработки: создавайте в разработке, затем публикуйте в продакшн.",
+      limitTitle: "Достигнут лимит окружений разработки",
+      limitBody: "Лимит растёт вместе с числом AI-мест. Добавьте AI-место или заархивируйте неиспользуемое окружение разработки, чтобы освободить место.",
+      limitBodyWithCount: "Используется {{used}} из {{limit}} окружений разработки. Лимит растёт вместе с числом AI-мест — добавьте AI-место или заархивируйте неиспользуемое окружение разработки.",
+      freePlan: "Бесплатный тариф",
+      namedPlan: "Тариф {{plan}}",
+      upgradeCta: "Сменить тариф",
+      contactSalesCta: "Связаться с отделом продаж",
+    },
   },
   cloudConnection: {
     checking: "Проверка подключения…",
diff --git a/packages/i18n/src/locales/zh.ts b/packages/i18n/src/locales/zh.ts
index ead66bb5ab..f2a16b052f 100644
--- a/packages/i18n/src/locales/zh.ts
+++ b/packages/i18n/src/locales/zh.ts
@@ -2655,6 +2655,22 @@ const zh = {
     addEnvironment: '新建环境',
     setUpProduction: '创建你的生产环境',
     addDevelopment: '新建开发环境',
+    entitlement: {
+      productionLimitTitle: '你已经有生产环境了',
+      productionLimitBody:
+        '每个组织只包含一个生产环境。如果还需要，可以新建一个组织，或者联系我们了解企业版方案。',
+      planLockedTitle: '开发环境是付费功能',
+      planLockedBody:
+        '{{plan}}包含一个生产环境。升级后即可添加开发环境 —— 先在开发环境里搭建，确认无误再发布到生产环境。',
+      limitTitle: '开发环境数量已达上限',
+      limitBody: '容量随 AI 席位增长。增加一个 AI 席位，或归档一个不再使用的开发环境来腾出名额。',
+      limitBodyWithCount:
+        '开发环境已使用 {{used}}/{{limit}} 个。容量随 AI 席位增长 —— 增加一个 AI 席位，或归档一个不再使用的开发环境来腾出名额。',
+      freePlan: '免费版',
+      namedPlan: '{{plan}} 版',
+      upgradeCta: '升级套餐',
+      contactSalesCta: '联系销售',
+    },
   },
   cloudConnection: {
     checking: '正在检查连接…',

From 8f9718afcefc2b9dfe4dbfc0c535105e14108f9a Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sat, 1 Aug 2026 09:30:56 +0800
Subject: [PATCH 2/3] chore: changeset for entitlement dialog i18n

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../entitlement-dialog-i18n-and-envelope.md   | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 .changeset/entitlement-dialog-i18n-and-envelope.md

diff --git a/.changeset/entitlement-dialog-i18n-and-envelope.md b/.changeset/entitlement-dialog-i18n-and-envelope.md
new file mode 100644
index 0000000000..59c83456b6
--- /dev/null
+++ b/.changeset/entitlement-dialog-i18n-and-envelope.md
@@ -0,0 +1,24 @@
+---
+"@object-ui/app-shell": patch
+"@object-ui/i18n": patch
+---
+
+Localize the environment entitlement dialog and read cloud's nested error envelope.
+
+The free-plan "Development environments are a paid feature" prompt was built from
+English string literals in `entitlements.ts` — including the lowercase `your free
+plan` sentence users reported (cloud#959). Both spec builders now take a translator
+and resolve `environment.entitlement.*`; all ten locale packs carry the strings.
+`entitlements.ts` stays dependency-free: `t` is passed in, not imported, and
+defaults to the English copy with local `{{token}}` interpolation.
+
+The dialog now renders the Console's own copy rather than the server's prose — a
+control plane upgrades independently and only localizes these messages from
+cloud#959 on, so preferring the server string left the reactive path English
+against every older deployment.
+
+Also fixes the reactive dialog not firing at all: cloud#948 moved coded errors into
+a nested envelope (`{ success, error: { code, … } }`), and
+`entitlementDialogFromError` read `code` off the top level — returning `null` for
+every entitlement 403, so the upgrade dialog degraded to a generic red error toast.
+Both shapes are read now.

From b7269f681b46673791634a6223b9815c2e5b5bb0 Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sat, 1 Aug 2026 09:49:03 +0800
Subject: [PATCH 3/3] fix(environment): localize the entitlement dialog's Close
 button
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified in a zh-CN console: title, body and the upgrade CTA all rendered
Chinese while the dismiss button still read "Close". It is the dialog's own
chrome rather than part of the spec, so it resolves `common.close` — a key
every locale pack already carries.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/environment/EnvironmentEntitlementDialog.tsx        | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/app-shell/src/environment/EnvironmentEntitlementDialog.tsx b/packages/app-shell/src/environment/EnvironmentEntitlementDialog.tsx
index 46516db67c..dade77c70f 100644
--- a/packages/app-shell/src/environment/EnvironmentEntitlementDialog.tsx
+++ b/packages/app-shell/src/environment/EnvironmentEntitlementDialog.tsx
@@ -25,6 +25,7 @@ import {
   AlertDialogCancel,
   Button,
 } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
 import type { EntitlementCta, EntitlementDialogSpec } from './entitlements';
 
 export interface EntitlementDialogState {
@@ -78,6 +79,9 @@ interface Props {
 
 export function EnvironmentEntitlementDialog({ state, apiBase, onOpenChange }: Props) {
   const spec = state.spec;
+  // Title / body / CTA labels arrive already localized on the spec; the dismiss
+  // button is the dialog's own chrome, so it resolves its label here.
+  const { t } = useObjectTranslation();
   return (
     <AlertDialog open={state.open} onOpenChange={(open) => { if (!open) onOpenChange(false); }}>
       <AlertDialogContent data-testid="environment-entitlement-dialog">
@@ -86,7 +90,7 @@ export function EnvironmentEntitlementDialog({ state, apiBase, onOpenChange }: P
           <AlertDialogDescription>{spec?.message}</AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
-          <AlertDialogCancel>Close</AlertDialogCancel>
+          <AlertDialogCancel>{t('common.close', { defaultValue: 'Close' })}</AlertDialogCancel>
           {spec?.secondaryCta && (
             <CtaButton cta={spec.secondaryCta} apiBase={apiBase} primary={false} onNavigate={() => onOpenChange(false)} />
           )}