i18n Setup

You are a frontend developer setting up internationalization in a React or Next.js application. The user wants to configure either next-intl (Next.js App Router) or react-i18next (general React) for multi-language support.

What to check first

• Run npm list next react-i18next next-intl to see if i18n packages are already installed
• Check your package.json to confirm your Next.js version (next-intl requires Next.js 13.4+) and React version
• Verify your project structure: Next.js App Router vs Pages Router, or plain React with routing library

Steps

1. Install the appropriate i18n package: npm install next-intl for Next.js App Router or npm install react-i18next i18next for general React apps
2. Create a messages folder in your project root with language JSON files: messages/en.json, messages/de.json, messages/fr.json containing key-value translation pairs
3. For next-intl: Create i18n.ts in your project root with createSharedPathnamesNavigation() and getRequestConfig() functions
4. For next-intl: Update next.config.js to add the i18n plugin configuration with supported locales and default locale
5. For next-intl: Wrap your app in NextIntlClientProvider at the layout level and set up dynamic locale routing in [locale] folder structure
6. For react-i18next: Create i18n.js to initialize i18next with i18n.use(HttpBackend).init() and load language resources
7. For react-i18next: Wrap your root App component with Suspense and I18nextProvider
8. Use useTranslation() hook (react-i18next) or useTranslations() hook (next-intl) in components to access translated strings

Code

// next-intl setup: i18n.ts
import { getRequestConfig } from 'next-intl/server';
import { createSharedPathnamesNavigation } from 'next-intl/navigation';

export const locales = ['en', 'de', 'fr'];
export const defaultLocale = 'en';

export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`./messages/${locale}.json`)).default,
}));

export const { Link, redirect, usePathname, useRouter } =
  createSharedPathnamesNavigation({ locales, defaultLocale });

// next.config.js
import createNextIntlPlugin from 'next-intl/plugin';
const withNextIntl = createNextIntlPlugin();

export default withNextIntl({
  reactStrictMode: true,
});

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change