/i18n

name: i18n
description: Add full internationalization (i18n) to a Next.js project using next-intl. Supports 14+ languages, SEO-friendly locale routing, hreflang sitemaps, and bulk translation. Use when the user asks to "internationalize", "add i18n", "add translations", "multi-language", "localize", "add language support", or "translate my site".
user_invocable: true

Internationalize a Next.js Project

Add complete internationalization to a Next.js (App Router) project using **next-intl v4**. This skill handles routing, translation files, sitemap hreflang, and bulk translation across all locales.

Step 1: Assess the Project

1. Check the Next.js version (`package.json`) — must be 13+ with App Router 2. Check if i18n is already partially set up (look for `next-intl`, `next-i18next`, `[locale]` routes) 3. Identify all pages/routes that need translation 4. Identify all user-facing strings (hardcoded text in components) 5. Ask the user which locales to support (default recommendation: en, es, fr, de, pt, ja, ar, zh, zh-tw, id, vi, ms, ru, hi)

Step 2: Install Dependencies

npm install next-intl

Step 3: Create i18n Configuration Files

Create 4 files under `src/i18n/`:

`src/i18n/config.ts`

export const locales = ['en', 'es', 'fr', 'de', 'pt', 'ja', 'ar', 'zh', 'zh-tw', 'id', 'vi', 'ms', 'ru', 'hi'] as const

export type Locale = (typeof locales)[number]
export const defaultLocale: Locale = 'en'

export const localeNames: Record<Locale, string> = {
  en: 'English',
  es: 'Espanol',
  fr: 'Francais',
  de: 'Deutsch',
  pt: 'Portugues',
  ja: '日本語',
  ar: 'العربية',
  zh: '简体中文',
  'zh-tw': '繁體中文',
  id: 'Bahasa Indonesia',
  vi: 'Tieng Viet',
  ms: 'Bahasa Melayu',
  ru: 'Русский',
  hi: 'हिन्दी',
}

export const rtlLocales: Locale[] = ['ar']

`src/i18n/routing.ts`

import { defineRouting } from 'next-intl/routing'
import { defaultLocale, locales } from './config'

export const routing = defineRouting({
  locales,
  defaultLocale,
  localePrefix: 'as-needed', // English URLs stay clean, other locales get /es/, /fr/, etc.
})

`src/i18n/navigation.ts`

import { createNavigation } from 'next-intl/navigation'
import { routing } from './routing'

export const { Link, redirect, usePathname, useRouter } = createNavigation(routing)

`src/i18n/request.ts`

import { getRequestConfig } from 'next-intl/server'
import { routing } from './routing'

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale
  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale
  }
  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  }
})

Step 4: Create Middleware

Create `src/middleware.ts`:

import createMiddleware from 'next-intl/middleware'
import { routing } from '@/i18n/routing'

export default createMiddleware({
  ...routing,
  localeDetection: false, // Don't auto-redirect based on Accept-Language
})

export const config = {
  matcher: ['/((?!_next|api|images|fonts|favicon|sitemap|robots).*)'],
}

**Key decision**: `localeDetection: false` prevents auto-redirecting users based on browser language. This keeps English URLs stable for SEO. Users can manually switch languages via a language selector.

Step 5: Update next.config

Wrap the existing config with `createNextIntlPlugin`:

import createNextIntlPlugin from 'next-intl/plugin'
const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts')

// ... existing config ...
export default withNextIntl(nextConfig)

Step 6: Add `[locale]` Dynamic Route

Move all page content under `src/app/[locale]/`:

1. Create `src/app/[locale]/layout.tsx` with:

• `generateStaticParams()` returning all locales
• `setRequestLocale(locale)` call
• `<NextIntlClientProvider>` wrapping children
• `<html lang={locale} dir={rtlLocales.includes(locale) ? 'rtl' : 'ltr'}>`
• Hreflang `<link>` tags in `<head>` for all locales + `x-default`

2. Move existing pages into `src/app/[locale]/` 3. Each page should call `setRequestLocale(locale)` for static generation

Step 7: Extract Strings into Translation Files

1. Create `src/messages/en.json` with all user-facing strings organized by section:

   {
     "common": { "signIn": "Sign In", ... },
     "tools": { "tool-slug": { "title": "...", "description": "..." } },
     "faq": { "tool-slug": [{ "question": "...", "answer": "..." }] }
   }

2. Replace all hardcoded strings in components with `useTranslations()`:

   const t = useTranslations('common')
   return <button>{t('signIn')}</button>

3. For server components, use `getTranslations()`:

   const t = await getTranslations('common')

Step 8: Translate to All Locales

For each non-English locale, create `src/messages/{locale}.json` with the same structure as `en.json`.

Translation Strategy

Use **parallel Codex agents** via the `codex-tasks` skill to save Claude credits:

1. Launch one Codex task per locale (up to 7 in parallel) using `/codex-tasks` 2. Each task reads `en.json`, translates all strings, writes `{locale}.json` 3. Codex prompt should include:

• The full `en.json` content (or path to read it)
• Target language name and locale code
• Instructions:
• Translate naturally, not literally
• Keep technical terms in English (PowerPoint, PDF, API, etc.)
• Preserve JSON structure exactly (same keys, same nesting)
• Preserve interpolation variables like `{count}`, `{name}` unchanged
• Write the result to `src/messages/{locale}.json`

4. After Codex tasks complete, **verify the results** using the verification script below — Codex output quality varies and must be checked

Verification

After translation, run a verification script to catch issues:

import json

locales = ['es', 'fr',