Skip to main content

Ο πλήρης οδηγός διεθνοποίησης του Next.js

Ρυθμίστε το next-intl με το App Router, διαμορφώστε τη δρομολόγηση τοπικών ρυθμίσεων και αυτοματοποιήστε τις μεταφράσεις με AI.

1

Εγκαταστήστε το next-intl

Το next-intl είναι ένα ενιαίο πακέτο που διαχειρίζεται τη δρομολόγηση τοπικών ρυθμίσεων, τη φόρτωση μηνυμάτων και τα hook μετάφρασης για το Next.js App Router.

Terminal
npm install next-intl
Γιατί next-intl αντί για next-i18next; Το 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 (ο προεπιλεγμένος bundler στο Next.js 15) απαιτεί το experimental.turbo.resolveAlias στο next.config.js. Χωρίς αυτό, εμφανίζονται σφάλματα "Couldn't find next-intl config file".
3

Διαμορφώστε το middleware

Προσθέστε το middleware.ts για τη διαχείριση του εντοπισμού τοπικής ρύθμισης, της επανεγγραφής URL και των ανακατευθύνσεων. Το 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 για τη δημιουργία σελίδων για κάθε τοπική ρύθμιση κατά το build. Έτσι δημιουργείται η δομή URL /en/about, /de/about κ.λπ.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
ΠΡΕΠΕΙ να καλείτε τη setRequestLocale(locale) σε κάθε page.tsx και layout.tsx που χρησιμοποιεί μεταφράσεις. Χωρίς αυτήν, το Next.js επιστρέφει στη δυναμική απόδοση και η απόδοση του build υποβαθμίζεται σημαντικά.
5

Ενημερώστε τη ριζική διάταξη

Φορτώστε τα μηνύματα με τη getMessages() και μεταβιβάστε τα στη NextIntlClientProvider στη ριζική διάταξη τοπικής ρύθμισης. Ορίστε το χαρακτηριστικό lang του html από την παράμετρο 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. Η παράλειψή της προκαλεί δυσδιάκριτα σφάλματα στα client components, τα οποία είναι δύσκολο να εντοπιστούν.
6

Χρησιμοποιήστε μεταφράσεις στα components

Τα server components χρησιμοποιούν τη getTranslations (async, await). Τα client components χρησιμοποιούν τη useTranslations (hook). Επιλέξτε βάσει του σημείου απόδοσης του component — τα server components διατηρούν τις μεταφράσεις εντελώς εκτός του JavaScript bundle.

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 bundle του client, μειώνοντας τον χρόνο φόρτωσης για τους χρήστες.
7

Προσθέστε SEO: μεταδεδομένα και hreflang

Χρησιμοποιήστε τη generateMetadata για τη δημιουργία τίτλων και περιγραφών σελίδων ανά τοπική ρύθμιση. Προσθέστε alternates.languages για ετικέτες hreflang, ώστε οι μηχανές αναζήτησης να ανακαλύπτουν όλες τις γλωσσικές εκδόσεις κάθε σελίδας.

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, τα build μπορούν να δημιουργήσουν το localhost ως κανονικό URL, αν δεν έχει οριστεί το metadataBase. Να ορίζετε πάντα το metadataBase στη ριζική διάταξη με τον τομέα παραγωγής σας.
8

Διαχειριστείτε τις σελίδες σφαλμάτων και μη εύρεσης

Τα error.tsx και not-found.tsx χρειάζονται ειδική διαχείριση, επειδή μπορούν να αποδοθούν εκτός της κανονικής διάταξης τοπικής ρύθμισης. Το ριζικό not-found.tsx απαιτεί δική του ρύθμιση παρόχου i18n για την εμφάνιση τοπικοποιημένων μηνυμάτων σφάλματος.

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() καλείται ρητά στον κώδικά σας. Οι άγνωστες διαδρομές χωρίς αντίστοιχη σελίδα εμφανίζουν την προεπιλεγμένη σελίδα 404 του Next.js και όχι την τοπικοποιημένη έκδοσή σας.
9

Αυτοματοποιήστε τις μεταφράσεις

Αφού ολοκληρώσετε τη ρύθμιση i18n, μεταφράστε τα αρχεία μηνυμάτων σας με AI απευθείας από το IDE ή χρησιμοποιήστε το i18n Agent CLI στο pipeline CI/CD για αυτοματοποιημένη μετάφραση σε κάθε διάθεση έκδοσης.

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. Δοκιμάστε το UI σας με ψευδομεταφράσεις μέσω του i18n-pseudo πριν φτάσουν οι πραγματικές μεταφράσεις.

Εργαλεία ανοικτού κώδικα για το 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
Προβολή στο GitHub

@i18n-agent/cli

Ένα εργαλείο γραμμής εντολών για τη μετάφραση των αρχείων μηνυμάτων του Next.js χωρίς να βγαίνετε από το τερματικό. Μεταφράστε αρχεία απευθείας, ελέγξτε την κατάσταση εργασιών και πραγματοποιήστε λήψη των αποτελεσμάτων. Λειτουργεί σε pipeline CI/CD με έλεγχο ταυτότητας μέσω API key για πλήρως αυτοματοποιημένες ροές εργασίας τοπικοποίησης.

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 — έλεγχος ταυτότητας μέσω μεταβλητής περιβάλλοντος για αυτοματοποιημένα pipeline
Παρακολουθήστε την κατάσταση εργασιών, συνεχίστε τις αποτυχημένες εργασίες και πραγματοποιήστε λήψη των αποτελεσμάτων
Έξοδος JSON αναγνώσιμη από μηχανές για δέσμες ενεργειών και αυτοματισμούς
Προβολή στο GitHub

Συνηθισμένες παγίδες

"Unable to find next-intl locale"

Το middleware δεν αντιστοιχίστηκε στο αίτημα. Ελέγξτε τα εξής: βρίσκεται το middleware.ts στον ριζικό κατάλογο του έργου; Εξαιρεί σωστά το μοτίβο matcher τα στατικά αρχεία; Περιλαμβάνεται η τοπική ρύθμιση στη διαμόρφωση δρομολόγησης;

Μη αναμενόμενη δυναμική απόδοση

Η setRequestLocale(locale) λείπει από μια σελίδα ή διάταξη. Χωρίς αυτήν, το next-intl χρησιμοποιεί κεφαλίδες/cookie για τον εντοπισμό της τοπικής ρύθμισης, γεγονός που επιβάλλει δυναμική απόδοση και εμποδίζει τη στατική δημιουργία.

Οι παράλληλες διαδρομές δεν λειτουργούν με το i18n

Οι παράλληλες διαδρομές (@modal) και οι διαδρομές παρεμβολής ((.)photo) παρουσιάζουν γνωστές ασυμβατότητες με το δυναμικό τμήμα [locale]. Χρησιμοποιήστε δρομολόγηση μέσω middleware ως λύση για αυτά τα προηγμένα μοτίβα δρομολόγησης.

Η αλλαγή γλώσσας χάνει την τρέχουσα διαδρομή

Κατά την αλλαγή τοπικής ρύθμισης, διατηρήστε το τρέχον pathname με τη usePathname() και αντικαταστήστε μόνο το τμήμα της τοπικής ρύθμισης. Προσέξτε τις παραμέτρους δυναμικών διαδρομών — πρέπει να επιλυθούν ξανά για τη νέα τοπική ρύθμιση.

Προτεινόμενη δομή αρχείων

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`),
});

Δείτε τον οδηγό μας για τις εφεδρικές τοπικές ρυθμίσεις, με την πλήρη λίστα υποστηριζόμενων framework και 75 ενσωματωμένες αλυσίδες. Learn more →

Συχνές ερωτήσεις