Implementing Internationalization

We built this skill so you don't have to reverse-engineer the Intl API every time you ship a new locale. You're likely hardcoding strings, missing the lang attribute on your root element, and assuming toLocaleDateString() is enough for global users. It isn't. Internationalization is a system, not a translation pass. It requires BCP 47 compliance, robust pluralization logic, and validation pipelines that catch missing keys before they hit production. We engineered this workflow to handle the edge cases that break apps in de-DE, zh-CN, and ar-SA.

The Hidden Cost of Hardcoded Strings and Broken Locales

When you treat i18n as an afterthought, you pay for it in three ways: runtime performance, customer trust, and maintenance debt. Every time a user from a non-English locale visits your app, the browser or your server is forced to guess formatting rules. If you're not using the Intl object correctly, you're either serving wrong data or wasting cycles on fallback logic ^[1]. The ECMAScript Internationalization API provides specialized objects for locale-specific logic, but only if you initialize them with the right locale tags ^[3].

Beyond the code, the business impact is severe. A missing lang attribute on your element doesn't just affect screen readers; it signals to search engines that your content is English-only, tanking your SEO in every other market ^[7]. You lose organic traffic. You lose enterprise deals that require localization. And when you finally do ship a German or Japanese locale, you'll likely ship it with broken pluralization, wrong date formats, and UI text that overflows containers because you didn't account for text expansion in de-DE.

The cost of ignoring this compounds. Every hardcoded string is a ticket waiting to be opened. Every runtime formatting error is a P99 latency spike. Every missing locale key is a broken user journey. If you're managing complex state alongside localization, the friction increases—see how we handle Implementing Multi Step Wizard to see why state and i18n often collide. You need a structured approach, not a band-aid. The Internationalization Pack covers broader implementation strategies, but this skill drills down into the exact workflow for i18next and Intl compliance.

Why "Just Translate the Text" Breaks Your App

Imagine a logistics team that ships a dashboard to Berlin. They copy en.json to de.json and swap the text. On day one, it works. On day two, a user reports that the order count display is wrong. The UI shows "1 Bestellungen" instead of "1 Bestellung". The pluralization rules for German are different from English. Your app doesn't know this because you didn't implement Intl.PluralRules or configure i18next with proper pluralization keys.

This isn't a hypothetical. We've seen teams ship zh-CN locales where the date format is MM/DD/YYYY instead of YYYY-MM-DD, confusing users and breaking downstream parsing. We've seen apps crash when Intl.DateTimeFormat receives an unsupported locale. The Intl API is powerful, but it's strict ^[4]. It expects valid BCP 47 tags. It expects you to handle fallbacks. It expects you to format numbers, currencies, and relative times according to the user's region ^[8].

Consider a fintech app that needs to format currency. In en-US, it's $1,234.56. In de-DE, it's 1.234,56 €. In ar-SA, it's ١٬٢٣٤٫٥٦ ر.س.. If you hardcode the separator, you're broken. If you use Intl.NumberFormat without a locale, you're broken. If you don't validate your translation files against a schema, you'll ship keys that don't exist, resulting in {{key}} placeholders in the UI.

The W3C provides extensive techniques for authoring HTML for internationalization, but implementing them manually is error-prone ^[6]. You need a workflow that enforces these standards. You need a skill that scaffolds the directory structure, generates the config, validates the files, and provides type-safe hooks. You need to treat i18n as a first-class citizen in your build pipeline, not a manual copy-paste job.

What Changes When You Lock Down the i18n Workflow

Once you install this skill, your i18n workflow shifts from reactive patching to proactive enforcement. You start with BCP 47 standards. Every locale tag is validated. You initialize i18next with a production-grade config that supports ChainedBackend for HTTP and lazy loading, ensuring your app doesn't download 5MB of translation files on first load. You get type-safe hooks that prevent typos in key names. You get a validation script that runs in CI/CD, checking for missing keys and schema violations before code merges.

The Intl API integration becomes seamless. You use useTranslation hooks that respect the user's locale, falling back gracefully to English or a default language. You use the Trans component for HTML interpolation, avoiding innerHTML vulnerabilities. You handle pluralization with Intl.PluralRules logic baked into your translation files. You format dates, numbers, and relative times with Intl.DateTimeFormat, Intl.NumberFormat, and Intl.RelativeTimeFormat, all configured via the skill's templates.

The validation pipeline catches errors early. The validate-translations.sh script checks your files against translation-schema.json. It detects missing keys compared to the source locale. It exits non-zero on failure, blocking the build. You sleep better knowing that every merge is i18n-compliant. The Internationalization Pack offers additional guidance, but this skill gives you the executable scripts and templates to ship immediately.

You also get structured references. The bcp47-and-standards.md file gives you the authoritative list of BCP 47 tags. The i18next-core-api.md file documents every method you need. The react-i18next-patterns.md file shows you how to use HOCs, hooks, and namespaces effectively. You're not guessing. You're following a proven workflow.

What's in the Implementing Internationalization Skill

This is a multi-file deliverable. Every file serves a specific purpose in the i18n workflow. There are no placeholders. There are no "TODO" comments. There is production-grade code, validation, and scaffolding.

• skill.md — Orchestrator skill defining the i18n workflow: BCP 47 standards, i18next initialization, React integration, validation, and scaffolding. References all templates, scripts, validators, and examples.
• references/bcp47-and-standards.md — Authoritative reference for BCP 47 language tags, RFC 6497 transformed content, and MDN guidelines on language markup in HTML/XML.
• references/i18next-core-api.md — Curated i18next Core API docs: init with resources/backends, addResourceBundle, loadNamespaces, loadLanguages, reloadResources, and Backend Plugin API.
• references/react-i18next-patterns.md — Curated React-i18next patterns: withTranslation HOC, useTranslation hook, Trans component, namespace management, and ESLint/precommit config.
• templates/i18next-config.ts — Production-grade i18next initialization with TypeScript types, ChainedBackend for HTTP + lazy loading, fallbackLng, and namespace support.
• templates/react-hooks.tsx — Production-grade React hooks usage: useTranslation with namespaces, Trans component for HTML interpolation, and type-safe translation function.
• templates/translation-schema.json — JSON Schema for validating translation file structure, ensuring keys are strings and nested objects follow expected patterns.
• scripts/scaffold-i18n.sh — Executable script to scaffold i18n directory structure, create initial locale files (en, de), and generate i18next config template.
• scripts/validate-translations.sh — Executable script to validate translation files against schema and check for missing keys using node-validator. Exits non-zero on failure.
• validators/translation-validator.mjs — Node.js validator script: checks translation files against JSON schema, detects missing keys compared to source locale, and exits non-zero on errors.
• examples/worked-example.tsx — Complete React component example demonstrating namespace usage, interpolation, pluralization, and type-safe translation.
• examples/locales/en.json — Example English locale file with nested keys, interpolation, and pluralization.
• examples/locales/de.json — Example German locale file mirroring English structure.

The Internationalization Pack provides broader context, but this skill delivers the exact files you need to implement i18n in React with i18next and Intl. The Implementing Multi Step Wizard skill complements this by handling state, which often intersects with locale-aware UI flows.

Upgrade to Pro and Ship Global-Ready Code

Stop guessing Intl options. Stop shipping broken locales. Stop manually validating translation files. Upgrade to Pro to install this skill and get a structured, validated, production-ready i18n workflow. The code is here. The scripts are here. The references are here. All you have to do is install and ship.