كيفية ترجمة ملفات i18next JSON في React & Next.js (2026)

لقد انتهيت للتو من تطبيق React يحتاج إلى أن يكون جاهزًا في 12 لغة بحلول يوم الجمعة القادم. تعيش ملفاتك المحلية في public/locales/en/common.json، لديك 340 مفتاحًا لكل لغة محلية، وتبدو الرموز داخل سلاسلك مثل {{userName}} و {{count}} منتشرة عبر الكائنات المتداخلة. تقوم بلصق JSON في ChatGPT، وتعود بنتيجة تحتوي على {{ nombreUsuario }}، ومسافات إضافية، ونصف مفاتيح الجمع معاد تسميتها. يتعطل تطبيقك عند الإنشاء.

إذا حاولت أتمتة ترجمة i18next JSON، فأنت تعرف هذا الألم. تنسيق JSON مرن، وهذا هو بالضبط السبب الذي يجعل معظم أدوات الترجمة تفسده. المشكلة الحقيقية ليست جودة نموذج اللغة - بل هي أن أدوات الذكاء الاصطناعي المخصصة للمستهلكين لا تفهم القواعد الهيكلية لـ i18next.

يرشدك هذا الدليل عبر ما يجعل i18next JSON مختلفًا عن تنسيقات اللغات المحلية الأخرى، ولماذا تتسبب أساليب الترجمة الساذجة في تعطيل تطبيقات React و Next.js، وكيفية أتمتة الترجمة بأمان عبر عشرات اللغات المحلية دون مراجعة يدوية لكل مفتاح.

ما هو i18next JSON ولماذا الترجمة صعبة

i18next هي مكتبة i18n الأكثر استخدامًا في بيئة JavaScript. تدعم React (react-i18next)، Next.js (next-i18next، App Router next-intl)، Vue، وخدمات الواجهة الخلفية لـ Node. تقوم بتخزين السلاسل القابلة للترجمة في ملفات JSON مسطحة أو متداخلة، ملف واحد لكل لغة محلية.

يبدو الملف النموذجي كما يلي:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

يبدو هذا بسيطًا، ولكن ثلاثة أمور تجعل ترجمته خطيرة باستخدام الذكاء الاصطناعي للأغراض العامة.

رموز الاستيفاء هي هيكلية وليست نصية

التسلسل {{userName}} ليس كلمة - إنه عنصر نائب يقوم وقت التشغيل باستبداله بالبيانات. أضف مسافة ({{ userName }})، أو أعد تسميته، أو ترجم المعرف الداخلي وسيفشل وقت التشغيل بصمت أو يرمي خطأ. يقوم بعض المترجمين بمساعدة بتحويل {{count}} إلى {{conteo}} في الإسبانية. يحاول تطبيقك الآن استيفاء متغير غير موجود ويعرض العنصر النائب الخام للمستخدم.

مفاتيح الجمع هي لواحق سحرية

يكتشف i18next صيغ الجمع بواسطة اللواحق: _zero, _one, _two, _few, _many, _other. هذه ليست سلاسل عشوائية - يجب أن تتطابق مع فئات الجمع في CLDR للغة المحلية المستهدفة. تستخدم الإنجليزية فقط _one و _other. تستخدم الروسية والعربية والبولندية ما يصل إلى ست فئات. إذا أسقط مترجمك _other أو أعاد تسميتها، فستتعطل سلسلة الرجوع.

يجب أن تبقى المفاتيح المتداخلة سليمة

على عكس ملفات Gettext .po، التي هي أزواج مفتاح-قيمة مسطحة، يمكن لملفات i18next أن تتداخل بشكل عشوائي. قد يقوم مترجم كسول بتسطيح الهيكل، أو تغيير أسماء المفاتيح لتتطابق مع النص المترجم، أو إعادة ترتيب الكائنات. لم يعد استدعاء t('cart.items_other') في الكود يعمل.

حلول سيئة يجربها المطورون أولاً

يمر كل فريق بنفس دورة الفشل المكونة من ثلاث مراحل قبل أن يستثمروا في حل حقيقي.

المرحلة الأولى: اللصق في ChatGPT

تقوم بنسخ 200 مفتاح إلى ChatGPT، وتسأل "translate this JSON to Spanish" (ترجم ملف JSON هذا إلى الإسبانية)، وتلصق النتيجة مرة أخرى. يعمل ذلك لـ 180 مفتاحًا. عشرين مفتاحًا أضيفت فيها مسافات داخل {{...}}، وثلاثة أعيدت كتابة لواحق الجمع فيها، وعلامة <strong> واحدة ترجمت إلى <fuerte>. إما أن يفشل بناء تطبيقك أو يتم شحن سلاسل معطوبة بصمت إلى الإنتاج.

المرحلة الثانية: واجهة برمجة تطبيقات Google Translate

تقوم بربط واجهة برمجة تطبيقات Google Translate REST، وتكرر عبر JSON الخاص بك، وترسل كل قيمة. السرعة رائعة. الجودة ليست كذلك. تعالج واجهة برمجة تطبيقات Google كل سلسلة بمعزل عن غيرها - لا يوجد سياق حول تطبيقك، ولا فهم بأن {{count}} هو عنصر نائب، ولا وعي بأن المفتاح cart.empty يختلف عن cart.items_one. لا يزال يتعين عليك إجراء مراجعة بشرية لكل مفتاح.

المرحلة الثالثة: منصات TMS التجارية

تقوم بالاشتراك في نظام إدارة الترجمة. يفرضون رسومًا لكل كلمة، ويتطلبون تكاملات GitHub، ويقيدونك بمقاعد شهرية. بالنسبة لمشروع جانبي أو تطبيق مستقل، تتدهور الجدوى الاقتصادية بسرعة - ولا يزال يواجهك نفس مشاكل تلف العناصر النائبة إذا لم يقم محركهم بتحليل تنسيق i18next على وجه التحديد.

تظهر نفس أنماط الفشل في سير عمل Gettext أيضًا. يغطي دليلنا حول كيفية ترجمة ملفات po. دون كسر متغيرات الكود المشكلة الموازية لـ WordPress ومجموعات Gettext الأخرى.

النهج الآمن: الترجمة الواعية بالصياغة

الطريقة الوحيدة الموثوقة لترجمة i18next JSON على نطاق واسع هي باستخدام أداة تقوم بتحليل التنسيق أولاً، وتثبيت الصياغة، ثم إرسال النص القابل للترجمة فقط إلى الذكاء الاصطناعي.

إليك ما تفعله المعالجة الواعية بالصياغة داخليًا:

1. تحلل JSON إلى شجرة تجريدية، مع الحفاظ على مسارات المفاتيح والتداخل.
2. تحدد رموز الاستيفاء ({{name}}, {{count, number}}, {{date, datetime}}) وتستبدلها بمعرفات العناصر النائبة.
3. تحدد علامات HTML داخل مكونات Trans (<0>, <strong>, <br/>) وتثبتها.
4. تكتشف مفاتيح الجمع بواسطة اللاحقة وتعينها إلى قواعد CLDR للغة المحلية المستهدفة.
5. ترسل النص النظيف فقط إلى LLM مع سياق حول مسار المفتاح.
6. تعيد إدخال الرموز والعلامات الأصلية في مواضعها الدقيقة.
7. تتحقق من صحة المخرجات - إذا كان أي عنصر نائب مفقودًا أو مشوهًا، تعود إلى المصدر.

هذا هو نفس المبدأ الذي يجعل ترجمة PO المستندة إلى السحابة آمنة. إذا كنت مهتمًا بالهندسة المعمارية الأساسية، فإن مقارنة جودة ترجمة الذكاء الاصطناعي الخاصة بنا توضح كيف تتعامل نماذج LLM المختلفة مع هذه القيود.

خطوة بخطوة: ترجمة i18next JSON باستخدام SimplePoTranslate

يدعم SimplePoTranslate ملفات i18next JSON بشكل أساسي في خطط Pro و Lifetime. تغطي الطبقة المجانية حاليًا ملفات .po و .pot - قم بالترقية أو استخدم نسخة تجريبية للوصول إلى JSON.

1. إعداد ملف المصدر الخاص بك

استخدم ملفك الإنجليزي (أو اللغة المحلية المصدر) كملف رئيسي. تأكد من أنه JSON صالح ويحتوي على جميع المفاتيح التي يستخدمها تطبيقك. خطأ شائع هو ترك مفاتيح قديمة أو غير مستخدمة، مما يحرق حصتك من الترجمة لسلاسل لن تعرضها أبدًا.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. الرفع إلى SimplePoTranslate

سجل الدخول إلى لوحة التحكم الخاصة بك، انقر فوق ترجمة جديدة، وقم بتحميل common.json. تكتشف المنصة تنسيق i18next تلقائيًا. اختر لغتك المستهدفة من بين اللغات المحلية الـ 41 المدعومة، وحدد نبرة (احترافية، عادية، تسويقية)، ثم أرسل.

3. دع المحرك يعمل

تحت الغطاء، يتم تحليل الملف، وتقسيمه إلى دفعات آمنة، وترجمته بالتوازي. يتم تثبيت رموز الاستيفاء. ويتم الحفاظ على لواحق الجمع وتعيينها إلى قواعد CLDR للغة المحلية المستهدفة. وتبقى علامات HTML داخل مكونات Trans سليمة.

4. تحميل ملف ZIP

ستتلقى ملف ZIP يحتوي على ملف JSON المترجم بالإضافة إلى تنسيقات بديلة (.php لتطبيقات PHP، و .po للتوافق بين الأدوات). ضع ملف JSON في public/locales/es/common.json وأعد النشر.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. تكرار أو تجميع

بالنسبة لجميع اللغات المحلية المستهدفة الـ 12، أرسل 12 مهمة. تغطي حصص خطة Pro عشرات من تطبيقات SaaS النموذجية. بالنسبة للمستودعات ذات الملفات المتعددة النطاقات، قم بتحميل كل ملف على حدة أو اجمعها بالتسلسل.

دمج الترجمات مرة أخرى في تطبيقك

بمجرد أن يكون لديك ملفات JSON مترجمة، يصبح الدمج هو الجزء السهل. بعض الملاحظات:

• تحقق من فئات الجمع. قم بإجراء اختبار سريع لكل لغة محلية: اعرض مكونًا بـ count={0}، count={1}، count={5} وتأكد من أن الثلاثة تنتج السلسلة الصحيحة.
• التحقق من اللغات المحلية ذات الاتجاه من اليمين إلى اليسار (RTL). إذا قمت بالترجمة إلى العربية أو العبرية أو الفارسية، فإن واجهة المستخدم الخاصة بك تحتاج إلى CSS يدعم RTL. يغطي دليل ترجمة ووردبريس RTL أنماط CSS التي تنطبق على تطبيقات React أيضًا.
• إعداد سلسلة احتياطية. قم بتكوين i18next للرجوع إلى الإنجليزية إذا كان المفتاح مفقودًا، حتى لا تتعطل تجربة المستخدمين في حالات النشر الجزئية.
• تأمين ملف المصدر الخاص بك في CI. أضف فحصًا يرفض طلبات السحب (PRs) التي يتم فيها تغيير en/common.json دون إعادة إنشاء اللغات المحلية الأخرى. يعد اختلاف الترجمة أكبر سبب واحد لأخطاء i18n في الإنتاج.

بالنسبة للفرق التي تعمل عبر React و Next.js والجانب الخادم، فإن إنتاج كل تنسيق من مصدر واحد يعد مكسبًا كبيرًا. يوضح منشورنا حول ملف واحد يدخل، خمسة تنسيقات تخرج لماذا يعتبر الإخراج متعدد التنسيقات مهمًا للصيانة طويلة الأمد.

عندما لا يكون JSON كافياً: التعامل مع الحالات المعقدة

تتطلب بعض الحالات الخاصة عناية إضافية.

تنسيق رسائل ICU

إذا كان مشروعك يستخدم صياغة ICU ({count, plural, one {1 item} other {# items}})، فإن i18next يتعامل معها على أنها استيفاء ولكن الهيكل أكثر تعقيدًا. تأكد من أن أداة الترجمة الخاصة بك تتعرف على معلمات ICU ولا تترجم أسماء الفئات مثل one، other، أو معرفات التنسيق مثل plural، number، date.

مكون Trans مع عقد React

يقوم <Trans> بعرض مكونات React داخل السلاسل المترجمة، مفهرسة حسب الفهرس (<0>, <1>). يجب على المترجم الحفاظ على الترتيب الدقيق للعلامات. يتعامل قفل الصياغة في SimplePoTranslate مع هذا الأمر، ولكن إذا كنت تستخدم أداة مختلفة، تحقق قبل النشر.

ملفات النطاق (Namespace)

تقوم التطبيقات الكبيرة بتقسيم اللغات المحلية إلى نطاقات: common.json, dashboard.json, checkout.json. ترجم كل ملف بشكل مستقل - لا تدمجها. تكون جودة السياق أعلى عندما تظل مسارات مفاتيح كل نطاق محددة النطاق.

تجميع كل ذلك

ترجمة i18next JSON لتطبيق React أو Next.js لا تتعلق باختيار أفضل نموذج للذكاء الاصطناعي. بل تتعلق باحترام القواعد الهيكلية للتنسيق: يجب أن تظل الاستيفاءات، لواحق الجمع، المفاتيح المتداخلة، وعلامات HTML سليمة خلال عملية الترجمة ذهابًا وإيابًا. تتعامل أدوات الذكاء الاصطناعي الاستهلاكية مع JSON كنص غير منظم. بينما تقوم الأدوات الواعية بالصياغة بتحليله كبيانات منظمة ولا تلمس إلا الأجزاء القابلة للترجمة.

إذا كنت تقوم بشحن تطبيق متعدد اللغات وكنت تنسخ وتلصق JSON في واجهات الدردشة، فأنت تعرف بالفعل التكلفة: ساعات من المراجعة اليدوية لكل لغة محلية، أخطاء عشوائية في الإنتاج، ومجموعة متزايدة من صيغ الجمع المعطلة. يزيل مسار العمل الواعي بالتنسيق كل نمط من أنماط الفشل هذه.

هل أنت مستعد لترجمة ملفات i18next JSON الخاصة بك بأمان؟ جرب SimplePoTranslate مجانًا - لا يلزم وجود بطاقة ائتمان. قم بالرفع مرة واحدة، وقم بالشحن في 41 لغة.