Next Intl Add Language

Next Intl Add Language is an AI skill that guides developers in adding new language support to Next.js applications using the next-intl internationalization library. It covers locale configuration, message file creation, middleware setup, routing patterns, and component-level translation integration for building fully localized Next.js applications with the App Router.

What Is This?

Overview

Next Intl Add Language provides step-by-step guidance for expanding language support in Next.js projects using next-intl. It covers adding new locale definitions to the configuration, creating and organizing translation message files, configuring middleware for automatic locale detection, setting up locale-prefixed routing, and integrating translations into both Server Components and Client Components. The skill ensures each step follows next-intl best practices for the App Router architecture.

Who Should Use This

This skill serves Next.js developers adding internationalization to existing applications, frontend teams expanding their application to support additional markets, localization engineers setting up translation infrastructure for Next.js projects, and developers migrating from other i18n libraries to next-intl.

Why Use It?

Problems It Solves

Adding a new language to a Next.js application requires changes across multiple configuration files, middleware, routing, and component code. Missing a step leads to broken locale detection, untranslated fallback content appearing to users, or routing errors where locale-prefixed URLs do not resolve correctly. The next-intl library has specific patterns for App Router that differ from Pages Router approaches.

Core Highlights

The skill provides a complete checklist that covers every file and configuration change needed to add a new language. It generates translation message file templates that match existing language structure, configures middleware for locale negotiation with proper fallback behavior, and provides component patterns for both server-rendered and client-rendered translation usage.

How to Use It?

Basic Usage

// Step 1: Add locale to i18n configuration (src/i18n.ts)
import { getRequestConfig } from 'next-intl/server';

export const locales = ['en', 'es', 'fr'] as const;  // Added 'fr'
export const defaultLocale = 'en';

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

// Step 2: Update middleware (src/middleware.ts)
import createMiddleware from 'next-intl/middleware';
import { locales, defaultLocale } from './i18n';

export default createMiddleware({
  locales,
  defaultLocale,
  localeDetection: true
});

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)']  
};

Real-World Examples

// messages/fr.json - New French translation file
{
  "common": {
    "welcome": "Bienvenue sur notre application",
    "login": "Se connecter",
    "logout": "Se deconnecter",
    "save": "Enregistrer",
    "cancel": "Annuler"
  },
  "navigation": {
    "home": "Accueil",
    "products": "Produits",
    "about": "A propos",
    "contact": "Contact"
  },
  "products": {
    "title": "Nos produits",
    "addToCart": "Ajouter au panier",
    "price": "Prix: {amount, number, currency}",
    "inStock": "{count, plural, =0 {Rupture de stock} one {# article en stock} other {# articles en stock}}"
  }
}

Advanced Tips

Use the next-intl message format with ICU syntax for pluralization, number formatting, and date formatting to handle language-specific rules correctly. Create a script that compares message keys across all locale files to identify missing translations before deployment. Implement a locale switcher component that preserves the current page path when changing languages.

When to Use It?

Use Cases

Use Next Intl Add Language when expanding a Next.js application to support a new market language, when setting up internationalization infrastructure for a new Next.js project, when migrating from another i18n approach to next-intl, or when establishing translation workflows for a team of content translators.

Related Topics

Next.js App Router internationalization patterns, ICU message format specification, locale detection and negotiation, translation management platforms, React Server Components with translations, and locale-aware date and number formatting all complement the next-intl workflow.

Important Notes

Requirements

Next.js 13.4 or later with App Router enabled. The next-intl package installed. Translation message files for the new language matching the structure of existing locale files. Middleware configuration for locale routing.

Usage Recommendations

Do: create the new language message file by copying the default locale file and translating values to maintain structural consistency. Test locale detection with browser language preferences to verify automatic locale selection works. Verify all dynamic routes work correctly with the new locale prefix.

Don't: add a new locale without creating its complete message file, as missing translations cause runtime errors or fallback text. Skip middleware configuration updates when adding locales, since unrecognized locales will not route correctly. Translate message keys instead of values, as keys must remain identical across all locale files.

Limitations

Next-intl handles application string translations but does not translate user-generated content or database records. ICU message format has a learning curve for complex pluralization and formatting rules. Very large translation files may impact Server Component rendering time and should be split into namespaces. Some third-party UI libraries may not support the locale passed through next-intl context.