التدويل يبدأ سهلاً. ملف JSON واحد، ودالة t()، وانتهى الأمر. ثم ينمو المنتج، ويضيف ثلاثة مطورين نصوصاً بأساليب مختلفة، ويعيد التسويق كتابة نصوص التهيئة، ولا أحد يعرف أي النصوص العربية قديم ولا هل ما زال ذلك المفتاح مستخدماً أصلاً.
الإجابة المختصرة: إطار i18n هو الجزء السهل. وما ينكسر على نطاق واسع هو سير العمل — كيف تُضاف النصوص وتُترجَم وتُراجَع وتُتقاعَد. قرّر ذلك مبكراً، لأن إضافته لاحقاً تعني تدقيق كل مفتاح كتبته يوماً.
هذا الدليل يغطي الهيكلة وسير العمل. أما للنطاق الأوسع لدعم العربية، فراجع الدليل الكامل لتعريب التطبيقات والمواقع.
ابنِ الطبقة حتى لو أطلقت بلغة واحدة
أرخص قرار تعريب متاح: جهّز i18n في المرحلة الأولى، حتى لو صدرت العربية لاحقاً.
ما يكلفه الآن: أيام قليلة. ثبّت مكتبة، وأخرج النصوص من الكود وأنت تكتبها، واستخدم خصائص CSS المنطقية.
وما يكلفه لاحقاً: أسابيع. فكل نص مكتوب داخل الكود يجب البحث عنه في المشروع كله — وهي تختبئ في رسائل التحقق، وقوالب البريد، ومعالجات الأخطاء، وتسميات الرسوم البيانية، ومولّدات PDF. والفرق تجد باستمرار ضعف ما قدّرته.
والفارق كبير بما يكفي ليكون بناء الطبقة مجدياً حتى لو لم تصدر العربية أبداً. فإن صدرت وفّرت أسابيع؛ وإن لم تصدر خسرت أياماً.
هيكلة ملفات الترجمة
قسّم بحسب الميزة لا بحسب النوع. الغريزة الأولى buttons.json وlabels.json وerrors.json. وهذا يتوسّع بشكل سيئ، لأن العمل على الدفع يعني لمس كل ملف.
locales/
en/
common.json
auth.json
checkout.json
ar/
common.json
auth.json
checkout.json
وتسمية المفاتيح يجب أن تصف المعنى لا المحتوى. فـauth.login.submitButton ينجو من تغيير النص؛ أما auth.login.signInNow فيصبح كذبة لحظة إعادة التسويق كتابته إلى «ابدأ الآن».
ولا تستخدم النص الإنجليزي كمفتاح أبداً. يبدو مريحاً ويعني أن كل تعديل نصي يصبح إعادة تسمية مفتاح في المشروع كله وفي كل ملف ترجمة.
وأبقِ مجموعة المفاتيح نفسها في اللغتين. فالمفتاح الموجود بالإنجليزية والغائب بالعربية يجب أن يُفشل فحصاً، لا أن يعرض بديلاً بصمت في الإنتاج.
الجموع: العربية لها ست صيغ
هنا ينكسر i18n الساذج، وينكسر بصمت.
الإنجليزية لها فئتا جمع. والعربية لها ست: صفر، ومفرد، ومثنى، وقليل، وكثير، وأخرى. والمكتبة التي تعالج المفرد والجمع فقط ستنتج عربية خاطئة نحوياً لمعظم الكميات.
{
"items": {
"zero": "لا توجد عناصر",
"one": "عنصر واحد",
"two": "عنصران",
"few": "{{count}} عناصر",
"many": "{{count}} عنصراً",
"other": "{{count}} عنصر"
}
}
تحقّق من دعم مكتبتك لقواعد جموع CLDR قبل الالتزام بها. فـi18next وFormatJS وحزمة intl في Flutter تدعمها كلها. أما الحل المكتوب يدوياً فشبه مؤكد أنه لا يدعمها، والمخرجات خاطئة بطريقة لا يراها المراجع الناطق بالإنجليزية.
وصيغة المثنى مهمة. فللعربية صيغة خاصة للاثنين تحديداً، والخطأ فيها ملحوظ فوراً للقارئ الأصلي بشكل يُقرأ كإهمال.
الاستيفاء وترتيب الكلمات
لا تدمج أجزاء نصوص مترجمة أبداً. فترتيب الكلمات يختلف بين اللغات، والجمل المركّبة تنتج كلاماً بلا معنى.
// خطأ — يفترض ترتيب الكلمات الإنجليزي
t("youHave") + " " + count + " " + t("newMessages")
// صواب — نص واحد بمعنى واحد
t("newMessages", { count })
وأعطِ المتغيرات أسماء ذات دلالة. فـ{{name}} و{{count}} يخبران المترجم بما يعمل عليه؛ أما {{0}} و{{1}} فلا، والمترجم الذي لا يرى السياق سيخمّن.
وانتبه للاستيفاء ثنائي الاتجاه. فالقيمة اللاتينية داخل جملة عربية تحتاج عزلاً وإلا وقعت علامات الترقيم خطأً — راجع الأرقام والعملات والصيغ.
ووفّر سياقاً للمفاتيح الملتبسة. كلمة «Post» فعل واسم؛ والمترجم الذي يرى الكلمة وحدها لا يعرف أيهما. ومعظم المكتبات تدعم حقل سياق أو وصف — استخدمه، فالبديل أن يسأل المترجم أو، والأسوأ، أن يخمّن.
سير العمل: الجزء الذي ينكسر فعلاً
الإعداد التقني يوم واحد. أما سير العمل فهو ما يحدد هل ستبقى العربية دقيقة بعد سنة.
والمقاربات الثلاث الشائعة:
| المقاربة | تناسب | نقطة الضعف |
|---|---|---|
| ملفات داخل المستودع | الفرق الصغيرة، والنصوص التي يكتبها المطورون | غير المطورين لا يستطيعون المساهمة |
| منصة إدارة ترجمات | المنتجات النامية، والمترجمون الخارجيون | التكلفة وتعقيد المزامنة |
| جدول بيانات مع سكربت استيراد | الميزانيات الصغيرة، والتحديثات المتفرقة | يدوي وعرضة للخطأ على نطاق واسع |
ولمعظم المنتجات الخليجية، الملفات داخل المستودع تعمل جيداً في البداية، وتصبح منصة الترجمة مجدية حين يحتاج غير المطورين تعديل النصوص بانتظام.
وأياً كان اختيارك، ثلاث قواعد ثابتة:
أفشل البناء عند غياب مفتاح. فالمفتاح الموجود بالإنجليزية والغائب بالعربية يجب أن يكسر التكامل المستمر، لا أن يعرض بديلاً بصمت في الإنتاج حيث لا يلاحظه أحد.
واكشف المفاتيح غير المستخدمة. فالملفات تتراكم فيها نصوص لميزات حُذفت قبل سنتين. والفحص الدوري للمفاتيح الغائبة عن الكود يمنع هذا من النمو بلا حد.
ولا تنشر ترجمة آلية للإنتاج بلا مراجعة أبداً. فالمسودة الأولى من الترجمة الآلية معقولة للمحتوى الكبير. أما نشرها بلا مراجعة فينتج نصاً يميّزه القارئ المتمكن فوراً كإنتاج آلة، وهذا يكلف من المصداقية أكثر مما وفّرته الترجمة من وقت.
ملاحظات على الأطر
React / Next.js — next-intl وreact-i18next يعالجان الجموع العربية صحيحاً. وNext.js في App Router يستخدم مقطع مسار [lang]، ما يمنحك رابطاً حقيقياً لكل لغة وبالتالي معالجة hreflang سليمة للبحث.
Flutter — حزمة intl مع ملفات ARB. والوصول المولَّد بأنواع محددة يعني أن المفتاح المفقود خطأ تصريف لا بديل وقت التشغيل، وهي أقوى صورة ممكنة لقاعدة «أفشل عند غياب المفتاح».
الباك إند — لا تنسه. فالبريد والرسائل النصية وفواتير PDF ورسائل أخطاء الواجهات البرمجية كلها تحتاج ترجمة، وهي أكثر السطوح إغفالاً. والتطبيق العربي الذي يرسل بريداً معاملاتياً بالإنجليزية تناقض شائع وقابل للتفادي.
قائمة تحقق
- طبقة i18n مبنية في المرحلة الأولى بصرف النظر عن لغات الإطلاق
- الملفات مقسّمة بحسب الميزة لا نوع النص
- المفاتيح تصف المعنى لا المحتوى
- لا نصوص إنجليزية مستخدمة كمفاتيح
- التحقق من دعم المكتبة لقواعد جموع CLDR بصيغ العربية الست
- لا دمج نصوص لتكوين جمل
- متغيرات استيفاء مسمّاة مع ملاحظات سياق
- عزل ثنائي الاتجاه للقيم اللاتينية المستوفاة
- التكامل المستمر يفشل عند غياب مفتاح
- فحص دوري للمفاتيح غير المستخدمة
- ترجمة سطوح الباك إند: البريد والرسائل وPDF وأخطاء الواجهات
- مراجعة متحدث أصلي قبل الإصدار، دائماً
اقرأ أيضاً
- الدليل الكامل لتعريب التطبيقات والمواقع — طبقات التعريب الست.
- RTL في CSS — النصف التخطيطي من المشكلة.
- الأرقام والعملات والصيغ — استيفاء الأرقام والعملة.
- دعم العربية وRTL في React Native — خصوصيات الموبايل.
- أخطاء التعريب الشائعة — ما يقع خطأً عملياً.
الأسئلة الشائعة
كم صيغة جمع في العربية؟
ست: صفر، ومفرد، ومثنى، وقليل، وكثير، وأخرى. والإنجليزية لها اثنتان، فأي مكتبة أو حل مكتوب يدوياً يعالج المفرد والجمع فقط سينتج عربية خاطئة نحوياً لمعظم الكميات. تحقّق من دعم قواعد جموع CLDR قبل اختيار مكتبة — فـi18next وFormatJS وحزمة intl في Flutter تدعمها.
هل أجهّز i18n إن كنت أطلق بالإنجليزية فقط؟
نعم، إن كانت العربية في خارطة طريقك. بناء الطبقة يكلف أياماً الآن؛ وإضافتها لاحقاً تكلف أسابيع، لأن النصوص المكتوبة داخل الكود تختبئ في رسائل التحقق وقوالب البريد ومعالجات الأخطاء ومولّدات PDF. والفارق كبير بما يكفي ليكون مجدياً حتى لو لم تصدر العربية أبداً.
هل أستخدم النص الإنجليزي كمفتاح ترجمة؟
لا. يبدو مريحاً لكنه يعني أن كل تعديل نصي يصبح إعادة تسمية مفتاح في المشروع كله وكل ملف ترجمة. استخدم مفاتيح تصف المعنى — auth.login.submitButton — بحيث لا تلمس إعادة كتابة نص الزر أي كود.
هل أستطيع استخدام الترجمة الآلية لنصوصي العربية؟
كمسودة أولى للمحتوى الكبير نعم. أما نشرها بلا مراجعة بشرية فينتج نصاً يميّزه القارئ المتمكن فوراً كإنتاج آلة، وهي لا تستطيع اتخاذ قرارات مستوى اللغة ولا تكييف الأمثلة. وكلفة المصداقية تتجاوز الوقت الموفَّر عادةً.
لماذا لا أدمج النصوص المترجمة؟
ترتيب الكلمات يختلف بين اللغات، فالجملة المركّبة من أجزاء بالترتيب الإنجليزي تنتج كلاماً بلا معنى بالعربية. استخدم نصاً واحداً لكل جملة مع متغيرات استيفاء مسمّاة، وأعطِ المترجمين ملاحظات سياق للمفاتيح الملتبسة.
ما أشيع إغفال في i18n؟
سطوح الباك إند. فالبريد والرسائل النصية وفواتير PDF ونصوص أخطاء الواجهات البرمجية تُترك بالإنجليزية باستمرار بينما الواجهة مترجمة بالكامل. والتطبيق العربي الذي يرسل بريداً معاملاتياً بالإنجليزية تناقض شائع وقابل للتفادي تماماً.
كيف أمنع ملفات الترجمة من التعفّن؟
أفشل التكامل المستمر حين يوجد مفتاح بلغة ويغيب بأخرى، وشغّل فحصاً دورياً للمفاتيح التي لم تعد مذكورة في الكود. وبلا الاثنين، تتراكم في الملفات نصوص قديمة لميزات محذوفة وتعرض بديلاً إنجليزياً بصمت في الإنتاج حيث لا يلاحظه أحد.
الخلاصة
ابنِ طبقة i18n في المرحلة الأولى. تكلف أياماً الآن وأسابيع لاحقاً، والحساب صحيح حتى لو لم تصدر العربية أبداً.
وافحص دعم الجموع قبل اختيار مكتبة. فصيغ العربية الست هي تحديداً ما تخطئ فيه التنفيذات الساذجة، والخطأ غير مرئي للمراجعين الذين لا يقرأون العربية.
واستثمر في سير العمل لا في الإعداد وحده. فإفشال البناء عند غياب المفاتيح وفحص غير المستخدمة هو ما يبقي العربية دقيقة بعد الإصدار الأول، وهناك تتدهور معظم المنتجات بصمت.
تخطط لمنتج ثنائي اللغة؟ تواصل معنا — نبني بالعربية أولاً، فطبقة i18n موجودة من أول التزام في المستودع. اطّلع على خدمات تطوير الويب وتطبيقات الموبايل.