כיצד לתרגם אפליקציית React עם react-i18next

הגדירו את react-i18next, תרגמו את הקובץ en.json ליותר מ־40 שפות באמצעות בינה מלאכותית, ולאחר מכן תנו לתוסף הדפדפן של PTC (‏Private Translation Cloud) לסקור את אפליקציית React הפעילה בכל גרסה. מדריך זה מכסה בינאום (i18n) של React מקצה לקצה: הגדרת react-i18next, טיפול בריבוי ובתוכן דינמי, תרגום קובץ ה־en.json שלכם ליותר מ־40 שפות עם PTC, והחלפת שפות בזמן ריצה. בסיום התהליך תהיה לכם מערכת לוקליזציה עובדת של React, מוכנה להפצה. לסקירה כללית של הכלי העצמאי לתרגום JSON, ראו תרגום קובצי JSON אונליין עם בינה מלאכותית.

איך נראית אפליקציית React שעברה לוקליזציה

אפליקציית React שבה:

• כל המחרוזות הפונות למשתמש נמצאות בקובצי תרגום מסוג JSON תחת src/i18n/locales/ (או public/locales/).
• בורר שפות מאפשר מעבר בין אנגלית, ספרדית, צרפתית וגרמנית.
• תוכן דינמי (שמות משתמשים, מונים, תאריכים) מוכנס למחרוזות (interpolation) בצורה נכונה לפי הלוקאל.
• צורות ריבוי עוקבות אחר הכללים של כל שפת יעד.
• קובצי ה־.json המתורגמים מופקים על ידי PTC, ולא נכתבים ידנית.

שלב 1: הקמת תשתית לאפליקציית React + TypeScript עם Vite

מדריך זה משתמש באפליקציית React + TypeScript שנבנתה עם Vite. אם אתם מוסיפים את react-i18next לאפליקציה קיימת, דלגו לשלב 2.

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

פעולה זו מפעילה שרת פיתוח ופותחת את דף ברירת המחדל של Vite + React בדפדפן שלכם.

שלב 2: התקנת react-i18next והחלפת מחרוזות קבועות בקוד ב־t()

npm install i18next react-i18next

צרו את מבנה התיקיות עבור ה־i18n ב־React שלכם:

src/
  i18n/
    locales/
      en.json

הוסיפו את המחרוזות באנגלית לקובץ src/i18n/locales/en.json:

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

רכיב React טיפוסי עם מחרוזות קבועות בקוד (hardcoded):

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

החליפו את הטקסט הקבוע ב־hook‏ useTranslation:

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

הפונקציה useTranslation() מחזירה:

• t() – מחפשת מחרוזת לפי מפתח.
• i18n – מאפשרת לשנות שפות באופן תכנותי.

שלב 3: טעינה אוטומטית של כל קובצי ה־JSON של הלוקאלים עם import.meta.glob

צרו את הקובץ src/i18n/index.ts כדי להגדיר את i18next ולטעון אוטומטית קובצי תרגום. התבנית import.meta.glob גורמת לכך שכל קובץ .json שתוסיפו ל־src/i18n/locales/ יזוהה אוטומטית. אין צורך בייבוא ידני כשמוסיפים שפות חדשות:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources =
  | string
  | { [k: string]: TranslationResources }
  | TranslationResources[];

const modules = import.meta.glob<{ default: Record<string, TranslationResources> }>(
  './locales/*.json',
  { eager: true }
);

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};
for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

ייבאו את i18n לפני רינדור האפליקציה. פתחו את src/main.tsx והוסיפו את הייבוא:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import './i18n'; // <- add this

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

אם תדלגו על שלב זה, t() יחזיר מפתחות תרגום במקום את הטקסט המתורגם.

שלב 4: הכנסת משתנים, צורות ריבוי וקישורים לפי המוסכמות של i18next

הכנסת משתנים עם {{variableName}}

השתמשו בתחביר {{variableName}} ב־JSON שלכם והעבירו את הערך ל־t(). עדכנו את en.json:

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

const user = { firstName: 'Sarah' };
<p>{t('userGreeting', { firstName: user.firstName })}</p>

הארגומנט השני ל־t() הוא אובייקט עם הערכים שברצונכם להחליף. ניתן להשתמש בכמה משתנים שצריך.

טיפול בריבוי עם סיומות המפתח _one / _other

השתמשו בתבנית הסיומות _one / _other. המשתנה חייב להיקרא count:

{
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}

<p>{t('newMessages', { count: messageCount })}</p>

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

תרגום קישורים ו־HTML עם רכיב Trans

עבור תרגומים המכילים אלמנטים של HTML כמו קישורים או טקסט מודגש, השתמשו ברכיב Trans:

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

התגיות <1> ו־<3> הן מצייני מיקום מבוססי אינדקס הממופים לאלמנטים צאצאים (הספירה מתחילה מ־0):

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
  I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
</Trans>

כך אלמנטי ה־JSX נשארים ברכיב, בעוד שהמתרגמים יכולים לשנות את סדר הטקסט שמסביב בצורה טבעית.

עיצוב תאריכים, מספרים ומטבעות עם Intl

השתמשו במעצבי Intl במקום להטמיע מחרוזות עיצוב בתוך התרגומים שלכם:

const formatDate = (date: Date, locale: string) =>
  new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);

const formatCurrency = (amount: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);

const { i18n } = useTranslation();
<p>{formatDate(new Date(), i18n.language)}</p>
<p>{formatCurrency(199.99, i18n.language, 'EUR')}</p>

שלב 5: תרגום קובצי ה־JSON עם PTC ב־5 שלבים

כעת יש לכם את en.json ואתם צריכים להפיק את es.json, ‏fr.json, ‏de.json וכו'. PTC תוכנן בדיוק למטרה זו.

1. התחילו פרויקט PTC ובחרו באנגלית כשפת המקור. תקופת הניסיון בחינם מכסה 20,000 מילים ל־2 שפות, ללא צורך בכרטיס אשראי.
2. העלו את en.json. המערכת של PTC מנתחת את המבנה המקונן, מזהה מצייני מיקום של i18next (כמו {{name}}, ‏{{count}}), ומזהה את סיומות הריבוי (_one, ‏_other).
3. הוסיפו תיאור קצר של אפליקציית React שלכם וקהל היעד שלה. PTC משתמש בהקשר זה כדי להתאים את הטון והטרמינולוגיה בכל שפה.
4. בחרו שפות יעד ואשרו. PTC מפיק קובץ .json מתורגם אחד לכל שפת יעד, הזהה מבנית למקור. אותם מפתחות, אותו קינון, אותם מצייני מיקום. הערכים הם אלו שמתורגמים.
5. הכניסו את הקבצים לתיקיית src/i18n/locales/. בזכות הטעינה האוטומטית עם import.meta.glob שהגדרתם בשלב 3, הקבצים החדשים יעבדו מיד ללא שינויי קוד.

לאחר שתרגמתם את הקובץ הראשון שלכם עם PTC, תוכלו לעבור לתהליך אוטומטי. חברו את מאגר ה־GitHub, ה־GitLab או ה־Bitbucket שלכם באמצעות אינטגרציית Git, או השתמשו ב־API של PTC כדי לחבר את התרגום לצינור ה־CI/CD שלכם. מחרוזות חדשות ב־en.json יפעילו תרגום אוטומטי. PTC יפתח pull request עם קובצי שפות היעד המעודכנים.

שלב 6: אימות ההגדרה עם בורר שפות

הוסיפו כפתורי שפה כדי לוודא שהגדרת ה־react-i18next שלכם עובדת:

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

הפונקציה i18n.changeLanguage() מפעילה רינדור מחדש של כל רכיב המשתמש ב־useTranslation(), כך שכל ממשק המשתמש מתעדכן מיד. ללא טעינה מחדש של הדף.

זיהוי אוטומטי של שפת המשתמש עם i18next-browser-languagedetector

התקינו את i18next-browser-languagedetector כדי לטעון אוטומטית את השפה הנכונה מהגדרות הדפדפן של המשתמש, מהכתובת (URL) או מהעדפות שמורות:

npm install i18next-browser-languagedetector

import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'de', 'ar'],
    interpolation: { escapeValue: false },
    detection: {
      order: ['querystring', 'localStorage', 'cookie', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

טעינה מושהית (Lazy-load) של תרגומים עם i18next-http-backend

כברירת מחדל, כל קובצי התרגום נארזים (bundled) בזמן הבנייה. עבור אפליקציות עם שפות רבות, השתמשו ב־i18next-http-backend כדי להביא רק את השפה שהמשתמש באמת צריך:

npm install i18next-http-backend

import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr'],
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

העבירו את קובצי התרגום שלכם ל־public/locales/ כדי שיוגשו כנכסים סטטיים:

public/
  locales/
    en/translation.json
    fr/translation.json

מעבר לצרפתית יביא כעת את /locales/fr/translation.json לפי דרישה במקום לארוז אותו מראש. החבילה הראשונית (bundle) תישאר קטנה ללא קשר למספר השפות שבהן אתם תומכים.

סקירת תרגום חזותית של אפליקציית React הפעילה שלכם – הפצה ללא QA ידני בכל גרסה

לאחר ש־PTC תרגם את קובץ ה־en.json שלכם, אתם עדיין צריכים לוודא את תקינות אפליקציית React הפעילה. תווית מתורגמת עלולה לחרוג מגבולות הכפתור בגרמנית. המילה "Save" עלולה להיות מתורגמת כשם עצם בצרפתית כשהממשק היה זקוק לפועל. מחרוזת אנגלית קבועה בקוד מחוץ ל־t() תרונדר ללא תרגום, ללא קשר למספר השפות שאתם מפיצים.

ה־AI Visual QA של PTC מחליף את שלב ה־QA הידני. עבור אפליקציות מבוססות דפדפן כמו React, הגרסה המתאימה היא תוסף הדפדפן. התקינו אותו פעם אחת והקליטו walkthrough קצר של תהליכי המשתמש הקריטיים באפליקציית React שלכם (כניסה למערכת, פיצ'ר מרכזי, הגדרות). מאותו רגע, PTC מריץ מחדש את ההקלטה בכל שפת יעד לאחר כל עדכון תרגום, מצלם כל מסך ובודק את התוצאה המרונדרת:

• תיקונים בקובצי התרגום כאשר PTC שולט בהם. PTC יתרגם מחדש חלק דיבור שגוי, יבחר מילה נרדפת קצרה יותר שמתאימה לכפתור, או יפיק מחדש צורת ריבוי.
• הנחיות ל־Cursor / Claude Code כאשר הבעיה היא בקוד הרכיב שלכם. מחרוזת אנגלית קבועה בקוד מחוץ ל־t(), משפט שנבנה על ידי שרשור מחרוזות במקום t('key', { var }), או רכיב Trans חסר עבור תרגומי טקסט עשיר.

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

תרגום הערות גרסה, דפי שיווק ואימיילים ללקוחות

הערות הגרסה, דפי השיווק, דפי הנחיתה והאימיילים ללקוחות שלכם נמצאים מחוץ ל־en.json. הכלי העתקה והדבקה לתרגום של PTC מטפל בטקסטים אלו באותו פרויקט. הדביקו את טקסט המקור בלוח הבקרה של PTC, בחרו שפות יעד, וקבלו תרגומים המשתמשים באותו מילון מונחים ובאותו טון מותג כמו מחרוזות ממשק המשתמש של ה־React שלכם.

תרגום תגובות משתמשים, פוסטים ותוצאות חיפוש עם ה־API של PTC

תגובות משתמשים, פוסטים, תוצאות חיפוש וכל תוכן אחר המיוצר על ידי משתמשים שאפליקציית React שלכם מטפלת בו זקוקים לתרגום עם הגעתם. ה־PTC REST API מתרגם תוכן זה לפי דרישה עם אימות Bearer-token, תוך שימוש באותו מילון מונחים וטון מותג כמו בתרגומי ה־en.json שלכם.

כעת תרגמו את קובץ ה־en.json שלכם

התחילו את תקופת הניסיון של 30 יום בחינם – 20,000 מילים ל־2 שפות, ללא כרטיס אשראי. שני מסלולים:

• ידני: העלו את src/i18n/locales/en.json בדף תרגום ה־JSON.
• מבוסס CI: חברו את מאגר ה־Git שלכם דרך ה־API של PTC והתרגומים יתבצעו אוטומטית בכל push.

בכל מקרה, התקינו את תוסף הדפדפן ותנו ל־AI Visual QA לוודא את אפליקציית React הפעילה שלכם בכל שפה לפני ההפצה.