SKILL.md

i18n & Localization

Internationalization (i18n) and Localization (L10n) best practices.

1. Core Concepts

Term	Meaning
i18n	Internationalization - making app translatable
L10n	Localization - actual translations
Locale	Language + Region (en-US, tr-TR)
RTL	Right-to-left languages (Arabic, Hebrew)

2. When to Use i18n

Project Type	i18n Needed?
Public web app	✅ Yes
SaaS product	✅ Yes
Internal tool	⚠️ Maybe
Single-region app	⚠️ Consider future
Personal project	❌ Optional

3. Implementation Patterns

React (react-i18next)

import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome.title')}</h1>;
}

Next.js (next-intl)

import { useTranslations } from 'next-intl';

export default function Page() {
  const t = useTranslations('Home');
  return <h1>{t('title')}</h1>;
}

Python (gettext)

from gettext import gettext as _

print(_("Welcome to our app"))

4. File Structure

locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── errors.json
└── ar/          # RTL
    └── ...

5. Best Practices

DO ✅

Use translation keys, not raw text
Namespace translations by feature
Support pluralization
Handle date/number formats per locale
Plan for RTL from the start
Use ICU message format for complex strings

DON'T ❌

Hardcode strings in components
Concatenate translated strings
Assume text length (German is 30% longer)
Forget about RTL layout
Mix languages in same file

6. Common Issues

Issue	Solution
Missing translation	Fallback to default language
Hardcoded strings	Use linter/checker script
Date format	Use Intl.DateTimeFormat
Number format	Use Intl.NumberFormat
Pluralization	Use ICU message format

7. RTL Support

/* CSS Logical Properties */
.container {
  margin-inline-start: 1rem;  /* Not margin-left */
  padding-inline-end: 1rem;   /* Not padding-right */
}

[dir="rtl"] .icon {
  transform: scaleX(-1);
}

8. Checklist

Before shipping:

All user-facing strings use translation keys
Locale files exist for all supported languages
Date/number formatting uses Intl API
RTL layout tested (if applicable)
Fallback language configured
No hardcoded strings in components

Script

The bundled checker is a heuristic, capped at 50 sorted source files. It uses English-biased regexes and directory-based JSON locale grouping; gettext catalogs and messages/en.json layouts are not fully checked for key parity. Report actual sampled/discovered counts and parse failures; a clean sample does not certify completeness, translation quality or accessibility. Mirror only directional icons for RTL (for example navigation arrows), not every logo, image or media control.

Script	Purpose	Command
`scripts/i18n_checker.py`	Detect hardcoded strings & missing translations	`python scripts/i18n_checker.py <project_path>`

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.