i18n and Localization Patterns Skill

i18n and Localization Patterns

Overview

This skill provides comprehensive guidance for implementing internationalization in React applications. It ensures ALL user-facing strings, date displays, currency, lists, and time calculations are locale-aware.

When to use this skill:

Adding ANY user-facing text to components
Formatting dates, times, currency, lists, or ordinals
Implementing complex pluralization
Embedding React components in translated text
Supporting RTL languages (Hebrew, Arabic)

Bundled Resources (load with Read("${CLAUDE_PLUGIN_ROOT}/skills/i18n-date-patterns/<path>")):

references/formatting-utilities.md - useFormatting hook API reference
references/ork-delta.md - House decisions and working config that upstream docs do not carry
checklists/i18n-checklist.md - Implementation and review checklist
examples/component-i18n-example.md - Complete component example

Canonical Reference: See docs/i18n-standards.md for the full i18n standards document.

Core Patterns

1. useTranslation Hook (All UI Strings)

Every visible string MUST use the translation function:

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation(['patients', 'common']);
  
  return (
    <div>
      <h1>{t('patients:title')}</h1>
      <button>{t('common:actions.save')}</button>
    </div>
  );
}

2. useFormatting Hook (Locale-Aware Data)

All locale-sensitive formatting MUST use the centralized hook:

import { useFormatting } from '@/hooks';

function PriceDisplay({ amount, items }) {
  const { formatILS, formatList, formatOrdinal } = useFormatting();
  
  return (
    <div>
      <p>Price: {formatILS(amount)}</p>        {/* ₪1,500.00 */}
      <p>Items: {formatList(items)}</p>        {/* "a, b, and c" */}
      <p>Position: {formatOrdinal(3)}</p>      {/* "3rd" */}
    </div>
  );
}

Load Read("${CLAUDE_PLUGIN_ROOT}/skills/i18n-date-patterns/references/formatting-utilities.md") for the complete API.

3. Date Formatting

All dates MUST use the centralized @/lib/dates library:

import { formatDate, formatDateShort, calculateWaitTime } from '@/lib/dates';

const date = formatDate(appointment.date);    // "Jan 6, 2026"
const waitTime = calculateWaitTime('09:30');  // "15 min"

4. ICU MessageFormat (Complex Plurals)

Use ICU syntax in translation files for pluralization:

{
  "patients": "{count, plural, =0 {No patients} one {# patient} other {# patients}}"
}

t('patients', { count: 5 })  // → "5 patients"

House rules for plurals live in rules/i18n-icu-plurals.md. For the full ICU grammar see the upstream table below.

5. Trans Component (Rich Text)

For embedded React components in translated text:

import { Trans } from 'react-i18next';

<Trans
  i18nKey="richText.welcome"
  values={{ name: userName }}
  components={{ strong: <strong /> }}
/>

House rules for <Trans> live in rules/i18n-trans-component.md; the plural-plus-rich-text ordering constraint lives in references/ork-delta.md. For the full component API see the upstream table below.

Upstream coverage (do not restate)

These topics are owned by first-party docs. Read them there instead of re-deriving them here.

| Topic | First-party source | House subset kept here | |-------|--------------------|------------------------| | ICU plural, select, selectordinal, offset and nested message grammar | https://formatjs.github.io/docs/core-concepts/icu-syntax/ and https://unicode-org.github.io/icu/userguide/format_parse/messages/ | rules/i18n-icu-plurals.md keeps the house subset in full: no ternary pluralization, the mandatory other arm, =0 for zero states, Hebrew dual and Arabic categories | | Which plural categories a given locale actually has | https://cldr.unicode.org/index/cldr-spec/plural-rules | none, read upstream | | ICU number skeletons inside a message (::currency/ILS) | https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html | references/ork-delta.md keeps only the ILS skeleton decision | | In-message date and time forms ({date, date, medium}) and offset: plurals | https://unicode-org.github.io/icu/userguide/format_parse/messages/ | nothing; fetch it upstream | | <Trans> API: named vs indexed tags, self-closing tags, TransProps typing | https://react.i18next.com/latest/trans-component | rules/i18n-trans-component.md keeps the house subset in full: never split a sentence across t() calls, never dangerouslySetInnerHTML, prefer named tags over indexed | | Wiring the ICU parser into i18next | https://github.com/i18next/i18next-icu | references/ork-delta.md keeps the decision and why suffix keys are not enough | | Intl.ListFormat primitive behind useFormatting | https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat | references/formatting-utilities.md keeps the house hook API | | Intl.NumberFormat primitive behind useFormatting | https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat | references/formatting-utilities.md keeps the house hook API |

Translation File Structure

frontend/src/i18n/locales/
├── en/
│   ├── common.json      # Shared: actions, status, time
│   ├── patients.json    # Patient-related strings
│   ├── dashboard.json   # Dashboard strings
│   ├── owner.json       # Owner portal strings
│   └── invoices.json    # Invoice strings
└── he/
    └── (same structure)

Anti-Patterns (FORBIDDEN)

// ❌ NEVER hardcode strings
<h1>מטופלים</h1>                    // Use t('patients:title')
<button>Save</button>               // Use t('common:actions.save')

// ❌ NEVER use .join() for lists
items.join(', ')                    // Use formatList(items)

// ❌ NEVER hardcode currency
"₪" + price                         // Use formatILS(price)

// ❌ NEVER use new Date() for formatting
new Date().toLocaleDateString()     // Use formatDate() from @/lib/dates

// ❌ NEVER use inline plural logic
count === 1 ? 'item' : 'items'      // Use ICU MessageFormat

// ❌ NEVER leave console.log in production
console.log('debug')                // Remove before commit

// ❌ NEVER use dangerouslySetInnerHTML for i18n
dangerouslySetInnerHTML             // Use <Trans> component

Quick Reference

| Need | Solution | |------|----------| | UI text | t('namespace:key') from useTranslation | | Currency | formatILS(amount) from useFormatting | | Lists | formatList(items) from useFormatting | | Ordinals | formatOrdinal(n) from useFormatting | | Dates | formatDate(date) from @/lib/dates | | Plurals | ICU MessageFormat in translation files | | Rich text | <Trans> component | | RTL check | isRTL from useFormatting |

Checklist

Load Read("${CLAUDE_PLUGIN_ROOT}/skills/i18n-date-patterns/checklists/i18n-checklist.md") for complete implementation and review checklists.

Integration with Agents

Frontend UI Developer

Uses all i18n patterns for components
References this skill for formatting
Ensures no hardcoded strings

Code Quality Reviewer

Checks for anti-patterns (.join(), console.log, etc.)
Validates translation key coverage
Ensures RTL compatibility

Skill Version: 1.2.0 Last Updated: 2026-01-06 Maintained by: Yonatan Gross

Related Skills

ork:testing-e2e - E2E testing patterns including accessibility testing for i18n
ork:react-server-components-framework - Server-side locale detection and RSC i18n patterns
ork:accessibility - RTL-aware focus management for bidirectional UI navigation

Key Decisions

| Decision | Choice | Rationale | |----------|--------|-----------| | Translation Library | react-i18next | React-native hooks, namespace support, ICU format | | Date Library | dayjs | Lightweight, locale plugins, immutable API | | Message Format | ICU MessageFormat | Industry standard, complex plural/select support | | Locale Storage | Per-namespace JSON | Code-splitting, lazy loading per feature | | RTL Detection | CSS logical properties | Native browser support, no JS overhead |

Capability Details

translation-hooks

Keywords: useTranslation, t(), i18n hook, translation hook Solves:

Translate UI strings with useTranslation
Implement namespaced translations
Handle missing translation keys

formatting-hooks

Keywords: useFormatting, formatCurrency, formatList, formatOrdinal Solves:

Format currency values with locale
Format lists with proper separators
Handle ordinal numbers across locales

icu-messageformat

Keywords: ICU, MessageFormat, plural, pluralization Solves:

Apply the house Hebrew plural-category decision (see references/ork-delta.md)
ICU select, gender forms and nested message grammar are routed upstream (see Upstream coverage)
Build complex message patterns

date-time-formatting

Keywords: date format, time format, dayjs, locale date, calendar Solves:

Format dates with dayjs and locale
Handle timezone-aware formatting
Build calendar components with i18n

rtl-support

Keywords: RTL, right-to-left, hebrew, arabic, direction Solves:

Support RTL languages like Hebrew
Handle bidirectional text
Configure RTL-aware layouts

trans-component

Keywords: Trans, rich text, embedded JSX, interpolation Solves:

Embed React components in translations
Handle rich text formatting
Implement safe HTML in translations

Agent Skills: i18n and Localization Patterns

Install this agent skill to your local

Skill Files