כיצד לתרגם אפליקציית 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/).
• בורר שפות מאפשר מעבר בין אנגלית, ספרדית, צרפתית וגרמנית.
• תוכן דינמי (שמות משתמשים, מונים, תאריכים) מוטמע בצורה נכונה לפי הכללים של כל שפה.
• צורות ריבוי עוקבות אחר הכללים של כל שפת יעד.
• קובצי ה־.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() – מחפשת מחרוזת לפי מפתח (key).
• 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 יפתח PR עם קובצי שפות היעד המעודכנים.

שלב 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) קצר של תהליכי המשתמש הקריטיים באפליקציה (התחברות, פיצ'ר מרכזי, הגדרות). מאותו רגע, PTC מריץ מחדש את ההקלטה בכל שפת יעד אחרי כל עדכון תרגום, מצלם כל מסך ובודק את התוצאה המרונדרת:

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

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

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

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

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

תגובות משתמשים, פוסטים, תוצאות חיפוש וכל תוכן אחר שנוצר על ידי משתמשים (UGC) באפליקציית ה־React שלכם זקוקים לתרגום ברגע הגעתם. ה־REST API של PTC מתרגם תוכן זה לפי דרישה עם אימות 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 הפעילה שלכם בכל שפה לפני ההפצה.