שאלו את שאלתכם וקבלו סיכום של המסמך על ידי הפניה לדף הזה ולספק ה-AI שתבחרו
היסטוריית גרסאות
- "עדכון השימוש ב-API של useIntlayer ב-Solid לגישה ישירה למאפיינים"v8.9.04.5.2026
- "היסטוריה ראשונית"v8.4.1023.3.2026
התוכן של הדף הזה תורגם באמצעות AI.
צפייה בגרסה האחרונה של התוכן המקורי באנגליתאם יש לכם רעיון לשיפור התיעוד הזה, אל תהססו לתרום על ידי הגשת Pull Request ב-GitHub.
קישור GitHub לתיעודהעתקת ה-Markdown של המסמך ללוח
תרגום אתר ה-Vite ו-Lit שלכם באמצעות Intlayer
תוכן עניינים
למה לבחור ב-Intlayer על פני חלופות?
בהשוואה לפתרונות מובילים כמו lit-localize או i18next, Intlayer הוא פתרון המגיע עם אופטימיזציות מובנות כגון:
Intlayer מותאם לפעול בצורה מושלמת עם Lit על ידי הצעת תיחום תוכן ברמת רכיב האינטרנט (Web Component), תמיכה ב-TypeScript, וכל התכונות הנדרשות להרחבת הבינאום (i18n).
במקום לטעון קובצי JSON עצומים לתוך הדפים שלכם, טענו רק את התוכן הנדרש. Intlayer מסייע להפחית את גודל החבילה והדפים שלכם בעד 50%.
תיחום התוכן של האפליקציה שלכם מקל על התחזוקה באפליקציות רחבות היקף. תוכלו לשכפל או למחוק תיקיית פיצ'ר בודדת ללא הנטל המחשבתי של סקירת כל קוד התוכן שלכם. בנוסף, Intlayer בעל טיפוסיות מלאה (fully typed) כדי להבטיח את דיוק התוכן שלכם.
הצבת תוכן בסמיכות לקוד (co-locating) מפחיתה את ההקשר (context) הנדרש על ידי מודלי שפה גדולים (LLMs). Intlayer מגיע גם עם חבילת כלים, כגון CLI לבדיקת תרגומים חסרים, LSP, MCP ו-agent skills, כדי להפוך את חוויית המפתח (DX) לחלקה אף יותר עבור סוכני AI.
השתמשו באוטומציה לתרגום ב-CI/CD pipeline שלכם באמצעות ה-LLM לבחירתכם בעלות של ספק ה-AI שלכם. Intlayer מציע גם קומפיילר לאוטומציה של חילוץ תוכן, וכן פלטפורמת ווב המסייעת לתרגם ברקע.
חיבור קובצי JSON ענקיים לרכיבים עלול להוביל לבעיות ביצועים וריאקטיביות. Intlayer מבצע אופטימיזציה לטעינת התוכן שלכם בזמן הבנייה (build time).
יותר מסתם פתרון i18n, Intlayer מספק עורך חזותי באחסון עצמי (self-hosted) ו-CMS מלא שיעזרו לכם לנהל את התוכן הרב-לשוני שלכם בזמן אמת, מה שהופך את שיתוף הפעולה עם מתרגמים, כותבי תוכן וחברי צוות אחרים לחלק ופשוט. ניתן לאחסן תוכן מקומית ו/או מרחוק.
ראו את תבנית האפליקציה (Application Template) ב-GitHub.
מדריך שלב אחר שלב להגדרת Intlayer באפליקציית Vite ו-Lit
התקנת תלויות
התקינו את החבילות הנדרשות באמצעות npm:
bashהעתקת קודהעתקת הקוד ללוח
הדגל
--interactiveהוא אופציונלי. השתמשו ב-intlayer-cli initאם אתם סוכן AI.פקודה זו תזהה את הסביבה שלכם ותתקין את החבילות הנדרשות. לדוגמה:
bashהעתקת קודהעתקת הקוד ללוח
intlayer
חבילת הליבה המספקת כלי בינאום לניהול הגדרות, תרגום, הצהרת תוכן, טרנספילציה ו-פקודות CLI.
lit-intlayer החבילה שמשלבת את Intlayer עם אפליקציות Lit. היא מספקת hooks המבוססים על
ReactiveController(useIntlayer,useLocaleוכו') כך שרכיבי LitElement מתרנדרים מחדש אוטומטית כאשר השפה משתנה.vite-intlayer כוללת את תוסף Vite לשילוב Intlayer עם Vite bundler, וכן middleware לזיהוי השפה המועדפת על המשתמש, ניהול קובצי cookie וטיפול בהפניות URL.
הגדרת הפרויקט שלכם
ארכיטקטורה
בארכיטקטורה זו,
lit-intlayerמספקת אינטגרציות של custom elements ובקרים ריאקטיביים לניהול תרגומים בתוך Web Components. הצהרות התוכן שוכנות ב-src/לצד הרכיבים.bashהעתקת קודהעתקת הקוד ללוח
הגדרות
צרו קובץ הגדרות כדי להגדיר את השפות של האפליקציה שלכם:
intlayer.config.tsהעתקת קודהעתקת הקוד ללוח
import { Locales, type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // שפות נוספות שלכם ], defaultLocale: Locales.ENGLISH, }, }; export default config;באמצעות קובץ הגדרות זה, תוכלו להגדיר כתובות URL מותאמות לשפה, הפניות middleware, שמות קובצי cookie, את המיקום והסיומת של הצהרות התוכן שלכם, להשבית יומני רישום של Intlayer במסוף ועוד. לרשימה המלאה של הפרמטרים הזמינים, עיינו ב-תיעוד ההגדרות.
שילוב Intlayer בהגדרות Vite שלכם
הוסיפו את תוסף intlayer להגדרות שלכם.
vite.config.tsהעתקת קודהעתקת הקוד ללוח
import { defineConfig } from "vite"; import { intlayer } from "vite-intlayer"; // https://vitejs.dev/config/ export default defineConfig({ plugins: [ intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api"), }, }), ], });תוסף ה-Vite
intlayer()משמש לשילוב Intlayer עם Vite. הוא מבטיח את בניית קובצי הצהרת התוכן ועוקב אחריהם במצב פיתוח. הוא מגדיר משתני סביבה של Intlayer בתוך אפליקציית Vite. בנוסף, הוא מספק כינויים (aliases) לשיפור הביצועים.אתחול Intlayer בנקודת הכניסה שלכם
קראו ל-
installIntlayer()לפני שרכיבים מותאמים אישית (custom elements) נרשמים, כך שה-singleton הגלובלי של השפה יהיה מוכן כאשר הרכיב הראשון מתחבר.src/main.tsהעתקת קודהעתקת הקוד ללוח
אם אתם משתמשים גם בהצהרות תוכן עם
md()(Markdown), התקינו בנוסף את מרנדר ה-markdown:src/main.tsהעתקת קודהעתקת הקוד ללוח
הצהרת התוכן שלכם
צרו ונהלו את הצהרות התוכן שלכם כדי לאחסן תרגומים:
src/app.content.tsהעתקת קודהעתקת הקוד ללוח
import { t, type Dictionary } from "intlayer"; const appContent = { key: "app", content: { title: "Vite + Lit", viteLogo: t({ en: "Vite logo", fr: "Logo Vite", es: "Logo Vite", he: "לוגו Vite", }), litLogo: t({ en: "Lit logo", fr: "Logo Lit", es: "Logo Lit", he: "לוגו Lit", }), count: t({ en: "count is {{count}}", fr: "le compte est {{count}}", es: "el recuento es {{count}}", he: "הספירה היא {{count}}", }), readTheDocs: t({ en: "Click on the Vite and Lit logos to learn more", fr: "Cliquez sur les logos Vite et Lit pour en savoir plus", es: "Haga clic en los logotipos de Vite y Lit para obtener más información", he: "לחצו על סמלי הלוגו של Vite ו-Lit כדי ללמוד עוד", }), }, } satisfies Dictionary; export default appContent;הצהרות התוכן שלכם יכולות להיות מוגדרות בכל מקום באפליקציה שלכם כל עוד הן כלולות בתיקיית
contentDir(כברירת מחדל,./src), ותואמות לסיומת קובץ הצהרת התוכן (כברירת מחדל,.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).לפרטים נוספים, עיינו ב-תיעוד הצהרת תוכן.
שימוש ב-Intlayer בתוך ה-LitElement שלכם
השתמשו ב-
useIntlayerבתוךLitElement. הוא מחזיר פרוקסי שלReactiveControllerשמפעיל באופן אוטומטי רינדור מחדש בכל פעם שהשפה הפעילה משתנה - ללא צורך בהגדרות נוספות.src/my-element.tsהעתקת קודהעתקת הקוד ללוח
כאשר אתם זקוקים למחרוזת המתורגמת במאפיין HTML טבעי (לדוגמה
alt,aria-label,title), תוכלו להשתמש במחרוזת המתורגמת במספר דרכים:typescriptהעתקת קודהעתקת הקוד ללוח
שינוי שפת התוכן שלכם
אופציונליכדי לשנות את שפת התוכן שלכם, השתמשו במתודה
setLocaleהנחשפת על ידי הבקרuseLocale.src/locale-switcher.tsהעתקת קודהעתקת הקוד ללוח
רינדור תוכן Markdown ו-HTML
אופציונליIntlayer תומך בהצהרות תוכן באמצעות
md()ו-html(). ב-Lit, הפלט המקומפל מוזרק כ-HTML גולמי באמצעות ההוראהunsafeHTML.src/app.content.tsהעתקת קודהעתקת הקוד ללוח
import { md, t, type Dictionary } from "intlayer"; const appContent = { key: "app", content: { // ... editNote: md( t({ en: "Edit `src/my-element.ts` and save to test **HMR**", fr: "Modifiez `src/my-element.ts` et enregistrez pour tester **HMR**", es: "Edite `src/my-element.ts` y guarde para probar **HMR**", he: "ערכו את `src/my-element.ts` ושמרו כדי לבדוק **HMR**", }) ), }, } satisfies Dictionary; export default appContent;רנדרו את ה-HTML המקומפל ברכיב שלכם:
src/my-element.tsהעתקת קודהעתקת הקוד ללוח
TIP String(content.editNote)קורא ל-toString()על ה-IntlayerNode, המחזיר את מחרוזת ה-Markdown הגולמית. העבירו אותה ל-compileMarkdownכדי לקבל מחרוזת HTML, ולאחר מכן רנדרו אותה באמצעות הוראתunsafeHTMLשל Lit.הוספת ניתוב מותאם לשפה לאפליקציה שלכם
אופציונליכדי ליצור נתיבים ייחודיים לכל שפה (שימושי ל-SEO), תוכלו להשתמש בנתב צד-לקוח לצד פונקציות העזר
localeMap/localeFlatMapשל Intlayer, ובתוסף Vite מסוגintlayerProxyעבור זיהוי שפה בצד השרת.תחילה, הוסיפו את
intlayerProxyלהגדרות ה-Vite שלכם:שימו לב שכדי להשתמש ב-
intlayerProxyבייצור, עליכם להעביר אתvite-intlayerמ-devDependenciesל-dependencies.החל מ-Intlayer גרסה 9,
intlayerProxy()ארוז ישירות בתוך התוסףintlayer()ומופעל כברירת מחדל באמצעות האפשרותrouting.enableProxy(trueכברירת מחדל). רישומו בנפרד כפי שמוצג להלן הוא כעת אופציונלי. הוא נשמר עבור תאימות לאחור ולהגדרות הדורשות שליטה בסדר התוספים. הגדירוrouting.enableProxy: falseכדי לבטל זאת. ראו את הערות השחרור של גרסה 9.vite.config.tsהעתקת קודהעתקת הקוד ללוח
import { defineConfig } from "vite"; import { intlayer } from "vite-intlayer"; export default defineConfig({ plugins: [ intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api"), }, }), ], });שינוי כתובת ה-URL כאשר השפה משתנה
אופציונליכדי לעדכן את כתובת ה-URL של הדפדפן כאשר השפה משתנה, השתמשו ב-
useRewriteURLלצד בורר השפות:src/locale-switcher.tsהעתקת קודהעתקת הקוד ללוח
החלפת מאפייני השפה והכיווניות ב-HTML
אופציונליעדכנו את המאפיינים
langו-dirשל תגית<html>כדי שיתאימו לשפה הנוכחית לצורכי נגישות ו-SEO.src/my-element.tsהעתקת קודהעתקת הקוד ללוח
חילוץ התוכן של הרכיבים שלכם
אופציונליאם יש לכם בסיס קוד קיים, המרת אלפי קבצים עלולה לגזול זמן רב.
כדי להקל על תהליך זה, Intlayer מציעה קומפיילר / מחלץ (extractor) כדי לשנות את הרכיבים שלכם ולחלץ את התוכן.
כדי להגדיר אותו, תוכלו להוסיף מקטע
compilerבקובץintlayer.config.tsשלכם:intlayer.config.tsהעתקת קודהעתקת הקוד ללוח
הריצו את ה-extractor כדי להמיר את הרכיבים שלכם ולחלץ את התוכן
bashהעתקת קודהעתקת הקוד ללוח
החל מגרסה 9, ה-
intlayerCompilerכלול בתוך התוסףintlayer. לכן אין צורך להוסיף אותו ידנית.עדכנו את
vite.config.tsשלכם כדי לכלול את התוסףintlayerCompiler:vite.config.tsהעתקת קודהעתקת הקוד ללוח
בנו את האפליקציה שלכם כדי להמיר את הרכיבים ולחלץ את התוכן
bashהעתקת קודהעתקת הקוד ללוח
(אופציונלי) מפת אתר (Sitemap) ו-robots.txt (בזמן בנייה)
Intlayer כולל מעצבים כגון generateSitemap ו-getMultilingualUrls המפיקים פלט רב-לשוני של sitemap.xml ו-robots.txt המוכן לסורקי מנועי חיפוש, אותו תוכלו לכתוב לתיקיית public/ של הפרויקט שלכם. בפועל, אתם מריצים סקריפט Node קטן לפני Vite (למשל hooks של predev / prebuild ב-npm) כך שקבצים אלה יהיו קיימים כאשר אתם בונים או מגישים את האפליקציה.
מפת אתר (Sitemap)
מחולל מפת האתר של Intlayer מכבד את הגדרות השפה שלכם וכולל את המטא-נתונים המקובלים עבור סורקים.
מפת האתר שנוצרת תומכת ב-namespace שלxhtml:link(הרחבות XML של hreflang). בניגוד למחוללים בסיסיים שפולטים רק כתובות URL שטוחות, Intlayer מחבר קישורים דו-כיווניים בין כל גרסה מותאמת שפה של כל דף (לדוגמה/about,/fr/aboutאו/about?lang=fr, בהתאם למצב הניתוב שלכם), מה שעוזר למנועי חיפוש לקשר בין כתובות URL מותאמות לשפה.
Robots.txt
השתמשו ב-getMultilingualUrls כך שרשומות Disallow יכסו כל איות מותאם שפה של נתיבים רגישים.
1. הוסיפו את generate-seo.mjs בשורש הפרויקט
העתקת הקוד ללוח
יש לוודא ש-intlayer מותקן כדי שהסקריפט יוכל לייבא אותו. הגדירו את SITE_URL בסביבה עבור ייצור (למשל ב-CI).
העדיפו אתgenerate-seo.mjsעבור Node ESM. אם אתם משתמשים ב-generate-seo.jsבמקום זאת, וודאו שמוגדר"type": "module"ב-package.json, או הריצו את Node עם תמיכת ESM מופעלת.
2. הריצו את הסקריפט לפני Vite
העתקת הקוד ללוח
התאימו זאת אם אתם משתמשים ב-pnpm או ב-yarn. תוכלו גם להפעיל את אותו הסקריפט מ-CI או משלב אחר אם זה מתאים לזרימת העבודה שלכם.
הגדרת TypeScript
וודאו שהגדרות ה-TypeScript שלכם כוללות את הטיפוסים שנוצרו אוטומטית.
העתקת הקוד ללוח
experimentalDecoratorsו-useDefineForClassFields: falseנדרשים על ידי Lit לתמיכה בדקורטורים (decorators).
הגדרת Git
מומלץ להתעלם מהקבצים שנוצרו על ידי Intlayer. הדבר מאפשר לכם להימנע מביצוע commit שלהם למאגר ה-Git שלכם.
לשם כך, תוכלו להוסיף את ההוראות הבאות לקובץ ה-.gitignore שלכם:
העתקת הקוד ללוח
תוסף ל-VS Code
כדי לשפר את חוויית הפיתוח שלכם עם Intlayer, תוכלו להתקין את התוסף הרשמי של Intlayer ל-VS Code.
תוסף זה מספק:
- השלמה אוטומטית (Autocompletion) עבור מפתחות תרגום.
- זיהוי שגיאות בזמן אמת עבור תרגומים חסרים.
- תצוגה מקדימה מוטמעת (Inline previews) של תוכן מתורגם.
- פעולות מהירות (Quick actions) ליצירה ועדכון פשוטים של תרגומים.
לפרטים נוספים על אופן השימוש בתוסף, עיינו ב-תיעוד התוסף של Intlayer ל-VS Code.
להעמיק עוד
כדי להעמיק עוד, תוכלו להטמיע את העורך החזותי או להעביר את התוכן שלכם לניהול חיצוני באמצעות ה-CMS.
שאלות נפוצות
ל-Vite אין דעה מוצקה לגבי i18n, ולכן הבחירה מגיעה מתוך האקו-סיסטם של Lit:
@lit/localize: האפשרות הרשמית, המבוססת על חילוץ XLIFF וחבילה מקומפלת אחת לכל שפה, כך שהחלפת שפה בזמן ריצה מצריכה מצב runtime mode.- מילון שנכתב ידנית המיובא לכל רכיב: ללא תלויות, ללא טיפוסיות, ללא כלים.
Intlayer: הפתרון המתקדם ביותר. תוכן מוצהר בכל מקום בבסיס הקוד שלכם (לצד כל רכיב או באופן מרוכז) ומקומפל על ידי תוסף Vite בזמן הבנייה, בעל טיפוסיות מלאה, עם תרגום באמצעות AI, עורך חזותי ו-CMS.
היתרון הייחודי ל-Vite הוא שתרגומים מפוענחים ועוברים tree-shaking בזמן ההידור במקום להיטען כ-JSON בזמן ריצה, כך שדף שולח רק את הרשומות שהוא מרנדר. ראו למה Intlayer ואת מבחן הביצועים.
הרבה פחות מהגדרה המבוססת על namespaces, מכיוון שדף לעולם אינו מוריד קטלוג שהוא אינו מרנדר. הקומפיילר בזמן הבנייה מחליף קריאות useIntlayer ברשומות המילון המדויקות שהרכיב משתמש בהן, כך שמפתחות שאינם בשימוש ושפות שאינן בשימוש מושמטים, ו-מילונים דינמיים מפצלים את השאר לפי שפה. בהשוואה לחלופות הרגילות, Intlayer מפחית את גודל החבילה והדף בעד 50%. ראו אופטימיזציית חבילה ואת מבחן הביצועים.
במידה רבה, כן. עקבו אחר סקירת מתאמי התאימות (compat adapters) כדי להעביר את התוכן. תוכלו גם להגר בהדרגה: תוסף sync JSON שומר על קטלוגי ה-JSON הקיימים שלכם כמקור האמת ומייצר מהם מילוני Intlayer, כך ששתי השכבות נשארות מסונכרנות בזמן שאתם מעבירים רכיבים בזה אחר זה.
כן. תוסף sync JSON שומר על קובצי ה-/messages/{locale}/{namespace}.json שלכם כמקור האמת ומייצר מהם מילוני Intlayer, בשני הכיוונים. תוסף sync PO עושה את אותו הדבר עבור קטלוגי gettext, ו-קבצים לפי שפה (per locale files) מאפשרים לכם לפצל תוכן לפי שפה במקום לקבץ שפות בקובץ אחד.
לא. הריצו npx intlayer extract ו-Intlayer יקרא את הרכיבים שלכם, ישלוף את המחרוזות המוצגות למשתמש ויכתוב קובץ .content לצד כל אחד מהם, כך שתוכלו לסקור diff במקום להעתיק מחרוזות לקטלוג אחת אחת. שלב 12 במדריך זה מפרט זאת.
עבור צינור עבודה אוטומטי לחלוטין, הקומפיילר של Intlayer עושה את אותו הדבר בזמן הבנייה: הוא סורק את קוד המקור שלכם ב-JSX, TSX, Vue ו-Svelte בכל שינוי, מייצר את המילונים ושומר עליהם מסונכרנים באמצעות hot module replacement, כך שאין צורך לתחזק מפתחות ידנית כלל.
ישנן שתי מגבלות שכדאי להכיר לפני הפעלת הקומפיילר. הוא פועל באמצעות ניתוח סטטי, כך שמחרוזות שקיימות רק בזמן ריצה, כגון קודי שגיאה מ-API או שדות CMS, נשארות מחוץ להישג ידו. כמו כן, עליו להבדיל בין טקסט המוצג למשתמש לבין לוגיקת אפליקציה כגון className="active" או קוד סטטוס, מה שמצריך מעט הערות בבסיס קוד גדול. פקודת extract נמנעת משתיהן על ידי השארתכם בתהליך הבקרה.
חמישה כלים, כולם אופציונליים:
- תוסף VS Code: קפיצה ממפתח
useIntlayerלקובץ התוכן שמצהיר עליו, חילוץ תוכן מרכיב, והרצת build, fill, test, push ו-pull מלוח הפקודות (command palette) או מלשונית Intlayer ייעודית. - שרת LSP: אותה מודעות בכל עורך התומך ב-LSP, עם מעבר להגדרה (go to definition), מציאת כל המופעים (find all references), תצוגה מקדימה בריחוף (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, בתוספת יכולת לכל סביבת פיתוח, המלמדות סוכן בינה מלאכותית את מבנה הניתוב שלכם ואת סוגי צמתי התוכן. - תוסף ESLint: הכלל
no-raw-textמסמן מחרוזות מקודדות בקוד (hardcoded), עם כללים נוספים עבור מפתחות מילון סטטיים ותוכן שאינו בשימוש.
