Skip to main content

Next.js अंतरराष्ट्रीयकरण की संपूर्ण गाइड

App Router के साथ next-intl सेट अप करें, लोकेल रूटिंग कॉन्फ़िगर करें और AI से अनुवाद ऑटोमेट करें।

1

next-intl इंस्टॉल करें

next-intl एक ही पैकेज में Next.js App Router के लिए लोकेल रूटिंग, मैसेज लोडिंग और ट्रांसलेशन हुक संभालता है।

Terminal
npm install next-intl
next-i18next के बजाय next-intl क्यों चुनें? next-intl को App Router और server components के लिए बनाया गया है। next-i18next को Pages Router के लिए डिज़ाइन किया गया था और App Router के लिए उसका समर्थन सीमित है।
2

i18n रिक्वेस्ट कॉन्फ़िग बनाएँ

दो फ़ाइलें बनाएँ: मैसेज लोड करने के लिए src/i18n/request.ts और लोकेल परिभाषाओं के लिए src/i18n/routing.ts। ये कॉन्फ़िगर करती हैं कि next-intl मैसेज और रूट कैसे रिज़ॉल्व करता है।

src/i18n/routing.ts
// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
  locales: ['en', 'de', 'ja', 'es'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',  // /about for en, /de/about for de
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);
Turbopack, जो Next.js 15 में डिफ़ॉल्ट बंडलर है, को आपके next.config.js में experimental.turbo.resolveAlias की आवश्यकता होती है। इसके बिना "Couldn't find next-intl config file" त्रुटियाँ मिलती हैं।
3

Middleware कॉन्फ़िगर करें

लोकेल पहचान, URL रीराइट और रीडायरेक्ट संभालने के लिए middleware.ts जोड़ें। Middleware हर रिक्वेस्ट को इंटरसेप्ट करके सुनिश्चित करता है कि सही लोकेल लागू हो।

middleware.ts
// middleware.ts  <- Must be in project ROOT, not src/
import createMiddleware from 'next-intl/middleware';
import { routing } from './src/i18n/routing';

export default createMiddleware(routing);

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};
middleware.ts आपके प्रोजेक्ट की रूट डायरेक्टरी में ही होना चाहिए, src/ के भीतर नहीं। next-intl के साथ यह कॉन्फ़िगरेशन की सबसे आम गलती है।
4

[locale] फ़ोल्डर संरचना सेट अप करें

अपने ऐप रूट को app/[locale]/ के भीतर ले जाएँ। बिल्ड के समय हर लोकेल के लिए पेज जनरेट करने हेतु generateStaticParams जोड़ें। इससे /en/about, /de/about आदि वाली URL संरचना बनती है।

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
अनुवाद उपयोग करने वाली हर page.tsx और layout.tsx में setRequestLocale(locale) कॉल करना अनिवार्य है। इसके बिना Next.js डायनेमिक रेंडरिंग पर फ़ॉलबैक करता है और आपके बिल्ड का प्रदर्शन काफ़ी घट जाता है।
5

अपना रूट लेआउट अपडेट करें

getMessages() से मैसेज लोड करें और उन्हें अपने रूट लोकेल लेआउट में NextIntlClientProvider को पास करें। html का lang एट्रिब्यूट locale पैरामीटर से सेट करें।

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages, setRequestLocale } from 'next-intl/server';
import { routing } from '@/i18n/routing';
import { notFound } from 'next/navigation';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const { locale } = await params;
  if (!routing.locales.includes(locale as any)) notFound();

  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
NextIntlClientProvider को स्पष्ट locale prop की आवश्यकता होती है। इसे न देने से client components में ऐसी सूक्ष्म त्रुटियाँ आती हैं जिन्हें डीबग करना कठिन होता है।
6

कंपोनेंट में अनुवाद उपयोग करें

Server components getTranslations (async, await) उपयोग करते हैं। Client components useTranslations (hook) उपयोग करते हैं। आपका कंपोनेंट जहाँ रेंडर होता है, उसके आधार पर चुनें—server components अनुवादों को पूरी तरह JavaScript बंडल से बाहर रखते हैं।

app/[locale]/page.tsx
// Server Component (default)
import { getTranslations, setRequestLocale } from 'next-intl/server';

export default async function AboutPage({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const t = await getTranslations('AboutPage');

  return <h1>{t('title')}</h1>;
}

// Client Component ('use client')
'use client';
import { useTranslations } from 'next-intl';

export default function SearchBar() {
  const t = useTranslations('SearchBar');
  return <input placeholder={t('placeholder')} />;
}
अनूदित सामग्री के लिए server components को प्राथमिकता दें। वे अनुवाद स्ट्रिंग को आपके क्लाइंट JavaScript बंडल से बाहर रखते हैं, जिससे यूज़र के लिए लोड समय घटता है।
7

SEO जोड़ें: मेटाडेटा और Hreflang

लोकेल-विशिष्ट पेज शीर्षक और विवरण बनाने के लिए generateMetadata उपयोग करें। hreflang टैग के लिए alternates.languages जोड़ें, ताकि सर्च इंजन हर पेज के सभी भाषा संस्करण खोज सकें।

app/[locale]/layout.tsx
// app/[locale]/layout.tsx or any page.tsx
import { getTranslations } from 'next-intl/server';
import { routing } from '@/i18n/routing';

export async function generateMetadata({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Metadata' });

  return {
    title: t('title'),
    description: t('description'),
    alternates: {
      languages: Object.fromEntries(
        routing.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
Vercel पर metadataBase सेट न होने पर बिल्ड canonical URL के रूप में localhost जनरेट कर सकता है। अपने रूट लेआउट में metadataBase को हमेशा अपने प्रोडक्शन डोमेन पर सेट करें।
8

त्रुटि और Not-Found पेज संभालें

error.tsx और not-found.tsx को विशेष रूप से संभालना पड़ता है, क्योंकि वे सामान्य लोकेल लेआउट के बाहर रेंडर हो सकते हैं। लोकलाइज़्ड त्रुटि संदेश दिखाने के लिए रूट not-found.tsx को अपना अलग i18n provider सेटअप चाहिए।

app/[locale]/error.tsx
// app/[locale]/error.tsx
'use client';
import { useTranslations } from 'next-intl';

export default function Error() {
  const t = useTranslations('Error');
  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

// app/not-found.tsx (root level -- needs own provider)
import { routing } from '@/i18n/routing';

export default async function GlobalNotFound() {
  return (
    <html lang={routing.defaultLocale}>
      <body>
        <h1>404 - Page Not Found</h1>
      </body>
    </html>
  );
}
Next.js आपका लोकलाइज़्ड 404 पेज केवल तभी रेंडर करता है जब आपके कोड में notFound() स्पष्ट रूप से कॉल किया गया हो। किसी मेल खाते पेज के बिना अज्ञात रूट आपके लोकलाइज़्ड संस्करण के बजाय डिफ़ॉल्ट Next.js 404 दिखाते हैं।
9

अनुवाद ऑटोमेट करें

आपका i18n सेटअप पूरा हो जाने पर अपने IDE से सीधे AI का उपयोग करके अपनी मैसेज फ़ाइलों का अनुवाद करें या हर डिप्लॉय पर ऑटोमेटेड अनुवाद के लिए अपनी CI/CD pipeline में i18n Agent CLI उपयोग करें।

Terminal
# In your IDE, ask your AI assistant:
> Translate messages/en.json to German, Japanese, and Spanish

✓ messages/de.json created (1.1s)
✓ messages/ja.json created (1.4s)
✓ messages/es.json created (1.0s)
स्मार्ट लोकेल फ़ॉलबैक के लिए next-intl-localechain उपयोग करें—ब्राज़ीलियाई पुर्तगाली उपलब्ध न होने पर pt-BR यूज़र को अंग्रेज़ी पर फ़ॉलबैक करने के बजाय pt-PT अनुवाद दिखाई देते हैं।

अनुवाद की गुणवत्ता जाँचने की प्रक्रिया ऑटोमेट करें

i18n-validate से गुम कुंजियाँ और खराब प्लेसहोल्डर रिलीज़ से पहले पकड़ें। वास्तविक अनुवाद आने से पहले i18n-pseudo से नकली अनुवाद उपयोग करके अपने UI की जाँच करें।

Next.js i18n के लिए ओपन-सोर्स टूल

ये ओपन-सोर्स पैकेज Next.js अंतरराष्ट्रीयकरण कार्य-प्रवाह की आम समस्याएँ हल करते हैं।

next-intl-localechain

कोई अनुवाद न मिलने पर सामान्य next-intl सीधे आपके डिफ़ॉल्ट लोकेल पर फ़ॉलबैक करता है। ब्राज़ीलियाई पुर्तगाली यूज़र को पूरी तरह उपयोगी pt-PT अनुवाद के बजाय अंग्रेज़ी दिखाई देती है। next-intl-localechain स्मार्ट फ़ॉलबैक चेन जोड़ता है—यह संबंधित लोकेल के अनुवादों को डीप-मर्ज करता है, ताकि क्षेत्रीय यूज़र को हमेशा उपलब्ध सबसे करीबी अनुवाद दिखाई दे।

src/i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { withLocaleChain } from 'next-intl-localechain';

export default getRequestConfig(withLocaleChain({
  loadMessages: (locale) =>
    import(`../../messages/${locale}.json`).then(m => m.default),
  defaultLocale: 'en'
}));
लोकेल चेन में अनुवादों को अपने-आप डीप-मर्ज करता है
पुर्तगाली, स्पेनिश, फ़्रेंच, जर्मन और अन्य भाषाओं के लिए पहले से उपलब्ध चेन
गुम मैसेज फ़ाइलों को त्रुटि दिए बिना सुचारु रूप से छोड़ता है
एक लाइन में सेटअप—आपके मौजूदा getRequestConfig को wrap करता है
GitHub पर देखें

@i18n-agent/cli

टर्मिनल छोड़े बिना आपकी Next.js मैसेज फ़ाइलों का अनुवाद करने वाला कमांड-लाइन टूल। फ़ाइलों का सीधे अनुवाद करें, जॉब की स्थिति जाँचें और परिणाम डाउनलोड करें। पूरी तरह ऑटोमेटेड लोकलाइज़ेशन कार्य-प्रवाह के लिए यह API key authentication वाली CI/CD pipelines में काम करता है।

Terminal
# Install the CLI
npm install -g @i18n-agent/cli

# Authenticate
i18nagent login

# Translate your message files
i18nagent translate ./messages/en.json --lang de,ja,es

# Or use in CI/CD with an API key
export I18N_AGENT_API_KEY=your-key-here
i18nagent translate ./messages/en.json --lang de,ja,es
टर्मिनल से JSON, YAML, PO और अन्य i18n फ़ाइल फ़ॉर्मैट का अनुवाद करें
CI/CD के लिए तैयार—ऑटोमेटेड pipelines हेतु environment variable से authenticate करें
जॉब की स्थिति ट्रैक करें, विफल जॉब फिर से शुरू करें और परिणाम डाउनलोड करें
स्क्रिप्टिंग और ऑटोमेशन के लिए मशीन द्वारा पढ़ा जा सकने वाला JSON आउटपुट
GitHub पर देखें

आम समस्याएँ

"Unable to find next-intl locale"

Middleware रिक्वेस्ट से मेल नहीं खाया। जाँचें: क्या middleware.ts प्रोजेक्ट रूट में है? क्या matcher पैटर्न स्टैटिक फ़ाइलों को सही ढंग से बाहर रखता है? क्या लोकेल आपके routing config में शामिल है?

अनपेक्षित डायनेमिक रेंडरिंग

किसी page या layout में setRequestLocale(locale) मौजूद नहीं है। इसके बिना next-intl लोकेल पहचानने के लिए headers/cookies उपयोग करता है, जिससे डायनेमिक रेंडरिंग अनिवार्य हो जाती है और स्टैटिक जनरेशन रुक जाता है।

i18n के साथ Parallel Routes का काम न करना

Parallel routes (@modal) और intercepting routes ((.)photo) की [locale] डायनेमिक सेगमेंट के साथ ज्ञात असंगतियाँ हैं। इन उन्नत routing patterns के लिए समाधान के रूप में middleware-आधारित routing उपयोग करें।

भाषा बदलने पर मौजूदा रूट का खो जाना

लोकेल बदलते समय usePathname() से मौजूदा pathname सुरक्षित रखें और केवल locale segment बदलें। डायनेमिक रूट पैरामीटर के साथ सावधानी रखें—उन्हें नए लोकेल के लिए फिर से रिज़ॉल्व करना होगा।

सुझाई गई फ़ाइल संरचना

Project Structure
my-nextjs-app/
├── middleware.ts              # Locale routing (project root!)
├── next.config.mjs
├── messages/
│   ├── en.json                # Source messages
│   ├── de.json
│   └── ja.json
├── src/
│   ├── i18n/
│   │   ├── request.ts         # Message loading config
│   │   └── routing.ts         # Locale definitions
│   └── app/
│       └── [locale]/
│           ├── layout.tsx     # Root locale layout
│           ├── page.tsx       # Home page
│           ├── error.tsx      # Localized error page
│           ├── not-found.tsx  # Localized 404
│           └── about/
│               └── page.tsx
└── package.json

इनका भी अनुवाद करें:

i18n Agent अभी आज़माएँ

अपनी अनुवाद फ़ाइल यहाँ छोड़ें

JSON, YAML, PO, XML, CSV, Markdown, Properties

या ब्राउज़ करने के लिए क्लिक करें

लक्षित भाषाएँ

साइन अप की ज़रूरत नहींतुरंत अनुमान

next-intl-localechain के साथ लोकेल फ़ॉलबैक

जब pt-BR जैसे क्षेत्रीय लोकेल में कोई अनुवाद कुंजी नहीं होती, तो next-intl पहले पैरेंट लोकेल pt की जाँच करने के बजाय सीधे डिफ़ॉल्ट लोकेल पर चला जाता है।

Terminal
npm install next-intl-localechain
Configuration
import { withLocaleChain } from 'next-intl-localechain';

export default withLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
  loadMessages: (locale) => import(`./messages/${locale}.json`),
});

समर्थित फ़्रेमवर्क की पूरी सूची और पहले से उपलब्ध 75 चेन के लिए हमारी लोकेल फ़ॉलबैक गाइड देखें। Learn more →

अक्सर पूछे जाने वाले प्रश्न