Internationalize and localize web applications with next-intl, react-intl, ICU MessageFormat, RTL layouts, locale routing, and dynamic locale loading. Use when adding translations or a new language, writing plural or select messages, supporting Hebrew or Arabic RTL, formatting dates, numbers, or currency per locale, or when the user mentions i18n, l10n, next-intl, or locale files.
Internationalization (i18n) and localization (l10n) for web applications. Implements proper message formatting, locale routing, RTL support, and dynamic translation loading.
ICU plural and select, rich text, dates, numbers, currency
references/icu-and-formatting.md
Hebrew, Arabic, or other RTL layouts, logical CSS, Tailwind
references/rtl-layout.md
Read the file that matches the task before writing code. The core rules below always apply.
Core rules
No user-visible string in code. Every label, error, placeholder, aria-label, and page title comes from a message file.
One message per sentence. Never concatenate fragments or build plurals with a ternary. Use ICU plural and select.
Always include the other branch in plural and select messages.
Format with Intl. Dates, numbers, currency, lists, and relative times go through Intl or the library formatter, never toFixed or a hardcoded pattern.
Logical CSS only. Use margin-inline-start, text-align: start, and Tailwind ms-*/pe-*. Never left or right for layout.
Set lang and dir on <html> from the active locale. Cover he, ar, fa, and ur as RTL.
Validate the locale at the boundary (route segment, cookie, header) against the configured list. Unknown locale means 404 or the default, never a thrown import error.
Load only the active locale. No static imports of every message file.
Keep locale files in sync. Same keys and same ICU placeholders in every language. Fail CI when they drift.
Do not translate by machine and ship unreviewed. Mark machine drafts and have a native speaker review user-facing copy.
Translation file structure
BAD: flat keys, mixed namespaces, layout in the name
Name keys for what the text means (checkout.submit), not where it sits or what it says. Keep the source-language file as the reference and the type source.
Plurals in one line
BAD
const message = count === 1 ? `You have ${count} message` : `You have ${count} messages`;
GOOD
{ "count": "{count, plural, =0 {No messages} one {# message} other {# messages}}" }
More ICU, rich text, and Intl formatting in references/icu-and-formatting.md.
Direction handling, icon mirroring, and mixed LTR/RTL text in references/rtl-layout.md.
Next.js 16 with next-intl in one screen
defineRouting({ locales, defaultLocale }) in src/i18n/routing.ts is the single source of locales.
src/proxy.ts runs createMiddleware(routing). Before Next.js 16 the file is middleware.ts.
src/i18n/request.ts uses getRequestConfig and validates the locale with hasLocale.
app/[locale]/layout.tsx awaits params (a Promise in Next.js 15 and 16), calls notFound() for bad locales, calls setRequestLocale(locale), and sets lang and dir.
Use createNavigation(routing) wrappers (Link, useRouter, usePathname) so links keep the locale.
Type message keys by augmenting AppConfig in next-intl.
Full code in references/next-intl-setup.md.
Review checklist
No hardcoded visible strings, including alt, title, placeholder, and aria-label
Plurals and selects use ICU with other
Dates, numbers, and currency use Intl with an explicit time zone on the server
No left, right, ml-*, mr-*, text-left in layout code
lang and dir set from the locale; Hebrew and Arabic both covered
hreflang alternates and a locale-aware sitemap for public pages
Every locale has the same keys as the source file
Locale switcher shows each language in its own name and sets lang on options
1---2name: i18n-localization3description: "Internationalize and localize web applications with next-intl, react-intl, ICU MessageFormat, RTL layouts, locale routing, and dynamic locale loading. Use when adding translations or a new language, writing plural or select messages, supporting Hebrew or Arabic RTL, formatting dates, numbers, or currency per locale, or when the user mentions i18n, l10n, next-intl, or locale files."4user-invocable: true5metadata:6 source: https://skillmd.com/skills/medy-gribkov/i18n-localization7---89# i18n-localization1011Internationalization (i18n) and localization (l10n) for web applications. Implements proper message formatting, locale routing, RTL support, and dynamic translation loading.1213## Where to look1415| Task | Read |16|---|---|17| next-intl routing, proxy.ts, layouts, locale switcher, loading messages, typed keys | [references/next-intl-setup.md](references/next-intl-setup.md) |18| ICU plural and select, rich text, dates, numbers, currency | [references/icu-and-formatting.md](references/icu-and-formatting.md) |19| Hebrew, Arabic, or other RTL layouts, logical CSS, Tailwind | [references/rtl-layout.md](references/rtl-layout.md) |2021Read the file that matches the task before writing code. The core rules below always apply.2223## Core rules24251. **No user-visible string in code.** Every label, error, placeholder, `aria-label`, and page title comes from a message file.262. **One message per sentence.** Never concatenate fragments or build plurals with a ternary. Use ICU `plural` and `select`.273. **Always include the `other` branch** in plural and select messages.284. **Format with Intl.** Dates, numbers, currency, lists, and relative times go through `Intl` or the library formatter, never `toFixed` or a hardcoded pattern.295. **Logical CSS only.** Use `margin-inline-start`, `text-align: start`, and Tailwind `ms-*`/`pe-*`. Never `left` or `right` for layout.306. **Set `lang` and `dir` on `<html>`** from the active locale. Cover `he`, `ar`, `fa`, and `ur` as RTL.317. **Validate the locale at the boundary** (route segment, cookie, header) against the configured list. Unknown locale means 404 or the default, never a thrown import error.328. **Load only the active locale.** No static imports of every message file.339. **Keep locale files in sync.** Same keys and same ICU placeholders in every language. Fail CI when they drift.3410. **Do not translate by machine and ship unreviewed.** Mark machine drafts and have a native speaker review user-facing copy.3536## Translation file structure3738**BAD: flat keys, mixed namespaces, layout in the name**39```json40{41 "welcomeMessage": "Welcome",42 "homePageTitle": "Home",43 "userProfileName": "Name",44 "checkoutButtonSubmit": "Submit Order"45}46```4748**GOOD: namespaced by feature, nested by meaning**49```json50// messages/en/common.json51{ "welcome": "Welcome", "loading": "Loading...", "error": "An error occurred" }5253// messages/en/home.json54{ "title": "Home", "hero": { "heading": "Welcome to our platform", "subheading": "Build amazing things" } }5556// messages/en/user.json57{ "profile": { "name": "Name", "email": "Email", "updatedAt": "Last updated {date}" } }58```5960Name keys for what the text means (`checkout.submit`), not where it sits or what it says. Keep the source-language file as the reference and the type source.6162## Plurals in one line6364**BAD**65```typescript66const message = count === 1 ? `You have ${count} message` : `You have ${count} messages`;67```6869**GOOD**70```json71{ "count": "{count, plural, =0 {No messages} one {# message} other {# messages}}" }72```7374More ICU, rich text, and Intl formatting in [references/icu-and-formatting.md](references/icu-and-formatting.md).7576## Logical CSS in one line7778**BAD**79```css80.sidebar { float: left; margin-right: 20px; text-align: left; }81```8283**GOOD**84```css85.sidebar { float: inline-start; margin-inline-end: 20px; text-align: start; }86```8788Direction handling, icon mirroring, and mixed LTR/RTL text in [references/rtl-layout.md](references/rtl-layout.md).8990## Next.js 16 with next-intl in one screen9192- `defineRouting({ locales, defaultLocale })` in `src/i18n/routing.ts` is the single source of locales.93- `src/proxy.ts` runs `createMiddleware(routing)`. Before Next.js 16 the file is `middleware.ts`.94- `src/i18n/request.ts` uses `getRequestConfig` and validates the locale with `hasLocale`.95- `app/[locale]/layout.tsx` awaits `params` (a Promise in Next.js 15 and 16), calls `notFound()` for bad locales, calls `setRequestLocale(locale)`, and sets `lang` and `dir`.96- Use `createNavigation(routing)` wrappers (`Link`, `useRouter`, `usePathname`) so links keep the locale.97- Type message keys by augmenting `AppConfig` in `next-intl`.9899Full code in [references/next-intl-setup.md](references/next-intl-setup.md).100101## Review checklist102103- [ ] No hardcoded visible strings, including `alt`, `title`, `placeholder`, and `aria-label`104- [ ] Plurals and selects use ICU with `other`105- [ ] Dates, numbers, and currency use Intl with an explicit time zone on the server106- [ ] No `left`, `right`, `ml-*`, `mr-*`, `text-left` in layout code107- [ ] `lang` and `dir` set from the locale; Hebrew and Arabic both covered108- [ ] `hreflang` alternates and a locale-aware sitemap for public pages109- [ ] Every locale has the same keys as the source file110- [ ] Locale switcher shows each language in its own name and sets `lang` on options
Run npx get-skill add medy-gribkov/i18n-localization in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Internationalize and localize web applications with next-intl, react-intl, ICU MessageFormat, RTL layouts, locale routing, and dynamic locale loading. Use when adding translations or a new language, writing plural or select messages, supporting Hebrew or Arabic RTL, formatting dates, numbers, or currency per locale, or when the user mentions i18n, l10n, next-intl, or locale files. It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
medy-gribkov (@medy-gribkov) published this skill. Their other Agent Skills are listed on their SkillMD profile.