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

The Challenge of Framework Level i18n

Internationalization (i18n) is one of the most complex layers of a frontend application. When you are working within a Vite-based Single Page Application (SPA), you likely rely on react-i18next or lingui to handle translations client-side. The state is managed in the browser, and the language is often tucked away in local storage or a URL query parameter.

Moving to Next.js changes the game entirely. You transition from a purely client-side routing model to a server-ready architecture where SEO-friendly locales (like /en/about or /es/about) are the standard. If you don't plan the migration carefully, you risk breaking your SEO, your hydration, and your user experience.

In this guide, we will look at how to port your i18n logic from Vite to Next.js using the App Router while keeping your codebase maintainable.

1. Understanding the Routing Shift

In a Vite app, your i18n setup usually looks like this:

// i18n.ts in Vite
i18n.use(initReactI18next).init({
  resources,
  lng: localStorage.getItem('lang') || 'en',
  fallbackLng: 'en',
});

In Next.js, the "source of truth" for the language is the URL path. Next.js 13+ (App Router) expects the locale to be a layout segment. Your file structure needs to move from src/pages/About.tsx to app/[locale]/about/page.tsx.

2. Setting up Middleware for Locale Detection

Instead of checking localStorage inside a useEffect, Next.js uses Middleware to detect the user's preferred language before the page even renders. This prevents the "flash of untranslated content."

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

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

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const pathnameHasLocale = locales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );

  if (pathnameHasLocale) return;

  const locale = 'en'; // Detect logic here
  request.nextUrl.pathname = `/${locale}${pathname}`;
  return NextResponse.redirect(request.nextUrl);
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

3. Handling Client vs. Server Components

This is where most developers get stuck. In Vite, all components are client components. In Next.js, you have to decide.

• Server Components: Use them for fetching data and SEO. You don't need the useTranslation hook here; you can simply import the JSON files directly or use a library like next-intl to get the dictionary on the server.
• Client Components: Use these for interactivity (forms, buttons). These still use hooks, but they must receive the current locale as a prop or via a specialized provider.

4. Porting the Dictionary Files

Most Vite apps keep translation files in public/locales. While you can keep them there, Next.js allows you to colocate dictionaries or import them dynamically to reduce the initial bundle size.

If you find the structural changes to your routing and component hierarchy overwhelming during this move, you might consider using ViteToNext.AI to automate the heavy lifting of converting your Vite structure into an App Router compatible format.

5. SEO and Metadata

In Vite, you probably used react-helmet to update titles and descriptions. In Next.js, you use the generateMetadata function. For i18n, this is vital as it allows you to provide localized meta tags per route.

export async function generateMetadata({ params: { locale } }) {
  const t = await getDictionary(locale);

  return {
    title: t.seo.title,
    description: t.seo.description,
  };
}

6. Common Pitfalls to Avoid

1. Hydration Mismatches: If the server renders "Hello" (English) but the client thinks the language is Spanish because of a leftover localStorage check, React will throw a hydration error. Always sync your client state with the URL parameter.
2. Hardcoded Links: Update all your <Link> components. Instead of <Link href="/about">, you need <Link href={/${locale}/about}>.
3. Third-Party Libraries: Ensure your UI libraries (like Radix or Headless UI) are wrapped in the correct locale providers so that screen readers correctly identify the language change.

Conclusion

Migrating an i18n-ready app from Vite to Next.js requires moving away from side-effect-based language detection (useEffect/localStorage) towards a URL-first approach. By leveraging Next.js Middleware and properly splitting your Server and Client components, you gain significant performance boosts and better SEO without sacrificing the developer experience you enjoyed in Vite.

Further reading: Explore automated migration strategies at vitetonext.codebypaki.online.