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 ViteToNext.AI can help convert your Vite component patterns into Next.js compatible structures automatically.

Accessing Translations in Server Components

Instead of the useTranslation hook (which requires a Client Component), you will now use asynchronous functions to fetch dictionaries:

// lib/get-dictionary.ts
const dictionaries = {
  en: () => import('../dictionaries/en.json').then((module) => module.default),
  es: () => import('../dictionaries/es.json').then((module) => module.default),
};

export const getDictionary = async (locale: 'en' | 'es') => dictionaries[locale]();

And inside your page.tsx:

export default async function Page({ params: { locale } }) {
  const dict = await getDictionary(locale);
  return <button>{dict.products.cart}</button>;
}

Step 3: Handling Client-Side Interactivity

You will still need hooks for components that change state (like a language switcher). For these cases, you must wrap your component in a I18nProvider.

1. Extract the dictionary on the server.
2. Pass it to a Client Component provider.
3. Consume it via hooks like useTranslations().

This ensures that even when the user interacts with the page, the translation context is fully available without a network request to a translation backend.

Step 4: Refactoring Static Assets

In Vite, your translation files likely live in public/locales. In Next.js, while they can stay in public, it is technically more performant to keep them in a dictionaries folder outside of public if you are using Server Components to import them. This prevents the translation keys from being public-facing URLs and allows for better bundling of only the required languages.

Common Pitfalls to Avoid

1. Hydration Errors: This happens if the server renders one language and the client tries to switch to another immediately. Ensure your <html> tag has the correct lang attribute assigned from the server.
2. SEO Metadata: Don't forget to update your layout.tsx to include metadata that changes based on the locale. Next.js makes this easy with the generateMetadata function.
3. Environment Variables: If your i18n logic used import.meta.env, remember to switch to process.env or NEXT_PUBLIC_ for client-side variables.

Conclusion

Moving an i18n app from Vite to Next.js is more than a simple file move; it's a shift from "loading translations" to "serving translations." By utilizing Middleware for routing and Server Components for dictionary fetching, you significantly improve your LCP and SEO while providing a smoother experience for your global users.

While the manual refactoring of hooks to async functions takes time, the performance gains and the power of the Next.js ecosystem make it a worthy investment for any growing application.

Further reading: Explore how to automate your framework transition at vitetonext.codebypaki.online.