שאלו את שאלתכם וקבלו סיכום של המסמך על ידי הפניה לדף הזה ולספק ה-AI שתבחרו
היסטוריית גרסאות
- Initial versionv7.0.01.11.2025
התוכן של הדף הזה תורגם באמצעות AI.
צפייה בגרסה האחרונה של התוכן המקורי באנגליתאם יש לכם רעיון לשיפור התיעוד הזה, אל תהססו לתרום על ידי הגשת Pull Request ב-GitHub.
קישור GitHub לתיעודהעתקת ה-Markdown של המסמך ללוח
How to internationalize your Next.js application using next-intl in 2026
Table of Contents
What is next-intl?
next-intl is a popular internationalization (i18n) library designed specifically for Next.js App Router. It provides a seamless way to build multilingual Next.js applications with excellent TypeScript support and built-in optimizations.
If you prefer, you can also refer to the next-i18next guide, or directly using Intlayer.
See the comparison in next-i18next vs next-intl vs Intlayer.
To understand where these libraries come from, read the history of JavaScript i18n.
What the benchmark says about next-intl on Next.js
Before implementing translations, understanding the performance profile of next-intl is essential. The i18n benchmark evaluates the same 10-page, 10-locale Next.js application across different setups and libraries to measure real bundle footprint, string leakage, and hydration overhead.
מדד
טעינת JSON דינמית
טעינה עצלה של תרגומים בזמן ריצה
JSON תחום (namespacing)
מרחבי שמות תרגום לכל דף
מהו המדד הזה?
הגודל הכולל לאחר דחיסת gzip של ה-bundle של ספריית הבינאום. הוא כולל רק את ה-provider ואת לוגיקת שליפת התוכן לאחר tree-shaking ומיזעור.
למה זה חשוב?
ספרייה קטנה יותר מקטינה את מטען ה-JavaScript ההתחלתי, מה שמוביל לזמני הורדה והרצה מהירים יותר בצד הלקוח.
הצגה כ
Key figures for next-intl on Next.js (gzip):
פתיחת הטבלה בחלון כדי לראות את כל תוכן הנתונים בבירור
| Setup | Library size | Page JS avg | Other-locale leak | Other-page leak |
|---|---|---|---|---|
| Base (no i18n) | - | 141.0 KB | 0.0% | 0.0% |
next-intl | 14.7 KB | 153.6 KB | 4.2% | 89.8% |
@intlayer/next-intl (compat) | 8.0 KB | 148.7 KB | 0.0% | 0.0% |
next-intlayer (native Intlayer) | 5.5 KB | 141.3 KB | 0.0% | 0.0% |
What to take away:
- Avoid global message catalogs: In standard setups where all messages are loaded in root layouts, ~89.8% of translated content sent to the browser belongs to other pages. Using
pick(messages, ['namespace'])per route removes this leakage, though it requires manual maintenance. - Runtime weight: The
next-intlruntime adds ~14.7 KB gzip to each page. For existingnext-intlapps, the@intlayer/next-intlcompat adapter preserves the same hooks (useTranslations,useFormatter, etc.) while dropping runtime size to ~8.0 KB with 0% leak. Nativenext-intlayerfurther reduces footprint to 5.5 KB.
See the full data: Next.js benchmark report, and the benchmark repository.
Feature comparison on Next.js
How next-intl compares with next-i18next and Intlayer on the features a Next.js App Router project usually needs:
פתיחת הטבלה בחלון כדי לראות את כל תוכן הנתונים בבירור
| Feature | next-intlayer (Intlayer) | next-intl | next-i18next |
|---|---|---|---|
| Translations near components | ✅ Content co-located with each component | ❌ Centralized JSON | ❌ Centralized JSON |
| TypeScript integration | ✅ Auto-generated strict types | ✅ Good, via AppConfig augmentation | ⚠️ Basic |
| Missing translation detection | ✅ TypeScript errors and build-time warnings | ⚠️ Runtime fallback | ⚠️ Runtime fallback |
| Rich content (JSX, Markdown) | ✅ Direct support | ⚠️ Tags via t.rich, no Markdown | ⚠️ Tags via <Trans> |
| AI translation | ✅ Your own provider and API key, with app context | ❌ No | ❌ No |
| Visual editor / CMS | ✅ Local visual editor + optional CMS | ❌ Via external platforms | ❌ Via external platforms |
| Localized routing | ✅ Built-in (Next.js and Vite) | ✅ Built-in [locale] segment | ✅ Built-in |
| Pluralization | ✅ Enumeration-based | ✅ ICU | ✅ Suffix-based (_one, _other) |
| Formatting (dates, numbers, currencies) | ✅ Intl-based formatters | ✅ useFormatter | ✅ Intl-based |
| Content formats | ✅ .ts, .tsx, .js, .json, .md, .yaml | ✅ .json, .js, .ts | ⚠️ .json |
| ICU MessageFormat | ✅ Via format: "icu" | ✅ Native | ⚠️ Via i18next-icu |
| SEO helpers (hreflang, sitemap) | ✅ Metadata, sitemap and robots.txt helpers | ✅ Good | ✅ Good |
| Server Components | ✅ Direct access in any Server Component | ⚠️ Pass t or await getTranslations() per component | ⚠️ Pass t down the component tree |
| Per-component tree-shaking | ✅ At build time (Babel / SWC) | ⚠️ Manual, with pick() per route | ⚠️ Manual, with namespaces per route |
| Lazy loading | ✅ Per locale and per dictionary | ✅ Per locale, namespaces managed by hand | ✅ Per locale, namespaces managed by hand |
| Runtime size (gzip, benchmark) | 4.9 KB | 14.7 KB | 19.7 KB |
| Missing translations in CI | ✅ npx intlayer test | ⚠️ Not built-in | ⚠️ Not built-in, saveMissing at runtime |
| Ecosystem / community | ⚠️ Smaller, growing fast | ✅ Large | ✅ Very large |
Runtime sizes come from the Next.js benchmark. For a detailed discussion, read next-i18next vs next-intl vs Intlayer.
Practices you should follow
Before we dive into the implementation, here are some practices you should follow:
- Set HTML
langanddirattributes In your layout, computedirusinggetLocaleDirection(locale)and set<html lang={locale} dir={dir}>for proper accessibility and SEO. - Split messages by namespace
Organize JSON files per locale and namespace (e.g.,
common.json,about.json) to load only what you need. - Minimize client payload
On pages, send only required namespaces to
NextIntlClientProvider(e.g.,pick(messages, ['common', 'about'])). - Prefer static pages Use static page as much as possible for better performance and SEO.
- I18n in server components
Server components, like pages or all components not marked as
clientare statics and can be pre-rendered at build time. So we will have to pass the translation functions to them as props. - Set up TypeScript types For your locales to ensure type safety throughout your application.
- Proxy for redirection Use a proxy to handle the locale detection and routing and redirect the user to the appropriate locale-prefixed URL.
- Internationalization of your metadata, sitemap, robots.txt
Internationalize your metadata, sitemap, robots.txt using the
generateMetadatafunction provided by Next.js to ensure a better discovery by search engines in all locales. - Localize Links
Localize Links using the
Linkcomponent to redirect the user to the appropriate locale-prefixed URL. It's important to ensure the discovery of your pages in all locales. - Automate tests and translations Automate tests and translations help loosing time to maintain your multilingual application.
See our doc listing everything you need to know about internationalization and SEO: Internationalization (i18n) with next-intl.
Step-by-Step Guide to Set Up next-intl in a Next.js Application
See Application Template on GitHub.
Here's the project structure we'll be creating:
העתקת הקוד ללוח
Install Dependencies
Install the necessary packages using npm:
bashהעתקת קודהעתקת הקוד ללוח
- next-intl: The core internationalization library for Next.js App Router that provides hooks, server functions, and client providers for managing translations.
Configure Your Project
Create a configuration file that defines your supported locales and sets up next-intl's request configuration. This file serves as the single source of truth for your i18n setup and ensures type safety throughout your application.
Centralizing your locale configuration prevents inconsistencies and makes it easier to add or remove locales in the future. The
getRequestConfigfunction runs on every request and loads only the translations needed for each page, enabling code-splitting and reducing bundle size.src/i18n.tsהעתקת קודהעתקת הקוד ללוח
Define Dynamic Locale Routes
Set up dynamic routing for locales by creating a
[locale]directory in your app folder. This allows Next.js to handle locale-based routing where each locale becomes a URL segment (e.g.,/en/about,/fr/about).Using dynamic routes enables Next.js to generate static pages for all locales at build time, improving performance and SEO. The layout component sets the HTML
langanddirattributes based on the locale, which is crucial for accessibility and search engine understanding.src/app/[locale]/layout.tsxהעתקת קודהעתקת הקוד ללוח
src/app/[locale]/about/page.tsxהעתקת קודהעתקת הקוד ללוח
Create Your Translation Files
Create JSON files for each locale and namespace. This structure allows you to organize translations logically and load only what you need for each page.
Organizing translations by namespace (e.g.,
common.json,about.json) enables code splitting and reduces bundle size. You only load the translations needed for each page, improving performance.locales/en/common.jsonהעתקת קודהעתקת הקוד ללוח
locales/fr/common.jsonהעתקת קודהעתקת הקוד ללוח
locales/en/about.jsonהעתקת קודהעתקת הקוד ללוח
locales/fr/about.jsonהעתקת קודהעתקת הקוד ללוח
Utilize Translations in Your Pages
Create a page component that loads translations on the server and passes them to both server and client components. This ensures that translations are loaded before rendering and prevents content flashing.
Server-side loading of translations improves SEO and prevents FOUC (Flash of Untranslated Content). By using
pickto send only required namespaces to the client provider, we minimize the JavaScript bundle sent to the browser.src/app/[locale]/about/page.tsxהעתקת קודהעתקת הקוד ללוח
Use Translations in Client Components
Client components can use the
useTranslationsanduseFormatterhooks to access translations and formatting functions. These hooks read from theNextIntlClientProvidercontext.Client components need React hooks to access translations. The
useTranslationsanduseFormatterhooks integrate seamlessly with next-intl and provide reactive updates when the locale changes.Don't forget to add the required namespaces to the page's client messages (only include the namespaces your client components actually need).
src/components/ClientComponent.tsxהעתקת קודהעתקת הקוד ללוח
Use Translations in Server Components
Server components cannot use React hooks, so they receive translations and formatters via props from their parent components. This approach keeps server components synchronous and allows them to be nested inside client components.
Server components that might be nested under client boundaries need to be synchronous. By passing translated strings and formatted values as props, we avoid async operations and ensure proper rendering. Pre-compute translations and formatting in the parent page component.
src/components/ServerComponent.tsxהעתקת קודהעתקת הקוד ללוח
In your page/layout, use
getTranslationsandgetFormatterfromnext-intl/serverto pre-compute translations and formatting, then pass them as props to server components.Change the language of your content
אופציונליTo change the language of your content with next-intl, render locale-aware links that point to the same pathname while switching locale. The provider rewrites URLs automatically, so you only have to target the current route.
src/components/LocaleSwitcher.tsxהעתקת קודהעתקת הקוד ללוח
Use the localized Link component
אופציונליnext-intlprovides a subpackagenext-intl/navigationthat contains a localized link component that automatically applies the active locale. We already extracted it for you in the@/i18nfile, so you can use it like this:src/components/MyComponent.tsxהעתקת קודהעתקת הקוד ללוח
Access the active locale inside Server Actions
אופציונליServer Actions can read the current locale using
next-intl/server. This is useful for sending localized emails or storing language preferences alongside submitted data.src/app/actions/get-current-locale.tsהעתקת קודהעתקת הקוד ללוח
getLocalereads the locale set bynext-intlproxy, so it works anywhere on the server: Route Handlers, Server Actions, and edge functions.Internationalize Your Metadata
אופציונליTranslating content is important, but the main goal of internationalization is to make your website more visible to the world. I18n is an incredible lever to improve your website visibility through proper SEO.
Properly internationalized metadata helps search engines understand what languages are available on your pages. This includes setting hreflang meta tags, translating titles and descriptions, and ensuring canonical URLs are correctly set for each locale.
src/app/[locale]/about/layout.tsxהעתקת קודהעתקת הקוד ללוח
Internationalize Your Sitemap
אופציונליGenerate a sitemap that includes all locale versions of your pages. This helps search engines discover and index all language versions of your content.
A properly internationalized sitemap ensures search engines can find and index all language versions of your pages. This improves visibility in international search results.
src/app/sitemap.tsהעתקת קודהעתקת הקוד ללוח
Internationalize Your robots.txt
אופציונליCreate a robots.txt file that properly handles all locale versions of your protected routes. This ensures that search engines don't index admin or dashboard pages in any language.
Properly configuring robots.txt for all locales prevents search engines from indexing sensitive pages when your routes are different for each locale.
src/app/robots.tsהעתקת קודהעתקת הקוד ללוח
Set Up Proxy for Locale Routing
אופציונליCreate a proxy to automatically detect the user's preferred locale and redirect them to the appropriate locale-prefixed URL. next-intl provides a convenient proxy function that handles this automatically.
Proxy ensures that users are automatically redirected to their preferred language when they visit your site. It also saves the user's preference for future visits, improving user experience.
src/proxy.tsהעתקת קודהעתקת הקוד ללוח
Set Up TypeScript Types for the Locale
אופציונליSetting up TypeScript will help you to get autocompletion and type safety for your keys.
For that, you can create a global.ts file in your project root and add the following code:
global.tsהעתקת קודהעתקת הקוד ללוח
This code will use Module Augmentation to add the locales and messages to the next-intl AppConfig type.
Automate Your Translations Using Intlayer
אופציונליIntlayer is a free and open-source library designed to assist the localization process in your application. While next-intl handles the translation loading and management, Intlayer helps automate the translation workflow.
Managing translations manually can be time-consuming and error-prone. Intlayer automates translation testing, generation, and management, saving you time and ensuring consistency across your application.
Intlayer will allows your to:
Declare your content where you want in your codebase Intlayer allows to declare your content where you want in your codebase using
.content.{ts|js|json}files. It will allow a better organization of your content, ensuring better readability and maintainability of your codebase.Test missing translations Intlayer provide test functions to that can be integrated in your CI/CD pipeline, or in your unit tests. Learn more about testing your translations.
Automate your translations, Intlayer provide a CLI and a VSCode extension to automate your translations. It can be integrated in your CI/CD pipeline. Learn more about automating your translations. You can use your own API key, and the AI provider of your choice. It also provide context aware translations, see fill content.
Connect external content Intlayer allows you to connect your content to an external content management system (CMS). To fetch it in a optimized way and insert it in your JSON resources. Learn more about fetching external content.
Visual editor Intlayer offers an free visual editor to edit your content using a visual editor. Learn more about visual editing your translations.
And more. To discover all the features provided by Intlayer, please refer to the Interest of Intlayer documentation.
For detailed performance benchmarks and comparisons, see:
תגובות
עדיין אין תגובות. היו הראשונים לשתף את מחשבותיכם.
