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_SKILL_DIR}/<path>")):

references/formatting-utilities.md - useFormatting hook API reference
references/icu-messageformat.md - ICU plural/select syntax
references/trans-component.md - Trans component for rich text
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_SKILL_DIR}/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"

Load Read("${CLAUDE_SKILL_DIR}/references/icu-messageformat.md") for full syntax.

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 /> }}
/>

Load Read("${CLAUDE_SKILL_DIR}/references/trans-component.md") for patterns.

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_SKILL_DIR}/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
type-safety-validation - Zod schemas for validating translation key structures and locale configs
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, select, pluralization Solves:

Implement pluralization rules
Handle gender-specific translations
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