fix(i18n): drop try/catch-around-hook in createSafeTranslation / useSafeTranslate (#2605)

Last known rules-of-hooks violation of the #2595/#2596 class — the factory closure escaped static lint but carried the same hook-order desync risk. useObjectTranslation is provider-safe; the real fallbacks (testKey probe / per-key detection) are unchanged and now test-locked, and the fallback t is a stable per-factory reference so downstream memo deps stop invalidating in the no-translations case. vitest i18n+plugin-detail+fields 656 ✓.

Author: os-zhuang

.changeset/i18n-safe-translation-hooks.md

@@ -0,0 +1,14 @@
+---
+'@object-ui/i18n': patch
+---
+
+fix(i18n): `createSafeTranslation` / `useSafeTranslate` no longer wrap the
+translation hook in try/catch — the last known rules-of-hooks violation of
+the class fixed in objectui#2595/#2596 (a throw after the hook ran would
+desync hook order on the next render; the factory closure just escaped the
+static lint). `useObjectTranslation` is provider-safe, and the actual
+fallback behavior is unchanged: the testKey probe (createSafeTranslation)
+and per-key `t(key) === key` detection (useSafeTranslate) still return the
+English defaults when translations aren't configured. The fallback `t` is
+now a stable per-factory reference, so downstream memo deps stop
+invalidating every render in the no-translations case.

packages/i18n/src/__tests__/useSafeTranslation.test.tsx

@@ -0,0 +1,41 @@
+/**
+ * Locks the fallback semantics of the safe-translation hooks AFTER the
+ * try/catch-around-hook removal (rules-of-hooks, objectui#2595/#2596 class):
+ * with no I18nProvider mounted, consumers must still get English defaults —
+ * via the testKey probe / per-key detection, not via a caught throw.
+ */
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { createSafeTranslation, useSafeTranslate } from '../useSafeTranslation';
+
+const DEFAULTS = {
+  'detail.test': 'Test Anchor',
+  'detail.greeting': 'Hello {{name}}',
+};
+
+describe('createSafeTranslation (no I18nProvider)', () => {
+  it('falls back to defaults with placeholder interpolation', () => {
+    const useT = createSafeTranslation(DEFAULTS, 'detail.test');
+    const { result } = renderHook(() => useT());
+    expect(result.current.t('detail.greeting', { name: 'Ada' })).toBe('Hello Ada');
+    expect(result.current.t('detail.test')).toBe('Test Anchor');
+    // Unknown keys pass through as-is (historical contract).
+    expect(result.current.t('detail.missing')).toBe('detail.missing');
+  });
+
+  it('returns a STABLE fallback t across renders (memo-dep friendly)', () => {
+    const useT = createSafeTranslation(DEFAULTS, 'detail.test');
+    const { result, rerender } = renderHook(() => useT());
+    const first = result.current.t;
+    rerender();
+    expect(result.current.t).toBe(first);
+  });
+});
+
+describe('useSafeTranslate (no I18nProvider)', () => {
+  it('returns the call-site fallback and supports key-chain form', () => {
+    const { result } = renderHook(() => useSafeTranslate());
+    expect(result.current('common.total', 'Total')).toBe('Total');
+    expect(result.current(['common.total', 'dashboard.total'], 'Total')).toBe('Total');
+  });
+});

packages/i18n/src/useSafeTranslation.ts

@@ -14,37 +14,33 @@ export function createSafeTranslation(
   defaults: Record<string, string>,
   testKey: string,
 ) {
-  return function useSafeTranslation() {
-    try {
-      const result = useObjectTranslation();
-      const testValue = result.t(testKey);
-      if (testValue === testKey) {
-        return {
-          t: (key: string, options?: Record<string, unknown>) => {
-            let value = defaults[key] || key;
-            if (options) {
-              for (const [k, v] of Object.entries(options)) {
-                value = value.replace(`{{${k}}}`, String(v));
-              }
-            }
-            return value;
-          },
-        };
+  // Factory-level fallback: one stable reference per defaults map, so
+  // downstream useMemo/useCallback deps don't invalidate every render in
+  // the no-translations case.
+  const fallbackT = (key: string, options?: Record<string, unknown>) => {
+    let value = defaults[key] || key;
+    if (options) {
+      for (const [k, v] of Object.entries(options)) {
+        value = value.replace(`{{${k}}}`, String(v));
       }
-      return { t: result.t };
-    } catch {
-      return {
-        t: (key: string, options?: Record<string, unknown>) => {
-          let value = defaults[key] || key;
-          if (options) {
-            for (const [k, v] of Object.entries(options)) {
-              value = value.replace(`{{${k}}}`, String(v));
-            }
-          }
-          return value;
-        },
-      };
     }
+    return value;
+  };
+
+  return function useSafeTranslation() {
+    // No try/catch around the hook: useObjectTranslation is provider-safe
+    // (optional context read + react-i18next global-instance fallback), and
+    // wrapping a hook call in try/catch violates rules-of-hooks — a throw
+    // after the hook ran would desync hook order on the next render (same
+    // fix as objectui#2595/#2596; this factory closure just escaped the
+    // static lint). The testKey probe below carries the actual
+    // "translations not configured" fallback.
+    const result = useObjectTranslation();
+    const testValue = result.t(testKey);
+    if (testValue === testKey) {
+      return { t: fallbackT };
+    }
+    return { t: result.t };
   };
 }
 
@@ -61,14 +57,11 @@ export function createSafeTranslation(
  * `tt(['common.total', 'dashboard.total'], 'Total')`.
  */
 export function useSafeTranslate(): (keyOrKeys: string | string[], fallback: string) => string {
-  let t: ((key: string) => string) | undefined;
-  try {
-    t = useObjectTranslation().t;
-  } catch {
-    t = undefined;
-  }
+  // Unconditional hook call (rules-of-hooks) — the hook is provider-safe,
+  // and a missing translation surfaces as `t(key) === key` per key below,
+  // never as a throw. Same fix as createSafeTranslation above.
+  const { t } = useObjectTranslation();
   return (keyOrKeys, fallback) => {
-    if (!t) return fallback;
     const keys = Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys];
     for (const key of keys) {
       const v = t(key);