Internationalization = design the system so localization is possible and safe.
Localization        = provide locale-specific language, data, formatting, assets, and behavior.

Feature: Case Hearing Scheduler
Locales: en-US, en-GB, id-ID, ar-EG, ja-JP
Locale source: URL segment, persisted preference fallback, Accept-Language initial hint
Text: all user-visible strings externalized with stable message IDs
Pluralization: ICU-style plural messages for count-dependent text
Date/time: hearing instant stored in UTC; rendered with case jurisdiction timezone
Local dates: filing deadline modeled as calendar date, not midnight UTC instant
Formats: Intl.DateTimeFormat, Intl.NumberFormat, Intl.RelativeTimeFormat
Direction: supports dir="rtl" at document/root boundary; logical CSS used
Testing: pseudo-locale, RTL smoke, DST transition, timezone matrix, screenshot diff
Risk: legal notices require jurisdiction-approved translations; block release without legal QA

Language: en, id, ar, ja
Region: US, GB, ID, EG, JP
Script: Latn, Arab, Hans, Hant
Calendar: gregory, buddhist, japanese, islamic
Numbering system: latn, arab, hanidec
Timezone: Asia/Jakarta, Europe/London, America/New_York
Currency: USD, GBP, IDR, JPY
Direction: ltr, rtl

User speaks English -> show English strings -> done

User locale influences:
- language of messages
- date and time format
- numbering system
- currency display
- plural rules
- collation/search/sort behavior
- list formatting
- text direction
- fallback chain
- legal/compliance content
- route/content variant

1. What locale is active?
2. Who owns locale selection?
3. How is locale represented in URL and app state?
4. What fallback chain is allowed?
5. Which values are formatted on client vs server?
6. Which strings are legal/compliance approved?
7. How do we test locale correctness before release?

const amount = 1234567.89;

new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
}).format(amount);
// "$1,234,567.89"

new Intl.NumberFormat("id-ID", {
  style: "currency",
  currency: "IDR",
}).format(amount);
// "Rp1.234.567,89" depending on runtime locale data

const instant = new Date("2026-06-27T05:30:00Z");

new Intl.DateTimeFormat("en-GB", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: "Europe/London",
}).format(instant);

new Intl.DateTimeFormat("id-ID", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: "Asia/Jakarta",
}).format(instant);

The instant is the same.
The representation changes by locale and timezone.

type DateFormatterKey = `${string}|${string}|${string}`;

const dateFormatterCache = new Map<DateFormatterKey, Intl.DateTimeFormat>();

function getDateFormatter(locale: string, timeZone: string, dateStyle: Intl.DateTimeFormatOptions["dateStyle"]) {
  const key: DateFormatterKey = `${locale}|${timeZone}|${dateStyle ?? "default"}`;

  let formatter = dateFormatterCache.get(key);

  if (!formatter) {
    formatter = new Intl.DateTimeFormat(locale, {
      dateStyle,
      timeZone,
    });
    dateFormatterCache.set(key, formatter);
  }

  return formatter;
}

Never build user-facing sentences by concatenating translated fragments.

const text = t("youHave") + " " + count + " " + t("newMessages");

inbox.unreadMessageCount =
  one: "You have {count} new message"
  other: "You have {count} new messages"

{count, plural,
  =0 {You have no new messages}
  one {You have one new message}
  other {You have # new messages}
}

submit

- Submit what?
- Button or heading?
- Formal or casual?
- Reusable or context-specific?
- Does change in English require new translation?

case.assignment.form.submitButton.label

{
  "id": "case.assignment.form.assignee.label",
  "defaultMessage": "Assignee",
  "description": "Label for the user/person field in the case assignment form.",
  "screen": "Case Assignment Dialog",
  "placeholders": {},
  "notes": "Noun. Do not translate as action verb."
}

{
  "id": "case.enforcement.notice.legalDisclaimer",
  "defaultMessage": "This notice does not constitute final agency action.",
  "description": "Legal disclaimer shown before enforcement notice submission.",
  "requiresLegalApproval": true,
  "jurisdictions": ["US-FED", "ID-OJK"],
  "version": "2026-06-27"
}

const label = `${count} item${count === 1 ? "" : "s"}`;

const rules = new Intl.PluralRules("en-US");

const messages = {
  one: "1 item",
  other: "{count} items",
};

function formatItemCount(count: number) {
  const category = rules.select(count);
  const template = messages[category as "one" | "other"] ?? messages.other;

  return template.replace("{count}", String(count));
}

zero
one
two
few
many
other

<div dangerouslySetInnerHTML={{ __html: t("termsHtml") }} />

<Trans
  id="signup.terms.notice"
  components={{
    termsLink: <a href="/terms" />,
    privacyLink: <a href="/privacy" />,
  }}
/>

By continuing, you agree to our <termsLink>Terms</termsLink> and <privacyLink>Privacy Policy</privacyLink>.

- URL locale segment: /id/cases
- User profile preference
- Tenant default
- Browser Accept-Language
- Case/document language
- Jurisdiction requirement
- Product default

const supportedLocales = ["en-US", "en-GB", "id-ID", "ar-EG", "ja-JP"] as const;
type SupportedLocale = (typeof supportedLocales)[number];

function isSupportedLocale(value: string): value is SupportedLocale {
  return (supportedLocales as readonly string[]).includes(value);
}

function resolveLocale(input: {
  urlLocale?: string;
  userLocale?: string;
  tenantLocale?: string;
  acceptedLocales?: string[];
  defaultLocale: SupportedLocale;
}): SupportedLocale {
  const candidates = [
    input.urlLocale,
    input.userLocale,
    input.tenantLocale,
    ...(input.acceptedLocales ?? []),
    input.defaultLocale,
  ];

  for (const candidate of candidates) {
    if (candidate && isSupportedLocale(candidate)) {
      return candidate;
    }
  }

  return input.defaultLocale;
}

pt-BR -> pt -> default
zh-Hant-TW -> zh-Hant -> zh -> default

/en-US/cases/123
/id-ID/cases/123
/ar-EG/cases/123

- shareable localized links
- stable SSR behavior
- SEO and metadata alignment
- cache partitioning by locale
- easier debugging
- deterministic route loading

- first render language flicker
- wrong SSR content
- cache contamination
- non-shareable localized pages
- analytics ambiguity
- search engines see only default language

Do not use one representation for all time concepts.

2026-06-27T05:30:00Z

const hearingStart = new Date("2026-06-27T05:30:00Z");

function formatHearingStart(locale: string, timeZone: string) {
  return new Intl.DateTimeFormat(locale, {
    dateStyle: "full",
    timeStyle: "short",
    timeZone,
  }).format(hearingStart);
}

2026-06-27

2026-06-27T00:00:00Z

2026-06-27T00:00:00Z
Asia/Jakarta -> 2026-06-27 07:00
America/Los_Angeles -> 2026-06-26 17:00

America/New_York can be -05:00 or -04:00 depending on date.
Europe/London can be +00:00 or +01:00 depending on date.

{
  "eventId": "hearing-123",
  "localDate": "2026-11-02",
  "localTime": "09:00",
  "timeZone": "America/New_York"
}

new Date("2026-06-27")

type InstantIsoString = string & { readonly __brand: "InstantIsoString" };
type LocalDateString = string & { readonly __brand: "LocalDateString" };
type TimeZoneId = string & { readonly __brand: "TimeZoneId" };

type Hearing = {
  id: string;
  startInstant: InstantIsoString;
  displayTimeZone: TimeZoneId;
};

type FilingDeadline = {
  id: string;
  dueDate: LocalDateString;
  jurisdictionTimeZone: TimeZoneId;
};

function parseLocalDate(value: unknown): LocalDateString {
  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
    throw new Error("Invalid local date");
  }

  return value as LocalDateString;
}

Model time concepts explicitly.
Do not let Date become your domain model.

Temporal.Instant
Temporal.PlainDate
Temporal.PlainTime
Temporal.ZonedDateTime
Temporal.Duration

const daysAgo = Math.floor((Date.now() - createdAt.getTime()) / 86_400_000);
return `${daysAgo} days ago`;

- English-only
- pluralization bug
- calendar/daylight-saving edge cases
- wrong thresholds
- stale display if not updated

const rtf = new Intl.RelativeTimeFormat("en-US", {
  numeric: "auto",
});

rtf.format(-1, "day");
// "yesterday"

names.sort();

const collator = new Intl.Collator("id-ID", {
  sensitivity: "base",
  usage: "sort",
});

names.sort(collator.compare);

const searchCollator = new Intl.Collator("tr-TR", {
  sensitivity: "base",
  usage: "search",
});

"💥".length;
// 2

"🇮🇩".length;
// 4

value.length
value.slice(0, 10)
value[0]

function countGraphemes(locale: string, input: string): number {
  const segmenter = new Intl.Segmenter(locale, {
    granularity: "grapheme",
  });

  return [...segmenter.segment(input)].length;
}

é as single composed code point
é as e + combining acute accent

const normalized = input.normalize("NFC");

Document direction: <html dir="rtl">
Component layout: logical CSS properties
Text fragments: dir="auto" where content language is unknown
Icons: mirror only when meaning is directional
Animations: review intent
Charts/maps: often not mirrored

.card {
  padding-inline-start: 1rem;
  padding-inline-end: 1rem;
  margin-block-end: 1rem;
  border-inline-start: 4px solid currentColor;
}

.card {
  padding-left: 1rem;
  margin-bottom: 1rem;
  border-left: 4px solid currentColor;
}

type Direction = "ltr" | "rtl";

function AppShell({ direction }: { direction: Direction }) {
  return (
    <div dir={direction} data-direction={direction}>
      {/* application */}
    </div>
  );
}

- decimal separators
- grouping separators
- currency symbols
- localized digits
- calendar-specific dates
- phone numbers
- addresses
- names
- postal codes

ISO date picker value: YYYY-MM-DD
Backend date value: YYYY-MM-DD
Displayed date: locale formatted

- text input with locale-aware parser
- strict canonical model
- formatted display on blur
- unformatted editing mode on focus
- server-side validation

type MoneyInputValue = {
  canonicalMinorUnits: number;
  currency: string;
  displayValue: string;
  locale: string;
};

Never assume formatted output can be safely parsed back by reversing string replacements.

- everyone has first name and last name
- names fit ASCII
- postal code is numeric
- phone number has fixed national format
- address line order is universal
- province/state exists everywhere

Display name: what the user wants shown
Legal name: structured only if required by legal process
Sortable name: locale/jurisdiction-specific if needed

English: Save case
Pseudo: [!! Šååvvêê çååšêê !!]

- longer text expansion
- missing externalization
- clipping/truncation
- hardcoded strings
- layout rigidity
- bidirectional issues
- placeholder mismatch

/en-XA/cases -> expanded accented pseudo text
/ar-XB/cases -> pseudo RTL mode

- localized URLs
- canonical URLs
- alternate language links
- localized metadata
- server-rendered content
- sitemap per locale
- locale-specific structured data
- correct document lang attribute

<html lang="id-ID" dir="ltr">

Server renders date in en-US timezone UTC.
Client hydrates in id-ID timezone Asia/Jakarta.
Text differs.
Hydration warning appears.

function HearingTime({ instant, locale, timeZone }: {
  instant: string;
  locale: string;
  timeZone: string;
}) {
  const formatted = new Intl.DateTimeFormat(locale, {
    dateStyle: "medium",
    timeStyle: "short",
    timeZone,
  }).format(new Date(instant));

  return <time dateTime={instant}>{formatted}</time>;
}

{
  "status": "PENDING_REVIEW"
}

const statusMessageIdByCode = {
  PENDING_REVIEW: "case.status.pendingReview",
  APPROVED: "case.status.approved",
  REJECTED: "case.status.rejected",
} as const;

- locale
- timezone policy if formatted server-side
- tenant/jurisdiction
- auth/permission where relevant
- content version

User A requests /cases in en-US.
CDN caches rendered page.
User B requests /cases in id-ID.
CDN returns English page.

- locale in path: /en-US/cases and /id-ID/cases
- Vary header policy where appropriate
- per-locale cache key
- avoid caching personalized localized pages publicly

type QueryKey = readonly [
  "case",
  string,
  {
    locale: string;
    tenantId: string;
  }
];

function DeleteButton() {
  return <button>Delete</button>;
}

type DeleteButtonProps = {
  label: string;
  onDelete: () => void;
};

function DeleteButton({ label, onDelete }: DeleteButtonProps) {
  return <button onClick={onDelete}>{label}</button>;
}

function DeleteCaseButton({ caseId }: { caseId: string }) {
  const t = useTranslations("case.actions");

  return (
    <button onClick={() => deleteCase(caseId)}>
      {t("deleteCase")}
    </button>
  );
}

en-US  -> baseline English, US date/number behavior
en-GB  -> English language, different date conventions
id-ID  -> Indonesian locale, decimal/currency behavior
ar-EG  -> RTL and Arabic plural/number behavior
ja-JP  -> non-Latin assumptions, compact labels, calendar/name behavior
pseudo -> text expansion and missing externalization

UTC
Asia/Jakarta
America/New_York
Europe/London
Pacific/Auckland

import { test, expect } from "@playwright/test";

test.use({
  locale: "id-ID",
  timezoneId: "Asia/Jakarta",
});

test("renders hearing time in Indonesian locale", async ({ page }) => {
  await page.goto("/id-ID/cases/123");
  await expect(page.getByTestId("hearing-time")).toContainText(/2026|27/);
});

- active locale
- fallback locale used
- missing translation key
- placeholder mismatch
- formatting error
- timezone selected
- user timezone vs jurisdiction timezone mismatch
- RTL mode
- catalog version
- route locale

{
  "event": "i18n.missing_message",
  "messageId": "case.assignment.form.submitButton.label",
  "locale": "id-ID",
  "fallbackLocale": "en-US",
  "route": "/id-ID/cases/123/assign",
  "catalogVersion": "2026.06.27"
}

[ ] All user-visible strings externalized
[ ] No string concatenation for translated sentences
[ ] Plurals handled with locale rules
[ ] Dates/times use explicit locale/timezone
[ ] Local date and instant are modeled separately
[ ] Number/currency/unit formatting uses Intl or approved formatter
[ ] URL/metadata locale strategy documented
[ ] RTL mode tested for supported locales
[ ] Pseudo-localization run for critical flows
[ ] Missing translation behavior defined
[ ] Translation keys include context/descriptions
[ ] Legal/compliance strings have approval path
[ ] Screenshots/context available to translators
[ ] CI validates placeholder consistency
[ ] Observability tracks missing/fallback messages

1. Does this introduce user-facing text?
2. Are messages full sentences with context?
3. Does count-dependent text use pluralization?
4. Does this display date/time/number/currency?
5. Is timezone explicit?
6. Is this value an instant, date-only, duration, or recurrence?
7. Does layout handle longer translations?
8. Does RTL change anything?
9. Are translations loaded before render?
10. Could localized API response leak across cache boundaries?

- investigator in Jakarta views case created in London
- hearing scheduled in jurisdiction timezone
- filing deadline is a local legal date
- audit log must be exact and forensic
- legal notice must use approved localized copy
- attachments may contain multilingual titles
- dashboard aggregates counts by status

type CaseSchedule = {
  hearingStartInstant: InstantIsoString;
  hearingTimeZone: TimeZoneId;
  filingDeadlineDate: LocalDateString;
  filingDeadlineJurisdiction: string;
};

type AuditEvent = {
  occurredAt: InstantIsoString;
  actorId: string;
  actionCode: string;
};

type LocalizedLegalNotice = {
  noticeCode: string;
  locale: SupportedLocale;
  approvedVersion: string;
  body: string;
};

Hearing time:
  show in jurisdiction timezone
  optionally show user's timezone as secondary

Filing deadline:
  show date only
  show jurisdiction/timezone note if relevant

Audit log:
  show exact timestamp with timezone
  include machine-readable instant in <time dateTime="...">

Legal notice:
  use approved locale version
  block fallback if no approved translation exists

- manual date formatting
- manual currency formatting
- manual pluralization
- hardcoded English labels

before/after diff
locale matrix screenshot
notes on edge cases discovered

instant
local date
local time
zoned date-time
duration
calendar period
recurrence

time model table
storage representation
rendering policy
test cases

layout
icons
keyboard behavior
focus order
scrollbars
charts
tables
forms
modals

RTL bug list
root cause category
fix proposal
screenshots

message extraction
key naming
translator context
screenshot handoff
placeholder validation
legal review
catalog versioning
fallback policy
release gate