Translation

Translation runs on two tiers: dictionary JSON files for static UI (parity-enforced across ar/en by a CI test) and the batched localize() engine for dynamic database content via a three-tier cache (in-memory LRU → Translation table → provider chain). The provider chain (engine.ts) tries Google Translate first and falls back to a Groq LLM (free tier) — each behind a circuit breaker — so a dead provider (as happened 2026-06-14 → 2026-07-12 when the Google quota died and silently killed all dynamic translation) can never again take translations down platform-wide. A registry-driven sweep (pnpm i18n:backfill + the daily /api/cron/translation-sweep) backfills and self-heals the cache for existing content, person names, new schools, and bulk imports. Drift can no longer ship: en/ar key parity, untranslated placeholders, hardcoded-string counts, and RTL physical classes are all gated in pnpm test and CI. The remaining work is the hardcoded-string sweep tracked by the ratchet baselines — run npx tsx scripts/i18n-hardcoded-ratchet.ts --by-dir for the live count.

Architecture

Infrastructure files

Coverage gaps

Cards and Lab sidebar items also lack dictionary keys. Run /i18n-check for the current per-area count.

Priority order

1. Button text — keys already exist in dictionary.common.*.
2. Wizard group labels — high visibility.
3. Form labels — largest UX impact.
4. Select options — needs config factory.
5. Validation — needs schema factory refactor.
6. Server action errors — needs error code pattern.
7. Empty states.
8. Toast messages — needs dictionary plumbing.
9. getText expansion to remaining content files.

Form pattern

Pass dictionary slices into client forms.

Copy// content.tsx
const dictionary = await getDictionary(lang)
return <StudentForm dictionary={dictionary.school.students} />
 
// form.tsx
<FormLabel>{dictionary.form.name}</FormLabel>
<Input placeholder={dictionary.form.namePlaceholder} {...field} />

Select pattern

Export option factories, not static arrays.

Copyexport const getGenderOptions = (d: Dictionary["school"]) => [
  { value: "male", label: d.students.gender.male },
  { value: "female", label: d.students.gender.female },
]

Validation pattern

Schemas become factories that take a ValidationHelper. Already shipping in onboarding and auth.

Copyimport { getValidationMessages } from "@/components/internationalization/helpers"
 
export const createStudentSchema = (
  v: ReturnType<typeof getValidationMessages>
) =>
  z.object({
    name: z.string().min(1, v.required()),
    email: z.string().email(v.email()),
    phone: z.string().min(10, v.minLength(10)),
  })

Blocker: validation files across the dashboard need to convert from module-level schemas to factories.

Toast pattern

Copyimport { getToastMessages } from "@/components/internationalization/helpers"
 
const t = useMemo(() => getToastMessages(dictionary), [dictionary])
 
if (result.success) toast.success(t.success.student.created())
else toast.error(t.error.student.createFailed())

Blocker: toasts run client-side; ToastHelper needs dictionary in scope.

Server action error pattern

Return error codes; translate on the client.

Copy// actions.ts
if (!session?.user) return { success: false, errorCode: "NOT_AUTHENTICATED" }
if (!schoolId) return { success: false, errorCode: "MISSING_SCHOOL_CONTEXT" }
 
// form.tsx
const ERROR_MAP: Record<string, string> = {
  NOT_AUTHENTICATED: dictionary.messages.errors.auth.notAuthenticated,
  MISSING_SCHOOL_CONTEXT:
    dictionary.messages.errors.tenant.missingSchoolContext,
}
toast.error(
  ERROR_MAP[result.errorCode] ?? dictionary.messages.errors.server.internalError
)

Per-area status

All 21 areas (Dashboard, Students, Teachers, Classes, Subjects, Announcements, Events, Assignments, Parents, Grades, Classrooms, Exams, Finance, Attendance, Timetable, Profile, Settings, Notifications, Admission, School Config, Reports) use the dictionary for table headers and sidebar but are partial on getText, forms, selects, validation, toasts, and actions. Students/Teachers/Classes/Subjects/Announcements/Parents/Classrooms/Exams/Attendance/Profile use getText for some surfaces; the rest are display-text-pending.

Wizard routes (/students/add, /teachers/add, /exams/manage, /exams/qbank, /finance/invoice) have hardcoded forms, selects, validation, toasts, and action errors.

Guardrails

See also

• Translation Guide — deep guide to DB-content translation (cache, name helpers, trade-offs, tooling)
• Internationalization — architecture reference
• Multi-Tenancy
• Pattern
• Validation
• Form