הגדרת next-intl לבינאום Next.js

מדוע לוקליזציה שוברת ניתוב ומטא-נתונים

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

אם ההחלטה מתקבלת בשלושה מקומות בו-זמנית, מקבלים התנגשות נתיבים — חלק מהכתובות מחזירות לוקאל לא נכון, חלק מפנות מחדש במעגל, וקישורים פנימיים מובילים לשפה שהמשתמש לא בחר.

תקלה טיפוסית שנייה — כפילות canonical. כל עוד העמוד חי בכתובת אחת, תג קנוני נבנה באופן טריוויאלי. עם ניתוב רב-לשוני אותה ישות נגישה דרך כמה נתיבים, ואם canonical ו-hreflang נוצרים בשכבות שונות, מנוע החיפוש רואה גרסאות מתחרות של אותו עמוד.

זה לא מתוקן בעריכת תבנית אלא במקור אמת אחיד: הלוקאל והנתיב חייבים להיות מחושבים ממקום אחד, והכתובות החלופיות — להיות מיוצרות מאותה רשימת לוקאלים שממנה נוצרים הנתיבים.

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

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

מה מספקת אינטרנציונליזציה נכונה

הגדרה נכונה של next-intl מסירה את הכאב העיקרי של אתרים רב-לשוניים — חוסר סנכרון בין נתיבים, מילונים וסימון. כאשר לוקאלים, קידומות נתיבים וכותרת hreflang נוצרים ממקור אחד, כל גרסת שפה מקבלת כתובת קנונית משלה.

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

מהירות הוספת שפה מפסיקה להיות תלויה בגודל הפרויקט. מילון חדש מחובר כקובץ נפרד עם מבנה שטוח של מפתחות, הנתיבים קולטים את הלוקאל אוטומטית, ו-middleware מזהה את השפה לפי כותרת הבקשה ו-cookie. בפועל זה הופך השקת שפה מפרויקט של שבועות למשימה של כמה ימים — בלי לכתוב מחדש קומפוננטות.

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

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

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

השוואת גישות לריבוי שפות

הבחירה בכלי לריבוי שפות קובעת כמה עבודה ידנית תישאר לצוות לאחר השקת השפה הראשונה. בפועל בוחרים בין שלוש אפשרויות: מילונים עצמאיים, ספרייה חיצונית ו-next-intl — כל אחת מכסה סוג אחר של משימות ויש לה גבולות שמעבר להם היא מתחילה להפריע.

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

ספריות חיצוניות מכסות בלשנות מורכבת, אך מוסיפות שכבת הפשטה בין האפליקציה לפריימוורק. כל עדכון של Next.js הופך לבדיקת תאימות, וקומפוננטות שרת דורשות פתרונות עוקפים.

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

איך מתבצעת next-intl התאמה בפרויקט

התאמת בינלאומיות ב-Next.js היא לא "לחבר ספרייה", אלא לתכנן ניתוב, מילונים והתנהגות בעת החלפת שפה כך שאף שפה לא תשבור SEO ולא תאבד תוכן. אנו עובדים בשלבים, שכל אחד מהם מסתיים בתוצאה ניתנת לבדיקה.

1. ביקורת הלוקליזציה הנוכחית. אנו בוחנים כיצד הטקסטים מאורגנים כעת: מוטבעים בקומפוננטות, מונחים בקבצים מפוזרים או כבר הוצאו למילונים. אנו מתעדים את השפות שבאמת נדרשות ואת המקומות שבהם התוכן מוזן באופן דינמי — דווקא שם לרוב צצות מחרוזות לא מתורגמות.
2. תכנון סכמת הניתוב. אנו קובעים האם הלוקאל יהיה בנתיב (/en/..., /de/...) או בתת-דומיין, מגדירים את לוקאל ברירת המחדל ואת כללי ההפניות. מסכמה זו תלוי האינדוקס: לכל שפה חייבת להיות כתובת משל עצמה ו-hreflang תקין.
3. חיבור המילונים. אנו מפצלים את התרגומים לפי מרחבי שמות — כלליים, עמודיים, שירותיים — ומגדירים טעינה של רק הסט הנדרש עבור נתיב מסוים. כך גודל הנתונים המועברים לא גדל יחד עם מספר השפות.
4. תרגום הממשק והתוכן. אנו מחליפים מחרוזות מוטבעות במפתחות, ועוברים בנפרד על תבניות תאריכים, מספרים וצורות רבים — הן מתנהגות באופן שונה בשפות שונות ודורשות כללים מפורשים, ולא הצבה תבניתית.
5. בדיקה בכל השפות. אנו מריצים כל נתיב בכל לוקאל: החלפת שפה, קישורים ישירים, הפניות, מפתחות חסרים. בנפרד אנו בודקים שבעת החלפת שפה המשתמש נשאר באותו עמוד, ולא נופל לדף הבית.
6. מסירת תיעוד. אנו מוסרים את סכמת הניתוב, מבנה המילונים, כללים להוספת שפה חדשה וצ'ק-ליסט לבדיקה. צוות הלקוח מרחיב מכאן והלאה את הלוקליזציה ללא מעורבותנו.

עיקרון מרכזי: שפה חדשה מתווספת על ידי עריכת קונפיגורציה וקובץ תרגומים, ולא על ידי כתיבה מחדש של נתיבים. אם כדי להפעיל לוקאל יש לגעת בקוד העמודים — הסכמה תוכננה שלא כהלכה, ואנו מתקנים זאת לפני המסירה.

ארטיפקטים לאחר הטמעת בינאום

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

• תצורת ניתוב ולוקאלים. קובץ הגדרות עם רשימת השפות, לוקאל ברירת המחדל ואסטרטגיית הקידומות: /en/catalog לעומת catalog עם זיהוי שפה לפי כותרת הבקשה. בנפרד מוגדרת ההתנהגות עבור שורש האתר ועבור לוקאלים לא קיימים — הפניה מחדש או עמוד 404.
• סכמת נתיבים. טבלת התאמה "כתובת ציבורית → קובץ עמוד → מילון", כולל מקטעים מקוננים וחלקים דינמיים. לפיה מפתח חדש מבין את המבנה תוך דקות, ולא משחזר אותו מתוך הקוד.
• מילוני הודעות. מחולקים לפי מרחבי שמות: טקסטים כלליים של הממשק, עמודים, הודעות דואר, שגיאות מערכת. הפורמט אחיד לכל השפות, המפתחות אינם משוכפלים בין הקבצים.
• נוהל עדכון תרגומים. מתואר הסדר: מי עורך את שפת המקור, כיצד השינויים מגיעים למתרגם, מה קורה עם מפתחות שאינם קיימים בשפת היעד. מצוינת התנהגות האפליקציה כאשר חסר תרגום — הצבת טקסט המקור במקום מחרוזת ריקה.
• בדיקות שלמות. השוואה אוטומטית של מילונים: אי-התאמת מפתחות בין שפות ומחרוזות שאינן בשימוש נתפסות לפני הבנייה, ולא בפרודקשן.
• תיעוד לעורכים. הנחיות למנהל התוכן: היכן נמצא הטקסט, כיצד להוסיף שפה, מה אסור לשנות במפתחות כדי לא לשבור את התצוגה.
• סכמת חיבור שפות חדשות. רשימה שלב-אחר-שלב: להוסיף לוקאל לתצורה, ליצור מילון, לבדוק נתיבים ומטא-נתונים של עמודים. שפה אחת מתווספת ללא שינויים ברכיבים.

את הערכה מעבירים יחד עם פירוט: מראים היכן מה נמצא וכיצד לבדוק את התוצאה באופן מקומי. תארו את המשימה — נחזור עם הערכה ותוכנית לפי הסטאק שלכם.

מקרה בוחן: האצת השקת שפה חדשה פי 4

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

השפה הרביעית ארכה שלושה שבועות, וכמעט מיד צצו שגיאות לוקליזציה — блокים לא מתורגמים, תאריכים ומספרים "שזזו", והודעות בשפה של המשתמש הקודם.

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

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

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

מה השתנה במספרים

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

במה שונה next-intl מלוקליזציה ידנית?

לוקליזציה ידנית מתחילה במילון תמים בקובץ נפרד, אך מחזיקה מעמד בדיוק עד הפער הראשון בין השפות. לאחר מכן מופיעים מפתחות שקיימים באנגלית ונשכחו בגרמנית, מחרוזות עם החלפה מהצורה Привет, {name}, שנבנו בשרשור, ותאריכים שעוצבו ידנית לכל שוק.

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

next-intl הופך את המודל הזה על פיו: התרגומים הופכים למשאב עם טיפוסים, ולא לאוסף מחרוזות. המפתחות מוגדרים פעם אחת, ופנייה למפתח שאינו קיים שוברת את הבנייה, ולא את הפרודקשן — תרגום שנשכח בענף שפה חדש נתפס לפני השחרור.

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

כאב נפרד של הגישה הידנית — נטיות וצורות רבים. בעברית «פריט 1», «2 פריטים», «5 פריטים» — צורות שונות, בערבית יש שש, וטיפול בכך דרך תנאים בקוד הופך במהרה ללוגיקה מסועפת ובלתי קריאה.

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

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

עם next-intl שפה חדשה מחוברת באמצעות קונפיגורציה וקובץ תרגומים, ומבנה המפתחות נשאר משותף: עריכה במקום אחד אינה מתפצלת בין הענפים. בדיוק משום כך, בפרויקטים עם שתי שפות ויותר, לוקליזציה ידנית מתייקרת עם כל שחרור, ואילו הגישה דרך next-intl — לא.

ספקות טכניים בנוגע לבינאום

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

כיצד לבצע מטמון לדפים אם השפה תלויה ב-URL?

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

מה לעשות עם תוכן דינמי ותרגומים ממסד הנתונים?

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

האם ניתן להוסיף שפה חדשה בלי לשכתב את הקוד?

כן. הוספת לוקאל היא קובץ מילון חדש ושורה אחת בהגדרות הנתיבים. הקומפוננטות והלוגיקה נשארות ללא שינוי, כי הן עובדות עם מפתחות ולא עם טקסט ישירות. אנו בונים מראש את מבנה המפתחות כך שסדר המילים והנטיות בשפות שונות לא ישברו את הפריסה.

אם נותרו ספקות בנוגע לסטאק שלכם — תארו את המשימה, ונחזור עם הערכה ותוכנית.

בואו נדון במשימת הלוקליזציה שלכם

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

מה שעוזר להאיץ את תחילת הפרויקט:

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

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

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