שאלו את שאלתכם וקבלו סיכום של המסמך על ידי הפניה לדף הזה ולספק ה-AI שתבחרו
היסטוריית גרסאות
- "עדכון לארכיטקטורת Next.js >= 9.4.0"v9.4.022.8.2026
- "עדכון השימוש ב-API של useIntlayer ב-Solid לגישה ישירה למאפיינים"v8.9.04.5.2026
- "הוספת פקודת init"v7.5.930.12.2025
- "הוספת אזכור של `x-default` באובייקט `alternates`"v7.0.61.11.2025
- "היסטוריה ראשונית"v7.0.029.6.2025
התוכן של הדף הזה תורגם באמצעות AI.
צפייה בגרסה האחרונה של התוכן המקורי באנגליתאם יש לכם רעיון לשיפור התיעוד הזה, אל תהססו לתרום על ידי הגשת Pull Request ב-GitHub.
קישור GitHub לתיעודהעתקת ה-Markdown של המסמך ללוח
תרגמו את אתר ה-Next.js 16 שלכם באמצעות Intlayer
ראו את תבנית האפליקציה (Application Template) ואת תבנית האפליקציה ללא נתיב שפה (Application Template without locale path) ב-GitHub.
תוכן עניינים
למה לבחור ב-Intlayer על פני חלופות?
בהשוואה לפתרונות מובילים כמו next-intl או i18next, Intlayer הוא פתרון המגיע עם אופטימיזציות מובנות כגון:
Intlayer מותאם לעבודה עם Server Components לרינדור יעיל ותואם באופן מלא ל-Turbopack. הוא אינו חוסם רינדור סטטי ומציע middleware לצד כל התכונות הנדרשות לבינאום (i18n) בהיקף נרחב.
Intlayer תואם ל-Next.js 12, 13, 14, 15 ו-16. אם אתם משתמשים ב-Next.js Pages Router, תוכלו לעיין במדריך זה. ניתוב לפי שפה (Locale routing) שימושי עבור SEO, גודל ה-bundle וביצועים. שני המבנים, עם ובלי ניתוב נתיבי שפה, נתמכים ומכוסים במדריך זה. עבור Next.js 12, 13, 14 ו-15 עם App Router, עיינו במדריך זה.
במקום לטעון קובצי JSON עצומים לתוך הדפים שלכם, טענו אך ורק את התוכן הנחוץ. Intlayer מסייע להפחית את גודל ה-bundle והדפים שלכם בעד 50%.
הגדרת היקף (scoping) התוכן של האפליקציה שלכם מפשטת את התחזוקה של אפליקציות בקנה מידה גדול. תוכלו לשכפל או למחוק תיקיית פיצ'ר בודדת ללא הנטל המחשבתי של סקירת כל בסיס קוד התוכן שלכם. בנוסף, Intlayer הוא בעל טיפוסיות מלאה (fully typed) כדי להבטיח את דיוק התוכן שלכם.
הצמדת התוכן (co-location) מפחיתה את ההקשר (context) הדרוש למודלי שפה גדולים (LLMs). בנוסף, Intlayer מגיע עם חבילת כלים, כגון CLI לבדיקת תרגומים חסרים, LSP, MCP ו-כישורי סוכן (agent skills), כדי להפוך את חוויית המפתח (DX) לחלקה אף יותר עבור סוכני AI.
השתמשו באוטומציה כדי לתרגם בצינור ה-CI/CD שלכם באמצעות ה-LLM לבחירתכם, בעלות ספק ה-AI שלכם. Intlayer מציע גם מהדר (compiler) לאוטומציה של חילוץ תוכן, וכן פלטפורמת אינטרנט המסייעת לתרגם ברקע.
חיבור קובצי JSON ענקיים לרכיבים עלול להוביל לבעיות ביצועים ותגובתיות. Intlayer ממטב את טעינת התוכן שלכם בזמן הבנייה (build time).
יותר מסתם פתרון i18n, Intlayer מספק עורך ויזואלי באחסון עצמי (self-hosted) ו-CMS מלא כדי לעזור לכם לנהל את התוכן הרב-לשוני שלכם בזמן אמת, מה שהופך את שיתוף הפעולה עם מתרגמים, כותבי תוכן וחברי צוות אחרים לחלק ופשוט. ניתן לאחסן תוכן באופן מקומי ו/או מרחוק.
מדריך שלב אחר שלב להגדרת Intlayer באפליקציית Next.js
התקנת תלויות
התקינו את החבילות הנדרשות באמצעות npm:
bashהעתקת קודהעתקת הקוד ללוח
הדגל
--interactiveהוא אופציונלי. השתמשו ב-intlayer-cli initאם אתם סוכן AI.פקודה זו תזהה את הסביבה שלכם ותתקין את החבילות הנדרשות. לדוגמה:
bashהעתקת קודהעתקת הקוד ללוח
intlayer
חבילת הליבה המספקת כלי בינאום לניהול תצורה, תרגום, הצהרת תוכן, טרנספילציה ו-פקודות CLI.
next-intlayer
החבילה המשלבת את Intlayer עם Next.js. היא מספקת context providers ו-hooks עבור בינאום ב-Next.js. בנוסף, היא כוללת את הפלאגין של Next.js לשילוב Intlayer עם Webpack או Turbopack, כמו גם proxy לזיהוי השפה המועדפת על המשתמש, ניהול עוגיות וטיפול בהפניות URL.
הגדרת הפרויקט שלכם
בחרו האם האפליקציה שלכם צריכה להשתמש בנתיבי URL מקומיים (למשל
/en/about,/fr/about) או להגיש תוכן ללא מקטע שפה בנתיב (למשל/about, תוך זיהוי השפה באמצעות עוגיות, כותרות או פרמטרי שאילתה).ארכיטקטורה
בארכיטקטורה זו, כל הדפים המקומיים מקוננים תחת מקטע ניתוב דינמי מסוג
[locale]. גישה זו מומלצת עבור SEO ורינדור סטטי מכיוון שלכל שפה יש כתובת URL ייחודית וייעודית:bashהעתקת קודהעתקת הקוד ללוח
תצורה
צרו קובץ תצורה
intlayer.config.tsכדי להצהיר על השפות הנתמכות באפליקציה שלכם:intlayer.config.tsהעתקת קודהעתקת הקוד ללוח
import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // השפות הנוספות שלכם ], defaultLocale: Locales.ENGLISH, }, routing: { mode: "prefix-no-default", // או `prefix-all` }, }; export default config;ארכיטקטורה
בארכיטקטורה זו, הנתיבים אינם כוללים מקטע דינמי של
[locale]בנתיב ה-URL. כל הדפים נמצאים ישירות תחתsrc/app/, והשפה נקבעת באמצעות עוגיות, כותרות או פרמטרי שאילתה. פתרון זה אידיאלי עבור לוחות בקרה (dashboards), כלים פנימיים או אפליקציות הדורשות אימות שבהן קידומת לכל כתובת URL אינה נחוצה:bashהעתקת קודהעתקת הקוד ללוח
תצורה
הגדירו את המאפיין
routing.modeל-"search-params"(למשל/about?locale=fr) או"no-prefix"כדי להגיש תוכן ללא קידומת נתיב:intlayer.config.tsהעתקת קודהעתקת הקוד ללוח
import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // השפות הנוספות שלכם ], defaultLocale: Locales.ENGLISH, }, routing: { mode: "search-params", // או `no-prefix`, שימושי לזיהוי באמצעות middleware / proxy }, }; export default config;באמצעות קובץ תצורה זה, תוכלו להגדיר כתובות URL מקומיות, הפניות proxy, שמות עוגיות, את המיקום והסיומת של הצהרות התוכן שלכם, לבטל יומני רישום של Intlayer במסוף ועוד. לרשימה מלאה של הפרמטרים הזמינים, עיינו בתיעוד התצורה.
שילוב Intlayer בהגדרות Next.js
הגדירו את תצורת Next.js שלכם לשימוש ב-Intlayer:
next.config.tsהעתקת קודהעתקת הקוד ללוח
import type { NextConfig } from "next"; import { withIntlayer } from "next-intlayer/server"; const nextConfig: NextConfig = {/* אפשרויות תצורה כאן */}; export default withIntlayer(nextConfig);הפלאגין של Next.js בשם
withIntlayer()משמש לשילוב Intlayer ב-Next.js. הוא מבטיח את בניית קובצי הצהרת התוכן ומנטר אותם במצב פיתוח. הוא מגדיר משתני סביבה של Intlayer בתוך סביבות Webpack או Turbopack. בנוסף, הוא מספק כינויים (aliases) למיטוב ביצועים ומבטיח תאימות ל-Server Components.הפונקציה
withIntlayer()היא פונקציה מבוססת Promise. היא מאפשרת להכין את מילוני Intlayer לפני תחילת הבנייה. אם ברצונכם להשתמש בה לצד פלאגינים אחרים, תוכלו להמתין לה באמצעות await. דוגמה:tsהעתקת קודהעתקת הקוד ללוח
אם ברצונכם להשתמש בה באופן סינכרוני, תוכלו להשתמש בפונקציה
withIntlayerSync(). דוגמה:tsהעתקת קודהעתקת הקוד ללוח
Intlayer מזהה באופן אוטומטי האם הפרויקט שלכם משתמש ב-webpack או ב-Turbopack על סמך דגלי שורת הפקודה
--webpack,--turboאו--turbopack, כמו גם גרסת ה-Next.js הנוכחית שלכם.החל מ-
next>=16, אם אתם משתמשים ב-Rspack, עליכם להורות במפורש ל-Intlayer להשתמש בתצורת webpack על ידי השבתת Turbopack:tsהעתקת קודהעתקת הקוד ללוח
הגדרת נתיבי שפה דינמיים
הסירו את כל התוכן מ-
RootLayoutוהחליפו אותו בקוד הבא:src/app/layout.tsxהעתקת קודהעתקת הקוד ללוח
import type { PropsWithChildren, FC } from "react"; import "./globals.css"; const RootLayout: FC<PropsWithChildren> = ({ children }) => ( // עדיין תוכלו לעטוף את הילדים עם ספקים אחרים, כגון `next-themes`, `react-query`, `framer-motion` וכו'. <>{children}</> ); export default RootLayout;השארת רכיב ה-
RootLayoutריק מאפשרת להגדיר את המאפייניםlangו-dirבתגית ה-<html>.כדי ליישם ניתוב דינמי, ספקו את הנתיב עבור השפה על ידי הוספת layout חדש בתוך תיקיית
[locale]:src/app/[locale]/layout.tsxהעתקת קודהעתקת הקוד ללוח
import { type NextLayoutIntlayer } from "next-intlayer"; import { IntlayerProvider } from "next-intlayer/server"; import { Inter } from "next/font/google"; import { getHTMLTextDir } from "intlayer"; const inter = Inter({ subsets: ["latin"] }); const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => { const { locale } = await params; return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <body className={inter.className}> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> </body> </html> ); }; export default LocaleLayout;רכיב
IntlayerProviderיחיד מכסה את שני חלקי העץ: הוא מזין את ה-context השרתי ברמת הבקשה הנקרא על ידי ה-hooks בשרת, ומרכיב את ה-client provider כך שרכיבי הלקוח יקבלו את אותה השפה.src/app/[locale]/layout.tsxהעתקת קודהעתקת הקוד ללוח
import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer"; import { Inter } from "next/font/google"; import { getHTMLTextDir } from "intlayer"; const inter = Inter({ subsets: ["latin"] }); const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => { const { locale } = await params; return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <body className={inter.className}> <IntlayerClientProvider locale={locale}> {children} </IntlayerClientProvider> </body> </html> ); }; export default LocaleLayout;מקטע הנתיב
[locale]משמש להגדרת השפה. דוגמה:/en-US/aboutיתייחס ל-en-USו-/fr/aboutל-fr.בשלב זה, תיתקלו בשגיאה:
Error: Missing <html> and <body> tags in the root layout.. דבר זה צפוי מכיוון שהקובץ/app/page.tsxאינו בשימוש עוד וניתן להסירו. במקומו, מקטע הנתיב[locale]יפעיל את הדף/app/[locale]/page.tsx. כתוצאה מכך, הדפים יהיו נגישים דרך נתיבים כמו/en,/fr,/esבדפדפן שלכם. כדי להגדיר את שפת ברירת המחדל כדף השורש, עיינו בהגדרת ה-proxyבשלב 7.לאחר מכן, יישמו את הפונקציה
generateStaticParamsב-Layout של האפליקציה שלכם.src/app/[locale]/layout.tsxהעתקת קודהעתקת הקוד ללוח
export { generateStaticParams } from "next-intlayer"; // שורה להוספה const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => { /*... שאר הקוד*/ }; export default LocaleLayout;generateStaticParamsמבטיח שהאפליקציה שלכם תבנה מראש את הדפים הנדרשים עבור כל השפות, ובכך תפחית את זמן החישוב בזמן ריצה ותשפר את חוויית המשתמש. לפרטים נוספים, עיינו בתיעוד של Next.js לגבי generateStaticParams.Intlayer פועל עם
export const dynamic = 'force-static';כדי להבטיח שהדפים ייבנו מראש עבור כל השפות.בארכיטקטורה ללא נתיבי שפה, אין תיקיית
[locale]. הגדירו אתsrc/app/layout.tsxישירות כדי לקרוא את השפה מהקשר הבקשה ועטפו את האפליקציה שלכם ב-IntlayerProvider:src/app/layout.tsxהעתקת קודהעתקת הקוד ללוח
import type { Metadata } from "next"; import type { ReactNode } from "react"; import "./globals.css"; import { getHTMLTextDir, getIntlayer } from "intlayer"; import { getLocale, IntlayerProvider } from "next-intlayer/server"; export { generateStaticParams } from "next-intlayer"; export const generateMetadata = async (): Promise<Metadata> => { const locale = await getLocale(); const { title, description, keywords } = getIntlayer("metadata", locale); return { title, description, keywords, }; }; const RootLayout = async ({ children, }: Readonly<{ children: ReactNode; }>) => { const locale = await getLocale(); return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> </body> </html> ); }; export default RootLayout;רכיב
IntlayerProviderיחיד מכסה את שני חלקי העץ: הוא מזין את ה-context השרתי ברמת הבקשה הנקרא על ידי ה-hooks בשרת, ומרכיב את ה-client provider כך שרכיבי הלקוח יקבלו את אותה השפה.src/app/layout.tsxהעתקת קודהעתקת הקוד ללוח
import type { Metadata } from "next"; import type { ReactNode } from "react"; import "./globals.css"; import { IntlayerProvider, LocalPromiseParams } from "next-intlayer"; import { getHTMLTextDir, getIntlayer } from "intlayer"; import { getLocale } from "next-intlayer/server"; export { generateStaticParams } from "next-intlayer"; export const generateMetadata = async (): Promise<Metadata> => { const locale = await getLocale(); const { title, description, keywords } = getIntlayer("metadata", locale); return { title, description, keywords, }; }; const RootLayout = async ({ children, }: Readonly<{ children: ReactNode; }>) => { const locale = await getLocale(); return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> </body> </html> ); }; export default RootLayout;הצהרת התוכן שלכם
צרו ונהלו את הצהרות התוכן שלכם כדי לאחסן תרגומים:
src/app/[locale]/page.content.tsהעתקת קודהעתקת הקוד ללוח
import { t, type Dictionary } from "intlayer"; const pageContent = { key: "page", content: { getStarted: { main: t({ he: "התחילו על ידי עריכת", en: "Get started by editing", fr: "Commencez par éditer", es: "Comience por editar", }), pageLink: "src/app/page.tsx", }, }, } satisfies Dictionary; export default pageContent;הצהרות התוכן שלכם יכולות להיות מוגדרות בכל מקום באפליקציה שלכם, כל עוד הן נכללות בתיקייה
contentDir(כברירת מחדל,./src) ותואמות לסיומת קובץ הצהרת התוכן (כברירת מחדל,.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).לפרטים נוספים, עיינו בתיעוד הצהרת תוכן.
שימוש בתוכן בקוד שלכם
גשו למילוני התוכן שלכם בכל רחבי האפליקציה:
src/app/[locale]/page.tsxהעתקת קודהעתקת הקוד ללוח
import type { FC } from "react"; import { ClientComponentExample } from "@components/ClientComponentExample"; import { ServerComponentExample } from "@components/ServerComponentExample"; import { type NextPageIntlayer, useIntlayer } from "next-intlayer"; const PageContent: FC = () => { const content = useIntlayer("page"); return ( <> <p>{content.getStarted.main}</p> <code>{content.getStarted.pageLink}</code> </> ); }; const Page: NextPageIntlayer = () => ( <> <PageContent /> <ServerComponentExample /> <ClientComponentExample /> </> ); export default Page;IntlayerProviderמורכב פעם אחת, ב-locale layout. הוא מספק את השפה הן ל-Server Components והן ל-Client Components, כך שדפים אינם צריכים לעטוף את עצמם יותר.- ה-hooks בשרת פותרים את השפה בסדר הבא: השפה המועברת באתר הקריאה, לאחר מכן ה-context השרתי שהוזן על ידי ה-provider, ולבסוף השפה הנישאת על ידי הבקשה (הכותרת
x-intlayer-localeהמוגדרת על ידי ה-proxy של Intlayer, ולאחר מכן עוגיית השפה). שלב אחרון זה שומר על נכונות התוכן בניווט בצד הלקוח המרנדר מחדש רק את מקטע הדף, שבו ה-layout (ויחד איתו ה-provider) אינו רץ מחדש.
src/app/[locale]/page.tsxהעתקת קודהעתקת הקוד ללוח
import type { FC } from "react"; import { ClientComponentExample } from "@components/ClientComponentExample"; import { ServerComponentExample } from "@components/ServerComponentExample"; import { type NextPageIntlayer } from "next-intlayer"; import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server"; const PageContent: FC = () => { const content = useIntlayer("page"); return ( <> <p>{content.getStarted.main}</p> <code>{content.getStarted.pageLink}</code> </> ); }; const Page: NextPageIntlayer = async ({ params }) => { const { locale } = await params; return ( <IntlayerServerProvider locale={locale}> <PageContent /> <ServerComponentExample /> <ClientComponentExample /> </IntlayerServerProvider> ); }; export default Page;IntlayerClientProviderמשמש לספק את השפה לרכיבי צד לקוח. ניתן למקם אותו בכל רכיב אב, כולל ב-layout. עם זאת, מיקומו ב-layout מומלץ מכיוון ש-Next.js משתפת קוד layout בין דפים, מה שהופך את הפעולה ליעילה יותר. באמצעות שימוש ב-IntlayerClientProviderב-layout, אתם נמנעים מאתחול מחדש שלו עבור כל דף, משפרים ביצועים ושומרים על הקשר לוקליזציה עקבי בכל האפליקציה שלכם.IntlayerServerProviderמשמש לספק את השפה לילדים בשרת. לא ניתן להגדיר אותו ב-layout.layout ו-page אינם יכולים לחלוק context שרתי משותף מכיוון שמערכת ה-context של השרת מבוססת על מאגר נתונים פר-בקשה (באמצעות מנגנון ה-cache של React), מה שגורם לכל "context" להיווצר מחדש עבור מקטעים שונים באפליקציה. מיקום ה-provider ב-layout משותף ישבור בידוד זה וימנע העברה תקינה של ערכי ה-context השרתי לרכיבי השרת שלכם.
src/components/ClientComponentExample.tsxהעתקת קודהעתקת הקוד ללוח
"use client"; import type { FC } from "react"; import { useIntlayer } from "next-intlayer"; export const ClientComponentExample: FC = () => { const content = useIntlayer("client-component-example"); // צרו הצהרת תוכן מתאימה return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> ); };src/components/ServerComponentExample.tsxהעתקת קודהעתקת הקוד ללוח
import type { FC } from "react"; import { useIntlayer } from "next-intlayer"; export const ServerComponentExample: FC = () => { const content = useIntlayer("server-component-example"); // צרו הצהרת תוכן מתאימה return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> ); };next-intlayerהוא נתיב הייבוא האיזומורפי: תנאי הייצואreact-serverמעניק ל-Server Components את מימוש השפה הסביבתית (ambient-locale), בעוד ש-Client Components מקבלים את המימוש המגובה ב-context. אותה הקריאה פועלת בשני הצדדים.src/components/ServerComponentExample.tsxהעתקת קודהעתקת הקוד ללוח
import type { FC } from "react"; import { useIntlayer } from "next-intlayer/server"; export const ServerComponentExample: FC = () => { const content = useIntlayer("server-component-example"); // צרו הצהרת תוכן מתאימה return ( <div> <h2>{content.title}</h2> <p>{content.content}</p> </div> ); };אם ברצונכם להשתמש בתוכן שלכם במאפיין מסוג
string, כגוןalt,title,href,aria-labelוכו', תוכלו להשתמש בערך הפונקציה כך:tsxהעתקת קודהעתקת הקוד ללוח
למידע נוסף על Hook ה-
useIntlayer, עיינו בתיעוד.אם האפליקציה שלכם כבר קיימת, תוכלו להשתמש ב-מהדר של Intlayer, כמו גם ב-פקודת extract, כדי להמיר אלפי רכיבים בשניות.
הגדרת Proxy לזיהוי שפה
אופציונליהגדירו proxy לזיהוי השפה המועדפת על המשתמש:
src/proxy.tsהעתקת קודהעתקת הקוד ללוח
export { intlayerProxy as proxy } from "next-intlayer/proxy"; export const config = { matcher: "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)", };ה-
intlayerProxyמשמש לזיהוי השפה המועדפת על המשתמש והפנייתו לכתובת ה-URL המתאימה כפי שהוגדר בתצורה. בנוסף, הוא מאפשר לשמור את השפה המועדפת של המשתמש בעוגייה.החל מגרסה 9 של Intlayer, פונקציונליות זו מכבדת את האפשרות
routing.enableProxy(trueכברירת מחדל). הגדירוrouting.enableProxy: falseבתצורה שלכם כדי להפוך אותה למעביר ישיר (pass-through) מבלי להסיר קובץ זה. ראו את הערות השחרור של v9.אם עליכם לשרשר מספר רכיבי proxy יחד (למשל,
intlayerProxyעם אימות או proxies מותאמים אישית), Intlayer מספק כעת כלי עזר בשםmultipleProxies.tsהעתקת קודהעתקת הקוד ללוח
בינאום המטא-דאטה שלכם
אופציונליבמקרה שבו ברצונכם לבצע בינאום למטא-דאטה שלכם, כגון כותרת הדף, תוכלו להשתמש בפונקציה
generateMetadataהמסופקת על ידי Next.js. בתוכה, תוכלו לשלוף את התוכן באמצעות הפונקציהgetIntlayerכדי לתרגם את המטא-דאטה.src/app/[locale]/metadata.content.tsהעתקת קודהעתקת הקוד ללוח
import { type Dictionary, t } from "intlayer"; import { Metadata } from "next"; const metadataContent = { key: "page-metadata", content: { title: t({ he: "יצירת אפליקציית Next", en: "Create Next App", fr: "Créer une application Next.js", es: "Crear una aplicación Next.js", }), description: t({ he: "נוצר על ידי create next app", en: "Generated by create next app", fr: "Généré par create next app", es: "Generado por create next app", }), }, } satisfies Dictionary<Metadata>; export default metadataContent;src/app/[locale]/layout.tsx or src/app/[locale]/page.tsxהעתקת קודהעתקת הקוד ללוח
import { getIntlayer, getMultilingualUrls } from "intlayer"; import type { Metadata } from "next"; import type { LocalPromiseParams } from "next-intlayer"; export const generateMetadata = async ({ params, }: LocalPromiseParams): Promise<Metadata> => { const { locale } = await params; const metadata = getIntlayer("page-metadata", locale); /** * Generates an object containing all url for each locale. * * Example: * ```ts * getMultilingualUrls('/about'); * * // Returns * // { * // en: '/about', * // fr: '/fr/about', * // es: '/es/about', * // } * ``` */ const multilingualUrls = getMultilingualUrls("/"); const localizedUrl = multilingualUrls[locale as keyof typeof multilingualUrls]; return { ...metadata, alternates: { canonical: localizedUrl, languages: { ...multilingualUrls, "x-default": "/" }, }, openGraph: { url: localizedUrl, }, }; }; // ... שאר הקודשימו לב כי הפונקציה
getIntlayerהמיובאת מ-next-intlayerמחזירה את התוכן עטוף ב-IntlayerNode, מה שמאפשר אינטגרציה עם העורך הויזואלי. לעומת זאת, הפונקציהgetIntlayerהמיובאת מ-intlayerמחזירה את התוכן ישירות ללא מאפיינים נוספים.למידע נוסף אודות אופטימיזציית מטא-דאטה, עיינו בתיעוד הרשמי של Next.js.
בינאום ה-sitemap.xml ו-robots.txt שלכם
אופציונליכדי לבצע בינאום עבור
sitemap.xmlו-robots.txt, תוכלו להשתמש בפונקציהgetMultilingualUrlsהמסופקת על ידי Intlayer. פונקציה זו מאפשרת ליצור כתובות URL רב-לשוניות עבור מפת האתר שלכם.src/app/sitemap.tsהעתקת קודהעתקת הקוד ללוח
import { getMultilingualUrls } from "intlayer"; import type { MetadataRoute } from "next"; const sitemap = (): MetadataRoute.Sitemap => [ { url: "https://example.com", alternates: { languages: { ...getMultilingualUrls("https://example.com"), "x-default": "https://example.com", }, }, }, { url: "https://example.com/login", alternates: { languages: { ...getMultilingualUrls("https://example.com/login"), "x-default": "https://example.com/login", }, }, }, { url: "https://example.com/register", alternates: { languages: { ...getMultilingualUrls("https://example.com/register"), "x-default": "https://example.com/register", }, }, }, ]; export default sitemap;src/app/robots.tsהעתקת קודהעתקת הקוד ללוח
import type { MetadataRoute } from "next"; import { getMultilingualUrls } from "intlayer"; const getAllMultilingualUrls = (urls: string[]) => urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]); const robots = (): MetadataRoute.Robots => ({ rules: { userAgent: "*", allow: ["/"], disallow: getAllMultilingualUrls(["/login", "/register"]), }, host: "https://example.com", sitemap: `https://example.com/sitemap.xml`, }); export default robots;למידע נוסף אודות אופטימיזציית מפת אתר (sitemap), עיינו בתיעוד הרשמי של Next.js. למידע נוסף אודות אופטימיזציית robots.txt, עיינו בתיעוד הרשמי של Next.js.
שינוי שפת התוכן שלכם
אופציונליכדי לשנות את שפת התוכן שלכם ב-Next.js, הדרך המומלצת היא להשתמש ברכיב
Linkכדי להפנות משתמשים לדף המקומי המתאים. רכיבLinkמאפשר prefetching של הדף, מה שמסייע למנוע טעינה מלאה מחדש של הדף.src/components/LocaleSwitcher.tsxהעתקת קודהעתקת הקוד ללוח
"use client"; import type { FC } from "react"; import { Locales, getHTMLTextDir, getLocaleName, getLocalizedUrl, } from "intlayer"; import { useLocale } from "next-intlayer"; import Link from "next/link"; export const LocaleSwitcher: FC = () => { const { locale, pathWithoutLocale, availableLocales, setLocale } = useLocale(); return ( <div> <button popoverTarget="localePopover">{getLocaleName(locale)}</button> <div id="localePopover" popover="auto"> {availableLocales.map((localeItem) => ( <Link href={getLocalizedUrl(pathWithoutLocale, localeItem)} key={localeItem} aria-current={locale === localeItem ? "page" : undefined} onClick={() => setLocale(localeItem)} replace // יבטיח שכפתור החזרה בדפדפן יפנה לדף הקודם > <span> {/* קוד שפה, למשל FR */} {localeItem} </span> <span> {/* שם השפה בשפה שלה, למשל Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* שם השפה בשפה הנוכחית, למשל ספרדית כאשר השפה הנוכחית מוגדרת ל-Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* שם השפה באנגלית, למשל French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> ))} </div> </div> ); };דרך חלופית היא להשתמש בפונקציה
setLocaleהמסופקת על ידי Hook ה-useLocale. פונקציה זו לא תאפשר ביצוע prefetch לדף. ראו את תיעוד Hook ה-useLocale לפרטים נוספים.תוכלו גם להגדיר פונקציה באפשרות
onLocaleChangeכדי להפעיל פונקציה מותאמת אישית בעת שינוי השפה.src/components/LocaleSwitcher.tsxהעתקת קודהעתקת הקוד ללוח
הפניות לתיעוד:
יצירת רכיב Link מקומי
אופציונליכדי להבטיח שהניווט באפליקציה שלכם יכבד את השפה הנוכחית, תוכלו ליצור רכיב
Linkמותאם אישית. רכיב זה מקדים באופן אוטומטי קישורים פנימיים עם קידומת השפה הנוכחית. לדוגמה, כאשר משתמש הדובר צרפתית לוחץ על קישור לדף "About", הוא מופנה ל-/fr/aboutבמקום ל-/about.התנהגות זו מועילה מכמה סיבות:
- SEO וחוויית משתמש: כתובות URL מקומיות עוזרות למנועי חיפוש לאנדקס נכון דפים ספציפיים לשפה ומספקות למשתמשים תוכן בשפתם המועדפת.
- עקביות: על ידי שימוש בקישור מקומי לאורך האפליקציה שלכם, אתם מבטיחים שהניווט יישאר בהקשר השפה הנוכחית, ומונעים מעברי שפה בלתי צפויים.
- תחזוקתיות: ריכוז לוגיקת הלוקליזציה ברכיב בודד מפשט את ניהול כתובות ה-URL, מה שהופך את בסיס הקוד שלכם לקל יותר לתחזוקה ולהרחבה ככל שהאפליקציה גדלה.
להלן היישום של רכיב
Linkמקומי ב-TypeScript:src/components/Link.tsxהעתקת קודהעתקת הקוד ללוח
"use client"; import { getLocalizedUrl } from "intlayer"; import NextLink, { type LinkProps as NextLinkProps } from "next/link"; import { useLocale } from "next-intlayer"; import type { PropsWithChildren, FC } from "react"; /** * פונקציית עזר לבדיקה האם כתובת URL נתונה היא חיצונית. * אם ה-URL מתחיל ב-http:// או https://, הוא נחשב חיצוני. */ export const checkIsExternalLink = (href?: string): boolean => /^https?:\/\//.test(href ?? ""); /** * רכיב Link מותאם אישית המתאים את המאפיין href לפי השפה הנוכחית. * עבור קישורים פנימיים, הוא משתמש ב-`getLocalizedUrl` כדי להוסיף קידומת שפה ל-URL (למשל, /fr/about). * דבר זה מבטיח שהניווט יישאר בתוך אותו הקשר שפה. */ export const Link: FC<PropsWithChildren<NextLinkProps>> = ({ href, children, ...props }) => { const { locale } = useLocale(); const isExternalLink = checkIsExternalLink(href.toString()); // אם הקישור הוא פנימי ומסופק href תקין, קבל את ה-URL המקומי. const hrefI18n: NextLinkProps["href"] = href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href; return ( <NextLink href={hrefI18n} {...props}> {children} </NextLink> ); };כיצד זה עובד
זיהוי קישורים חיצוניים:
פונקציית העזרcheckIsExternalLinkקובעת האם כתובת ה-URL היא חיצונית. קישורים חיצוניים נותרים ללא שינוי מכיוון שהם אינם זקוקים ללוקליזציה.אחזור השפה הנוכחית:
Hook ה-useLocaleמספק את השפה הנוכחית (למשל,frעבור צרפתית).לוקליזציה של ה-URL:
עבור קישורים פנימיים (שאינם חיצוניים), נעשה שימוש ב-getLocalizedUrlכדי להוסיף באופן אוטומטי קידומת שפה ל-URL. משמעות הדבר היא שאם המשתמש שלכם גולש בצרפתית, העברת/aboutכ-hrefתהפוך אותו ל-/fr/about.החזרת הקישור:
הרכיב מחזיר אלמנט<a>עם ה-URL המקומי, מה שמבטיח שהניווט יהיה עקבי עם השפה.
על ידי שילוב רכיב
Linkזה ברחבי האפליקציה שלכם, אתם שומרים על חוויית משתמש קוהרנטית ומודעת שפה, תוך הפקת תועלת משיפור ב-SEO ובשימושיות.קבלת השפה הנוכחית ב-Server Actions
אופציונליאם אתם זקוקים לשפה הפעילה בתוך Server Action (למשל, כדי לתרגם הודעות דוא"ל או להריץ לוגיקה מודעת שפה), קראו ל-
getLocaleמ-next-intlayer/server:src/app/actions/getLocale.tsהעתקת קודהעתקת הקוד ללוח
הפונקציה
getLocaleפועלת לפי אסטרטגיה מדורגת לקביעת שפת המשתמש:- ראשית, היא בודקת את כותרות הבקשה (headers) עבור ערך שפה שאולי הוגדר על ידי ה-proxy
- אם לא נמצאה שפה בכותרות, היא מחפשת שפה השמורה בעוגיות
- אם לא נמצאה עוגייה, היא מנסה לזהות את השפה המועדפת על המשתמש מהגדרות הדפדפן שלו
- כמוצא אחרון, היא חוזרת לשפת ברירת המחדל שהוגדרה באפליקציה
דבר זה מבטיח בחירה בשפה המתאימה ביותר בהתבסס על ההקשר הזמין.
אופטימיזציה של גודל ה-Bundle
אופציונליבעת שימוש ב-
next-intlayer, מילונים נכללים ב-bundle עבור כל דף כברירת מחדל. כדי למטב את גודל ה-bundle, Intlayer מספק פלאגין SWC אופציונלי המחליף בתבונה קריאותuseIntlayerבאמצעות פקודות מאקרו. הדבר מבטיח שהמילונים ייכללו ב-bundles רק עבור דפים שבאמת משתמשים בהם.כדי להפעיל אופטימיזציה זו, התקינו את החבילה
@intlayer/swc. לאחר ההתקנה,next-intlayerיזהה וישתמש בפלאגין באופן אוטומטי:bashהעתקת קודהעתקת הקוד ללוח
הערה: אופטימיזציה זו זמינה רק עבור Next.js 13 ומעלה.
הערה: חבילה זו אינה מותקנת כברירת מחדל מכיוון שפלאגיני SWC עדיין נחשבים ניסיוניים ב-Next.js. הדבר עשוי להשתנות בעתיד.
הערה: אם תגדירו את האפשרות כ-
importMode: 'dynamic'אוimportMode: 'fetch'(בתצורתdictionary), היא תסתמך על Suspense, כך שתצטרכו לעטוף את קריאות ה-useIntlayerשלכם בגבולSuspense. משמעות הדבר היא שלא תוכלו להשתמש ב-useIntlayerישירות ברמה העליונה של רכיב הדף / ה-Layout שלכם.חילוץ תוכן הרכיבים שלכם
אופציונליאם יש לכם בסיס קוד קיים, המרת אלפי קבצים עלולה לגזול זמן רב.
כדי להקל על תהליך זה, Intlayer מציע מהדר (compiler) / מחלץ (extractor) להמרת הרכיבים שלכם וחילוץ התוכן מתוכם.
כדי להגדיר זאת, תוכלו להוסיף סעיף
compilerבקובץintlayer.config.tsשלכם:intlayer.config.tsהעתקת קודהעתקת הקוד ללוח
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... שאר התצורה שלכם compiler: { /** * מציין האם המהדר מופעל. */ enabled: true, /** * מגדיר את נתיב קובצי הפלט */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * מציין האם לשמור את הרכיבים לאחר שהומרו. * * - אם `true`, המהדר ישכתב את קובץ הרכיב בדיסק. כך שההמרה תהיה קבועה, והמהדר ידלג על ההמרה בתהליך הבא. בדרך זו, המהדר יכול להמיר את האפליקציה, ולאחר מכן ניתן להסירו. * * - אם `false`, המהדר יזריק את הקריאה לפונקציה `useIntlayer()` לתוך הקוד בפלט הבנייה בלבד, וישמור על בסיס הקוד המקורי ללא שינוי. ההמרה תתבצע רק בזיכרון. */ saveComponents: false, /** * קידומת מפתח מילון */ dictionaryKeyPrefix: "", }, }; export default config;הריצו את המחלץ כדי להמיר את הרכיבים שלכם ולחלץ את התוכן:
bashהעתקת קודהעתקת הקוד ללוח
bashהעתקת קודהעתקת הקוד ללוח
babel.config.jsהעתקת קודהעתקת הקוד ללוח
bashהעתקת קודהעתקת הקוד ללוח
מעקב אחר שינויים במילונים ב-Turbopack
החל מ-next-intlayer v9.5, withIntlayer מפעיל את מנטר התוכן (content watcher) בעצמו, ללא צורך בהגדרה נוספת.
בעת שימוש ב-Turbopack כשרת הפיתוח שלכם באמצעות הפקודה next dev, שינויים במילונים לא יזוהו אוטומטית כברירת מחדל.
מגבלה זו מתרחשת מכיוון ש-Turbopack אינו יכול להריץ פלאגיני webpack במקביל כדי לנטר שינויים בקובצי התוכן שלכם. כדי לעקוף זאת, תצטרכו להשתמש בפקודה intlayer watch כדי להריץ בו-זמנית את שרת הפיתוח ואת מנטר הבנייה של Intlayer.
העתקת הקוד ללוח
אם אתם משתמשים ב-next-intlayer@<=6.x.x, עליכם לשמור על הדגל--turbopackכדי שאפליקציית Next.js 16 תפעל כראוי עם Turbopack. אנו ממליצים להשתמש ב-next-intlayer@>=7.x.xכדי להימנע ממגבלה זו.
הגדרת TypeScript
Intlayer עושה שימוש ב-module augmentation כדי להפיק תועלת מ-TypeScript ולהפוך את בסיס הקוד שלכם לחזק יותר.


ודאו שתצורת ה-TypeScript שלכם כוללת את הטיפוסים שנוצרו אוטומטית.
העתקת הקוד ללוח
הגדרת Git
מומלץ להתעלם מהקבצים שנוצרו על ידי Intlayer. הדבר מאפשר לכם להימנע מהעלאתם למאגר ה-Git שלכם.
לשם כך, תוכלו להוסיף את ההוראה הבאה לקובץ ה-.gitignore שלכם:
העתקת הקוד ללוח
הרחבה ל-VS Code
כדי לשפר את חוויית הפיתוח שלכם עם Intlayer, תוכלו להתקין את הרחבת VS Code הרשמית של Intlayer.
הרחבה זו מספקת:
- השלמה אוטומטית (Autocompletion) עבור מפתחות תרגום.
- זיהוי שגיאות בזמן אמת עבור תרגומים חסרים.
- תצוגה מקדימה מוטמעת (Inline previews) של תוכן מתורגם.
- פעולות מהירות (Quick actions) ליצירה ועדכון פשוטים של תרגומים.
לפרטים נוספים על אופן השימוש בהרחבה, עיינו בתיעוד של הרחבת VS Code של Intlayer.
להעמיק עוד
כדי להעמיק עוד, תוכלו ליישם את העורך הויזואלי או להעביר את התוכן שלכם לניהול חיצוני באמצעות ה-CMS.
שאלות נפוצות
ל-Next.js אין שכבת הודעות מובנית מאז שהשדה i18n ב-next.config.js הפסיק לחול על ה-App Router, ולכן שכבת הלוקליזציה היא תמיד בחירה בספרייה:
next-intl,i18next/next-i18nextו-react-intl: האפשרויות ההיסטוריות, המבוססות על קטלוגי הודעות JSON או ICU הנטענים לפי namespace.Lingui: מונחה חילוץ (extraction driven), עם הודעות ICU המהודרות בזמן בנייה.Intlayer: הפתרון המתקדם ביותר. תוכן מוצהר בכל מקום בבסיס הקוד שלכם (לצד כל רכיב או באופן מרוכז), מהודר בזמן בנייה למילונים נפרדים לכל רכיב, בעל טיפוסיות מלאה, עם תרגום מבוסס AI, עורך ויזואלי ו-CMS כלולים.
ההבדל המעשי הוא מה שמגיע לדפדפן. ספריות מבוססות namespace שולחות קטלוגי JSON שלמים לדף, בעוד ש-Intlayer שולח רק את התוכן שהרכיבים המרונדרים צורכים בפועל, מה שמפחית את גודל ה-bundle והדף בעד 50%. ראו למה Intlayer ואת מבחן הביצועים של i18n ב-Next.js.
הרבה פחות מהגדרה מבוססת namespace, מכיוון שדף לעולם אינו מוריד קטלוג שאינו מרנדר. Server Components פותרים את התוכן שלהם בשרת, ומהדר זמן הבנייה מחליף קריאות ל-useIntlayer ברשומות המילון המדויקות שהרכיב משתמש בהן, כך שמפתחות שאינם בשימוש ושפות שאינן נחוצות מושמטים, ו-מילונים דינמיים מפצלים את השאר לפי שפה. בהשוואה לחלופות המקובלות, Intlayer מפחית את גודל ה-bundle והדף בעד 50%. ראו אופטימיזציית bundle ואת מבחן הביצועים.
כן, וישנם שני מסלולים. תוכלו להגר את התוכן בהדרגה בעזרת מדריך ההגירה מ-next-intl או מדריך ההגירה מ-i18next. לחלופין, תוכלו לשמור על ה-API הנוכחי שלכם במלואו: מתאמי התאימות (compat adapters) חושפים בדיוק את אותו ה-API כמו next-intl, react-i18next ו-react-intl, אך מוגשים באמצעות מילוני Intlayer, כך שרק הייבוא משתנה וקוד הרכיב נשאר בעינו.
כן. ה-פלאגין לסנכרון JSON שומר על קובצי /messages/{locale}/{namespace}.json שלכם כמקור האמת ומייצר מהם מילוני Intlayer, בשני הכיוונים. פלאגין לסנכרון PO עושה את אותו הדבר עבור קטלוגי gettext, ו-קבצים לפי שפה מאפשרים לכם לפצל תוכן לפי שפה במקום לקבץ את כל השפות בקובץ אחד.
לא. הריצו npx intlayer extract ו-Intlayer יקרא את הרכיבים שלכם, יחלץ את המחרוזות הפונות למשתמש ויכתוב קובץ .content לצד כל אחד מהם, כך שתוכלו לבדוק diff במקום להעתיק מחרוזות לקטלוג אחת אחת. שלב 14 במדריך זה מדגים זאת.
עבור צינור אוטומטי לחלוטין, ה-מהדר של Intlayer (Intlayer Compiler) עושה את אותו הדבר בזמן בנייה: הוא סורק את קובצי ה-JSX, TSX, Vue ו-Svelte שלכם בכל שינוי, מייצר את המילונים ושומר עליהם מסונכרנים באמצעות Hot Module Replacement, כך שאין שום מפתחות לתחזק ידנית.
כדאי להכיר שתי מגבלות לפני הפעלת המהדר. הוא פועל באמצעות ניתוח סטטי, כך שמחרוזות שקיימות רק בזמן ריצה, כגון קודי שגיאה מ-API או שדות CMS, נשארות מחוץ להישג ידו. כמו כן, עליו להבדיל בין טקסט הפונה למשתמש לבין לוגיקת האפליקציה כמו className="active" או קוד סטטוס, מה שמצריך מספר הערות בבסיס קוד גדול. פקודת extract נמנעת משתיהן בכך שהיא משאירה אתכם בשליטה.
חמישה כלים, כולם אופציונליים:
- הרחבה ל-VS Code: קפיצה ממפתח ב-
useIntlayerלקובץ התוכן שמצהיר עליו, חילוץ תוכן מקומפוננטה, והרצת build, fill, test, push ו-pull מפלטת הפקודות או מלשונית Intlayer ייעודית. - שרת LSP: אותה מודעות בכל עורך התומך ב-LSP, עם מעבר להגדרה (go to definition), חיפוש כל ההפניות, תצוגה מקדימה בריחוף (hover) של ערך מתורגם, השלמה אוטומטית של מפתחות ושדות, ואזהרה כאשר מפתח אינו מוצהר בשום מקום. הוא גם מפענח קריאות של
i18next,react-i18next,next-intlו-use-intl, מה שעוזר במהלך ההגירה. - שרת MCP: חושף את התיעוד וה-CLI של Intlayer עבור Cursor, VS Code, Claude Desktop, Claude Code ו-ChatGPT, כך שעוזר יענה מתוך תיעוד עדכני במקום לנחש, ויוכל להריץ פקודות כמו
intlayer fillבעצמו. - כישורי סוכן (Agent skills): כישורים ממוקדים כגון
intlayer-config,intlayer-cliו-intlayer-content, בתוספת אחד לכל framework, המלמדים סוכן את הגדרות הניתוב שלכם ואת סוגי צמתי התוכן. - פלאגין ESLint: הכלל
no-raw-textמסמן מחרוזות מוקלדות בקוד (hardcoded), עם כללים נוספים למפתחות מילון סטטיים ותוכן שאינו בשימוש.
