Skill

i18n

Adds full internationalization (i18n) to Next.js App Router projects using next-intl, with SEO-friendly locale routing, hreflang sitemaps, 14+ languages, and bulk translation.

Next.js

Typescript

frontend

Install

npx claudepluginhub joshuarweaver/cascade-communication --plugin openclaudia-openclaudia-skills

Tool Access

This skill uses the workspace's default tool permissions.

Preview

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.

SKILL.md

Similar Skills

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

168.3k

subagent-driven-development

3 files

Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.

superpowers

168.3k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

168.3k

Stats

Stars401

Forks5

Last CommitApr 10, 2026

Actions

View Source View Plugin View on GitHub View README

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

Check the Next.js version (package.json) — must be 13+ with App Router
Check if i18n is already partially set up (look for next-intl, next-i18next, [locale] routes)
Identify all pages/routes that need translation
Identify all user-facing strings (hardcoded text in components)
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]/:

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
Move existing pages into src/app/[locale]/
Each page should call setRequestLocale(locale) for static generation

Step 7: Extract Strings into Translation Files

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": "..." }] }
}

Replace all hardcoded strings in components with useTranslations():

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

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:

Launch one Codex task per locale (up to 7 in parallel) using /codex-tasks
Each task reads en.json, translates all strings, writes {locale}.json
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
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', 'de', 'pt', 'ja', 'ar', 'zh', 'zh-tw', 'id', 'vi', 'ms', 'ru', 'hi']
english_words = ['the ', 'and ', 'you ', 'your ', 'our ', 'this ', 'that ', 'with ', 'from ', 'will ']

with open('src/messages/en.json') as f:
    en = json.load(f)

for loc in locales:
    with open(f'src/messages/{loc}.json') as f:
        data = json.load(f)

    # Check: missing sections
    missing = [s for s in en if s not in data]

    # Check: residual English content
    eng_count = 0
    def check(d):
        nonlocal eng_count  # won't work in inline script; use list trick
        if isinstance(d, dict):
            for v in d.values(): check(v)
        elif isinstance(d, str):
            if sum(1 for w in english_words if w in d.lower()) >= 3:
                eng_count += 1
    check(data)

    status = 'OK' if not missing and eng_count == 0 else 'ISSUES'
    print(f'{loc}: {status} (missing={len(missing)}, english={eng_count})')

Step 9: Update Sitemap with Hreflang

Update src/app/sitemap.ts to include hreflang alternates:

import { MetadataRoute } from 'next'
import { locales } from '@/i18n/config'

const baseUrl = 'https://www.example.com'

function buildAlternates(path: string): Record<string, string> {
  const alternates: Record<string, string> = {}
  for (const locale of locales) {
    const prefix = locale === 'en' ? '' : `/${locale}`
    alternates[locale] = `${baseUrl}${prefix}${path}`
  }
  return alternates
}

export default function sitemap(): MetadataRoute.Sitemap {
  return pages.map((path) => ({
    url: `${baseUrl}${path}`,
    lastModified: new Date(),
    alternates: { languages: buildAlternates(path) },
  }))
}

Important: Generate one canonical URL per page with hreflang alternates, NOT one URL per locale. This prevents duplicate content in search results.

Step 10: Add Language Selector (Optional)

Add a language switcher component that uses useRouter and usePathname from @/i18n/navigation to switch locales while preserving the current path.

Step 11: Verify

Build the project: npm run build — check that all static pages generate correctly
Test English URLs have no prefix: https://example.com/tools
Test locale URLs have prefix: https://example.com/es/tools
Verify sitemap has hreflang alternates
Check RTL rendering for Arabic
Run the translation verification script from Step 8

Common Pitfalls

public/sitemap.xml conflicts with dynamic src/app/sitemap.ts in dev mode — delete the static one or rename it
Middleware matcher must exclude _next, api, sitemap, robots, and static asset paths
localePrefix: 'as-needed' is critical — it keeps default locale URLs clean for SEO continuity
localeDetection: false prevents unwanted redirects that break SEO and confuse users
Large translation files (5000+ lines per locale) can make git pushes fail — use git config http.postBuffer 524288000
Verify translations thoroughly — automated translation often produces mixed-language output; always verify with the English word detection script after Codex tasks complete

Locale Count Reference

14 locales x N pages = 14N static pages at build time
Each locale JSON file is typically 2-5x the size of en.json (CJK characters, verbose languages)
Build time increases linearly with locale count

i18n

Install

Tool Access

Preview

SKILL.md

Similar Skills

i18n

Install

Tool Access

Preview

SKILL.md

Internationalize a Next.js Project

Step 1: Assess the Project

Step 2: Install Dependencies

Step 3: Create i18n Configuration Files

src/i18n/config.ts

src/i18n/routing.ts

src/i18n/navigation.ts

src/i18n/request.ts

Step 4: Create Middleware

Step 5: Update next.config

Step 6: Add [locale] Dynamic Route

Step 7: Extract Strings into Translation Files

Step 8: Translate to All Locales

Translation Strategy

Verification

Step 9: Update Sitemap with Hreflang

Step 10: Add Language Selector (Optional)

Step 11: Verify

Common Pitfalls

Locale Count Reference

Similar Skills

Internationalize a Next.js Project

Step 1: Assess the Project

Step 2: Install Dependencies

Step 3: Create i18n Configuration Files

src/i18n/config.ts

src/i18n/routing.ts

src/i18n/navigation.ts

src/i18n/request.ts

Step 4: Create Middleware

Step 5: Update next.config

Step 6: Add [locale] Dynamic Route

Step 7: Extract Strings into Translation Files

Step 8: Translate to All Locales

Translation Strategy

Verification

Step 9: Update Sitemap with Hreflang

Step 10: Add Language Selector (Optional)

Step 11: Verify

Common Pitfalls

Locale Count Reference

`src/i18n/config.ts`

`src/i18n/routing.ts`

`src/i18n/navigation.ts`

`src/i18n/request.ts`

Step 6: Add `[locale]` Dynamic Route

`src/i18n/config.ts`

`src/i18n/routing.ts`

`src/i18n/navigation.ts`

`src/i18n/request.ts`

Step 6: Add `[locale]` Dynamic Route