Migrating a Vite i18n App to Next.js Without Breaking Everything

Introduction

Internationalization (i18n) is one of those features that feels simple until you have to change your underlying architectural framework. If you've been building a Single Page Application (SPA) with Vite and react-i18next, you've likely enjoyed a fast developer experience and client-side translation loading.

However, as applications grow, SEO requirements and Initial Page Load metrics often push developers toward Next.js. The shift from Vite’s purely client-side environment to Next.js's specialized server-side capabilities introduces unique challenges for i18n—specifically regarding hydration mismatches and routing. In this guide, we will walk through the strategy for migrating your localization logic without breaking your user experience.

The Core Difference: CSR vs. SSR i18n

In a Vite application, i18n usually happens entirely on the client. You initialize i18next, load JSON files via an HTTP backend, and the library handles the switch.

In Next.js (App Router), internationalization is ideally handled via Middleware and Server Components. Instead of the browser detecting the language and showing a loading spinner while the JSON loads, the server detects the locale from the URL or headers and serves the pre-rendered content in the correct language immediately.

Step 1: Mapping Your Routing Strategy

Vite apps often use react-router-dom with a strategy where the locale is either in the state or a simple URL prefix.

In Next.js, the standard approach is using dynamic segments: /[locale]/your-page. You'll need to move your src/pages to app/[locale]/.

The Middleware Approach

Create a middleware.ts file in your root to handle locale detection:

import { NextResponse } from 'next/server';

import type { NextRequest } from 'next/server';



const locales = ['en', 'es', 'fr'];



export function middleware(request: NextRequest) {

  const pathname = request.nextUrl.pathname;

  const pathnameIsMissingLocale = locales.every(

    (locale) => !pathname.startsWith(`/${locale}/`) && pathname !== `/${locale}`

  );



  if (pathnameIsMissingLocale) {

    const locale = 'en'; // Detect from headers if preferred

    return NextResponse.redirect(

      new URL(`/${locale}${pathname}`, request.url)

    );

  }

}



export const config = {

  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],

};

Step 2: From react-i18next to next-intl or i18next-ssr

While you can use react-i18next in Next.js, the community has largely moved toward next-intl or specialized SSR setups for i18next to avoid the dreaded "Flash of Unlocalized Content" (FOUC).

If you have a massive codebase and want to automate the structural heavy lifting of this transition, tools like .