next-intl מול @intlayer/next-intl: אותו ה-API, חבילת קוד (Bundle) שונה

@intlayer/next-intl הוא מתאם תאימות (compat adapter): הוא חושף את ה-API המוכר של next-intl (כגון useTranslations, ‏getTranslations, ‏useLocale, ‏t.rich(), צורות רבים ב-ICU, ‏NextIntlClientProvider...) ומגיש אותו מתוך מילונים שקומפלו על ידי Intlayer. קוד האפליקציה אינו משתנה, אך ה-bundle משתנה באופן משמעותי.

מאמר זה משווה בין השניים על אותו יישום Next.js, שנבנה פעם אחת עם next-intl ופעם שנייה עם המתאם. הנתונים מגיעים מ-Benchmark Bloom, חבילת בדיקות קוד פתוח המתעדת את מה שהדפדפן מוריד בפועל. אם ברצונכם לקרוא השוואה בין שתי הספריות כספריות עצמאיות, עיינו ב-next-intl מול Intlayer. מאמר זה עוסק בשינויים שמביא המתאם כאשר משאירים את הקומפוננטות ללא שינוי.

תקציר (tl;dr): באותו יישום Next.js, החלפת next-intl ב-@intlayer/next-intl הפחיתה את ה-JavaScript הממוצע לדף מ-153.6 KB ל-147.5 KB ב-gzip, את גודל הקומפוננטה הממוצע מ-21.8 KB ל-8.1 KB, ביטלה דליפת מחרוזות מדפים זרים מ-~90% ל-0%, וקיצרה את משך ההידרציה מ-14.7 ms ל-12.8 ms, מבלי לערוך אף קומפוננטה. ב-TanStack Start, המקבילה עבור use-intl (המתאם @intlayer/use-intl) קיצצה את הקומפוננטות מ-76-87 KB ל-9-11 KB והאיצה את החלפת השפה מ-7-21 ms ל-4-9 ms. המתאם מוסיף 8.0 KB של זמן ריצה לעומת 14.7 KB ב-next-intl ו-5.5 KB ב-next-intlayer המקורית. הניתוב וה-middleware ממומשים מחדש על גבי תצורת הניתוב של Intlayer; נתיבים מתורגמים (pathnames) הם התכונה היחידה שאינה מועברת.

מהו בעצם @intlayer/next-intl

next-intl פועלת בזמן ריצה: getRequestConfig טוען קובץ messages/{locale}.json לכל בקשה, NextIntlClientProvider שולח אותו לצד הלקוח, ו-useTranslations("about") קורא מפתחות מאותו אובייקט בעת הרינדור. כל אופטימיזציה (פיצול ל-namespaces, סינון pick(messages, [...]) לכל דף, טעינה עצלה) היא באחריותכם הבלעדית.

@intlayer/next-intl שומרת על החלק הראשון והאחרון בשרשרת זו ומחליפה את התווך. הקומפוננטות שלכם עדיין קוראות ל-useTranslations("about"); מה שהן מקבלות בפועל מגיע ממילון Intlayer שקומפל בזמן build, מתוחם בדיוק לאותה קומפוננטה, ובשפה הפעילה בלבד.

שלושה מנגנונים גורמים לזה לעבוד:

1. כינויי ייבוא (Import aliasing): הפונקציה createNextIntlPlugin() מתוך @intlayer/next-intl/plugin עוטפת את withIntlayer ומוסיפה כינויים ל-Webpack ול-Turbopack כך ש-next-intl, ‏next-intl/server, ‏next-intl/navigation ו-next-intl/middleware מנותבים אל @intlayer/next-intl. אין צורך לשנות אף שורת ייבוא בקוד שלכם.
2. JSON כמקור האמת: תוסף syncJSON קורא את קובץ messages/{locale}.json הקיים שלכם, מפצל את המפתחות ברמה העליונה למילון נפרד לכל namespace, וכותב תרגומים בחזרה לאותם קבצים בדיוק כאשר ה-CLI או ה-CMS מעדכנים אותם. תהליך העבודה של המתרגמים נותר ללא שינוי.
3. קישור ברמת מוקד הקריאה (Call-site binding): שלב האופטימיזציה של Intlayer (דרך Babel או SWC) משכתב את הקריאה useTranslations("about") לקריאה שמקבלת ישירות את מילון about. הקומפוננטה אינה ניגשת עוד לעץ הודעות גלובלי, אלא אך ורק לתוכן שלה.

// הקוד שלכם, ללא שינוי
import { useTranslations } from "next-intl";

const AboutPage = () => {
  const t = useTranslations("about");
  return <h1>{t("title")}</h1>;
};

import _dicHash_about from "../.intlayer/dictionaries/about.mjs";
import { useDictionary as useTranslations } from "@intlayer/next-intl";

const AboutPage = () => {
  const t = useTranslations(_dicHash_about);
  return <h1>{t("title")}</h1>;
};

שכתוב זה הוא הסיבה לכך שגודל הקומפוננטה ודליפת הדפים מצטמצמים: דף מושך אך ורק את המילונים של הקומפוננטות שהוא מרנדר, ורק בשפה המוגשת באותו רגע.

מה המתאם שומר, ממה הוא מתעלם ומה אינו מוחלף

מבחן הביצועים (Benchmark)

מה נבדק

חבילת Benchmark Bloom בונה את אותו יישום בדיוק בכל הגדרה: 10 דפים (home, about, blog, careers, contact, FAQ, pricing, products, settings, team), 10 שפות (en, fr, es, de, it, pt, zh, ja, ko, ru), קומפוננטות זהות ותוכן זהה. הדפים נמדדים ב-en וב-fr.

next-intl נבנתה בארבע אסטרטגיות טעינה שונות, מהתצורה הנאיבית (קובץ messages/{locale}.json נטען במלואו) ועד לאופטימלית (namespace אחד לכל נתיב + pick() לכל דף). המתאם נבנה על אותן קומפוננטות של התצורה הנאיבית, כאשר שונו רק next.config.ts ו-intlayer.config.ts. אין צורך בגרסת "scoped" ייעודית: הקומפיילר תוחם תוכן לכל קומפוננטה, כך ששורות ה-static וה-dynamic כבר מבודדות וממוטבות מראש.

לכל בנייה, חבילת הבדיקות מודדת:

• גודל ספרייה (Lib size): משקל gzip של קומפוננטה ריקה שמייבאת רק את ספריית ה-i18n (העלות הקבועה של זמן הריצה).
• ממוצע JS לדף (Page JS): משקל ה-JavaScript המורד ב-gzip לכל דף, בממוצע על פני כל הדפים והשפות.
• אחוז דליפת שפה (Locale leak %): חלקן של מחרוזות מתורגמות ב-JS שהורד השייכות לשפה שהמשתמש אינו צופה בה.
• אחוז דליפת דפים (Page leak %): חלקן של מחרוזות מתורגמות ב-JS שהורד השייכות לדף שהמשתמש אינו נמצא בו.
• ממוצע לקומפוננטה (Component avg): משקל ממוצע ב-gzip של כל קומפוננטה כשהיא מקומפלת בבידוד.
• תגובתיות מקצה לקצה (E2E reactivity): זמן שעון בין בחירת שפה חדשה לעדכון html[lang] ב-DOM (נבדק ב-Playwright, ממוצע של 5 חזרות).
• הידרציה (Hydration): משך שלב ההידרציה של React.

הנתונים להלן מגיעים מהרצה מיום 12 בספטמבר 2026 עם next-intl / use-intl 4.14.2 ו-@intlayer/* 9.5.1. יישום הבדיקה קטן במכוון (עשרות בודדות של מחרוזות לכל שפה), כך שאחוזי הדליפה מתארים דפוס עקרוני: הם צומחים ככל שנפח התוכן גדל, בעוד שעלות זמן הריצה נשארת קבועה.

תוצאות ב-Next.js

כיצד לקרוא את התוצאות

• אותן קומפוננטות, 6 KB פחות לדף: בניית האפליקציה הנאיבית עם המתאם מגיעה ל-147.5 KB, פחות מכל תצורה של next-intl כולל התצורה הממוטבת ביותר (153.6 KB). ההבדל נובע ישירות ממשקל זמן הריצה: 8.0 KB לעומת 14.7 KB, המשולמים בכל דף.
• הדליפה יורדת ל-0% מבלי לגעת בקומפוננטות: המערך הנאיבי ב-next-intl שולח כ-90% מחרוזות מדפים זרים בכל דף. הגעה ל-0% ב-next-intl מחייבת מעבר לתצורות scoped-*: יצירת namespace לכל נתיב והפעלת pick(messages, [...]) בכל דף. המתאם מגיע ל-0% ישירות מהקוד הנאיבי משום ששלב האופטימיזציה קושר כל קריאת useTranslations("ns") למילון הייעודי שלה.
• קומפוננטות מתכווצות פי 2.7: קומפוננטה המקומפלת בבידוד שוקלת בממוצע 21.8 KB ב-next-intl (משום שהיא מקושרת ל-provider ולעץ ההודעות כולו) לעומת 8.1 KB עם המתאם. בתצורת scoped-static של next-intl מספר זה אף מזנק ל-80 KB.
• הידרציה מהירה יותר ב-2 ms (12.8 לעומת 14.7 ms): אין צורך לבצע דה-סריאליזציה לאובייקט הודעות גדול מתוך נתוני ה-RSC לפני ש-React יכולה לבצע הידרציה.
• המתאם אינו זמן הריצה הטבעי: next-intlayer מגיעה ל-141.3 KB, תוספת של 0.3 KB בלבד מעל אפליקציית הבסיס, עם זמן ריצה של 5.5 KB. המתאם נושא את מעטפת ה-API של next-intl (כגון useFormatter, t.rich, ומפענח ה-ICU) על גבי ליבת Intlayer, ומכאן 8.0 KB ותוספת של 6 KB לדף. הוא מהווה גשר מצוין, ולא היעד הסופי.

הטבלה המלאה זמינה ב-דוח ה-benchmark של Next.js.

תוצאות ב-TanStack Start (use-intl)

use-intl היא ליבת הספרייה הבלתי-תלויה של next-intl. המתאם שלה, @intlayer/use-intl, פועל לפי אותו עקרון באמצעות תוסף Vite (@intlayer/use-intl/plugin).

כיצד לקרוא את התוצאות

• במשקל הבתים לדף התוצאה כמעט זהה מול use-intl הממוטבת. @intlayer/use-intl במצב dynamic ‏(129.7 KB) קרובה בטווח של 1 KB ל-use-intl ב-scoped-dynamic ‏(128.7 KB). שורת ה-dynamic הפשוטה של use-intl אמנם קלה יותר (119.4 KB), אך היא מדליפה 90% ממחרוזות הדפים הזרים. ה-0% דליפה של המתאם הוא מה ששומר על גודל קבוע ככל שהתוכן צומח.
• קומפוננטות קטנות פי 7-9: קומפוננטות use-intl שוקלות בממוצע 76-87 KB בכל אסטרטגיה, משום ש-useTranslations קשורה לכל אובייקט ההודעות של ה-provider. המתאם מוריד זאת ל-9-11 KB.
• החלפת שפה מהירה בהרבה: התצורות הממוטבות של use-intl דורשות 13-21 ms לעדכון html[lang]; המתאם דורש 4-9 ms בלבד.
• שורת static שומרת על כל השפות: במצב static המתאם מציג 49.7% דליפת שפה, בדיוק כמו Intlayer הטבעית במצב זה. שורת הגדרה בודדת (importMode: 'dynamic') מסירה זאת לחלוטין.

הטבלה המלאה זמינה ב-דוח ה-benchmark של TanStack Start.

מדוע המספרים משתנים

שום דבר בקומפוננטה עצמה לא השתנה, ולכן השיפורים נובעים במלואם מהגורם שאליו useTranslations קשורה.

עם next-intl, הקישור נעשה דרך ה-provider. ‏NextIntlClientProvider מקבל את כל אובייקט ה-messages עבור השפה; כל קריאת useTranslations("about") קוראת ממנו. ה-bundler רואה קומפוננטה שמייבאת hook יחיד הקורא מ-context אחד, ואינו יכול לדעת שנעשה שימוש רק בענף של about. כל הנתיבים חולקים את אותו אובייקט הודעות, ולכן דליפת הדפים עומדת על כ-90% עד שמפצלים את הקבצים ידנית, והבזבוז גדל בשני הצירים במקביל:

.
├── messages
│   ├── en.json                       # כל ה-namespaces, כל הדפים
│   └── fr.json
└── src
    ├── i18n.ts                       # getRequestConfig({ messages: await import(...) })
    ├── middleware.ts                 # createMiddleware(routing)
    └── app/[locale]
        ├── layout.tsx                # <NextIntlClientProvider messages={messages}>
        └── about/page.tsx            # useTranslations("about")

עם @intlayer/next-intl, הקישור נעשה ברמת המילון. תוסף syncJSON הופך את messages/en.json למילון נפרד לכל מפתח ראשי; הקומפיילר מזהה איזו קומפוננטה קוראת ל-useTranslations("about") ומעביר לה ישירות את מילון about, בשפה הפעילה, כייבוא שניתן למעקב ולפיצול ב-bundler.

.
├── intlayer.config.ts                # syncJSON({ source: ({ locale }) => `./messages/${locale}.json` })
├── messages
│   ├── en.json                       # ללא שינוי, עדיין מקור האמת
│   └── fr.json
├── .intlayer/                        # נוצר אוטומטית: מילון אחד לכל namespace, לכל שפה
└── src
    ├── middleware.ts                 # createMiddleware() מחזיר כעת את הפרוקסי של Intlayer
    └── app/[locale]
        ├── layout.tsx                # <NextIntlClientProvider> (ללא פרופ messages)
        └── about/page.tsx            # useTranslations("about")  ← ללא שינוי

הקובץ src/i18n.ts והפרופ messages נעלמים. כל השאר נשאר זהה לחלוטין.

הגירה בשלושה שלבים

1. 1

   התקנה

   bash

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   npx intlayer init --interactive
   

   הפקודה מזהה את next-intl ומתקינה את intlayer, ‏next-intlayer, ‏@intlayer/next-intl ואת @intlayer/sync-json-plugin. השאירו את next-intl מותקנת: היא peer dependency של המתאם ומספקת את הטיפוסים.

2. 2

   כיוון Intlayer אל קובצי ההודעות שלכם

   intlayer.config.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     dictionary: {
       // "static" אורז את כל השפות; "dynamic" טוען את השפה הפעילה לפי דרישה
       importMode: "dynamic",
     },
     plugins: [
       syncJSON({
         // מחזיקי מקום ב-ICU: {name}, {count, plural, one {# item} other {# items}}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;
   

   הקבצים messages/{locale}.json נשארים במקומם. כל מפתח ראשי הופך למילון; useTranslations("about") ממופה למילון about.

3. 3

   עטיפת next.config.ts

   next.config.ts

   העתקת התוכן

   העתקת קוד

   העתקת הקוד ללוח

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {};
   
   export default withIntlayer(nextConfig);
   

   הפונקציה createNextIntlPlugin() משלבת את withIntlayer (מעקב תוכן, קימפול מילונים, שלב האופטימיזציה) ואת הכינויים של next-intl ל-@intlayer/next-intl עבור Webpack ו-Turbopack. בצעו build, והתוצאות בטבלאות שלעיל שלכם.

מה ניתן למחוק לאחר מכן

מה מרוויחים מעבר לחיסכון בבתים

• מפתחות בעלי טיפוסים קפדניים: הקריאה useTranslations("about") מוקלדת ומאומתת מול מילון about. קריאה ל-t("does.not.exist") הופכת לשגיאת TypeScript ברורה, ולא לנפילת ריצה שקטה.
• npx intlayer test מכשיל את ה-CI כאשר בשפה מסוימת חסר מפתח. npx intlayer fill מתרגם מפתחות חסרים באמצעות הספק לבחירתכם (OpenAI, Anthropic, Mistral, Gemini...) באמצעות המפתח שלכם, וכותב את התוצאה בחזרה ל-messages/{locale}.json.
• העורך החזותי וה-CMS פועלים על אותם מילונים, כך שמשתמשים ללא רקע טכני יכולים לערוך את messages/fr.json דרך ממשק גרפי והקובץ מתעדכן.
• מעבר הדרגתי ל-.content.ts: כל קומפוננטה יכולה לעבור מ-useTranslations("about") ל-useIntlayer("about") עם קובץ תוכן צמוד, קומפוננטה אחר קומפוננטה. מילוני JSON ו-.content.ts מתקיימים במקביל ומתמזגים.

מגבלות שיש להכיר לפני שמתחילים

מתי להשתמש בכל אפשרות?

שאלות נפוצות (FAQ)

השוואות קשורות

סדרת מתאמי התאימות:

השוואת הספריות ראש בראש:

תיעוד ומדריכים:

דוחות benchmark:

כדי להבין את מקורן של ספריות אלו, קראו על ההיסטוריה של בינאום ב-JavaScript.

סיכום

@intlayer/next-intl עושה דבר אחד מרכזי: היא משנה את הגורם שאליו useTranslations קשורה, מ-provider המחזיק בכל ההודעות למילון שקומפל במיוחד עבור אותה קומפוננטה. באותו יישום Next.js הדבר מביא לחיסכון של 6 KB לדף, קומפוננטות קטנות פי 2.7, 0% דליפת תוכן וקיצור של 2 ms במשך ההידרציה, עוד לפני שפותחים קובץ קומפוננטה כלשהו. הניתוב וה-middleware שומרים על ה-API המוכר שלהם על גבי תצורת הניתוב של Intlayer, וזמן הריצה הטבעי של next-intlayer נשאר קל אף יותר.

כל הנתונים הגולמיים, יישומי הבדיקה והסקריפטים זמינים במאגר Benchmark Bloom. הריצו אותם בעצמכם.

עיינו במסמך 'למה Intlayer?' לפרטים נוספים.