كيفية اكتشاف الترجمات المفقودة قبل أن يكتشفها مستخدموك

نادراً ما تؤدي الترجمة المفقودة إلى ظهور خطأ استثنائي أو توقف التطبيق. بناءً على إعداداتك، إما أنها تعرض النص الإنجليزي لمستخدم ياباني، أو تطبع checkout.summary.total مباشرة على الشاشة في بيئة الإنتاج. كلا الأمرين يتم شحنه في الإصدار، ويجتاز مراجعة الكود، ويكتشفه العميل بدلاً من أن تكتشفه أنت.

جدول المحتويات

هذا ينطبق مهما كانت المكتبة التي تستخدمها

لا شيء هنا محصور ببيئة برمجية معينة. تعمل طبقات الاكتشاف أدناه بنفس الطريقة على i18next أو react-i18next أو next-intl أو react-intl أو vue-i18n أو next-translate أو Lingui، لأنها تحل المفاتيح وتفشل بنفس الآلية.

الأدوات قابلة للنقل أيضاً. إذا كانت نصوصك موجودة اليوم في كتالوجات JSON، فإن إضافة Sync JSON توجه Intlayer إلى تلك الملفات، لتحصل على أوامر التدقيق، والتعبئة، والاختبار دون نقل محتواك أو تغيير استيراد واحد:

import { syncJSON } from "@intlayer/sync-json-plugin";

const config = {
  plugins: [
    syncJSON({
      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
      format: "i18next", // أو "icu" لمكتبات next-intl / react-intl
    }),
  ],
};

export default config;

إذا كنت تفضل الإبقاء على واجهة وقت التشغيل كما هي، فإن محولات التوافق تعيد تسمية useTranslation و $t وما شابهها على مستوى أداة الحزم (Bundler). في كلا الحالتين، تعامل مع الأوامر أدناه كتطبيق عملي للفكرة وليس كشرط إلزامي.

لماذا تكون الترجمات المفقودة غير مرئية؟

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

آلية التراجع التلقائي (Fallback) تزيد الأمر سوءاً. فالصفحة التي تظهر باللغة الإنجليزية في صمت تبدو سليمة تماماً للمطور الناطق بالإنجليزية ولجميع الاختبارات الآلية. المشكلة لا تظهر إلا للشخص الذي لا يستطيع قراءة الإنجليزية.

لذا فإن السؤال ليس "كيف أتعامل مع الترجمات المفقودة أثناء وقت التشغيل". بل هو "كيف أجعل دمج فرع يحتوي على ترجمة مفقودة أمراً مستحيلاً".

الطبقات الأربع التي يمكنك الإمساك بها من خلالها

تلتقط كل طبقة ما تعجز عنه الطبقات الأخرى. وتحتاج عملياً إلى أكثر من واحدة.

الفجوة التي تقع فيها معظم الفرق هي الصف الثالث: فهم يعلمون أن مفاتيحهم صالحة برمجياً، لكن لا توجد أداة تتحقق من أن جميع اللغات الثماني عشرة تحتوي على ترجمات فعلية.

الطبقة الأولى: جعل المفتاح نوعاً (Type) وليس مجرد نص

t("checkout.summry.total") خطأ إملائي يمر عبر مرحلة البناء والترجمة البرمجية دون اعتراض. إذا كانت مفاتيحك نصوصاً عادية، فكل إعادة تسمية تمثل مخاطرة في الإنتاج، وكل عملية حذف تترك وراءها مفاتيح مهجورة.

المفاتيح المعرفة بأنواع بيانات صارمة تحول هذه المشكلة إلى خطأ بناء يوقف الكود. يدعم react-i18next ذلك عبر دمج التصريحات، ويستنتجه next-intl من بنية الرسائل، ويستخرج Lingui المعرفات من نصوص المصدر، وينشئ Intlayer أنواعاً دقيقة من ملفات الإعلان. كلها تؤدي الغرض؛ الفارق يكمن في مقدار الجهد اللازم للضبط.

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

الطبقة الثانية: فحص النصوص التي لم تتحول لمفاتيح (Linting)

الترجمة التي لا تجدها غالباً ما تكون نصاً لم يتم نقله للملفات المترجمة إطلاقاً. النص المكتوب مباشرة داخل المكون لا يمكن لأي تدقيق كتالوجات اكتشافه، لأنه ببساطة غير مسجل في النظام.

تعالج إضافة ESLint الخاصة بـ Intlayer هذه النقطة عبر قاعدة no-raw-text، بالإضافة إلى no-unused-content للحالة المعاكسة: محتوى تم التصريح عنه ولم يعد مستخدماً في أي مكان.

import intlayer from "@intlayer/eslint-plugin";

export default [
  intlayer.configs.recommended,
  {
    rules: {
      "@intlayer/no-raw-text": "error",
      "@intlayer/no-unused-content": "warn",
    },
  },
];

قاعدة no-unused-content تمنع تضخم الكتالوجات بلا نهاية. فالمفاتيح المهجورة لا تكسر الكود، لكنها ترفع فواتير شركات الترجمة. تجد القائمة الكاملة للقواعد في توثيق إضافة ESLint.

الطبقة الثالثة: تدقيق تغطية اللغات

هذه هي الطبقة التي تجيب على السؤال الأهم. يوفرها Intlayer كأمر عبر واجهة الأوامر:

npx intlayer content test

يقوم الأمر بقراءة اللغات المحددة والقواميس، ثم يوضح بدقة أي المفاتيح تفتقر إلى أي لغات، وفي أي ملف تقع.

تفصيلة هامة قبل ربطها في مسارات العمل: تطبع واجهة الأوامر تقريراً ولكنها تنهي التنفيذ بالرمز صفر (نجاح). فإذا وضعتها في الـ CI على أمل إيقاف البناء، ستحصل على علامة خضراء وتقرير طويل لن يقرأه أحد. لمنع البناء وإيقافه، استخدم واجهة البرمجة التطبيقية أدناه.

الطبقة الرابعة: التأكيد الصريح في مجموعة الاختبارات

توفر لك دالة listMissingTranslations() نفس تقرير التدقيق كبيانات برمجية، وهو المطلوب تماماً لبوابة فحص البناء.

/* @vitest-environment node */
import { listMissingTranslations } from "intlayer/cli";
import { describe, expect, it } from "vitest";

describe("translations", () => {
  it("لا توجد لغات مطلوبة مفقودة", async () => {
    const result = await listMissingTranslations();

    if (result.missingRequiredLocales.length > 0) {
      console.log(result.missingTranslations);
    }

    expect(result.missingRequiredLocales).toHaveLength(0);
  });
});

تعيد الدالة ثلاثة حقول جوهرية:

• missingTranslations: المفاتيح واللغات المفقودة واسم الملف لكل منها. يُفضل طباعته عند فشل الاختبار.
• missingLocales: اتحاد كافة اللغات التي ينقصها محتوى عبر جميع المفاتيح.
• missingRequiredLocales: محصور فقط في requiredLocales المحددة في إعداداتك، أو جميع اللغات إن لم تُحدد.

requiredLocales تجعل الفحص قابلاً للتطبيق العملي

دعم ثماني عشرة لغة لا يعني إلزامية اكتمالها جميعاً بنسبة 100% لنشر الكود. تضع معظم الفرق تصنيفاً يوقف النشر وتصنيفاً يتم العمل عليه تدريجياً.

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.JAPANESE,
      Locales.POLISH,
    ],
    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

دون requiredLocales، تصبح كل لغة معلنة ملزمة للبناء ويتعطل النشر انتظاراً لآخر ترجمة، مما ينتهي بقيام الفريق بتعطيل الفحص كلياً.

كشف الفجوات الموجودة بالفعل في بيئة الإنتاج

تمنع الطبقات السابقة حدوث فجوات جديدة. وللتطبيقات العاملة بالفعل، تفيدك خطوتان:

التوطين الزائف (Pseudolocalization). استخدم لغة تجريبية يتم فيها تشويه كل نص مثل [!!! Ĉĥéçķöũţ !!!]. أي نص يظهر بالإنجليزية العادية هو نص مكتوب بشكل ثابت في الكود. يكشف ذلك في عشر دقائق ما يعجز عنه تدقيق الكتالوجات.

الزحف الآلي على موقعك (Crawling). إذا كنت توفر روابط مخصصة لكل لغة، اطلب عينة من الصفحات وابحث في كود الـ HTML عن النصوص الإنجليزية. ظهور "Add to cart" في رابط /ja/ يشير فوراً لترجمة مفقودة أو تراجع غير مقصود.

curl -s https://example.com/ja/checkout | grep -c "Add to cart"

ملء الفجوات

بمجرد تحديد ما ينقصك، يملأ الأمر intlayer fill الخانات الشاغرة، ويمكن للخيار autoFill توليد ملفات اللغات بمجرد كتابة المحتوى. راجع autoFill.

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

أخطاء شائعة

• التعامل مع الـ Fallback كشبكة حماية. هو مجرد حل إسcleaافي للعرض، والنص الإنجليزي الصامت خطأ لا يُبلغ عنه أحد.
• الاعتماد على تقرير CLI لإيقاف CI. يخرج الأمر دائماً بالرمز صفر. استخدم التأكيد في الاختبارات.
• إلزامية كافة اللغات كشرط وحيد. يؤدي لحذف الفحص عند أول تعطل للإطلاق.
• فحص الكتالوجات وإهمال الشاشة المعروضة. النصوص الثابتة لا تظهر في الكتالوجات أصلاً.
• اختبار اللغة الافتراضية فقط. اللغة الوحيدة المضمون عدم نقصها.
• الاكتفاء بالتعبئة الآلية كحل نهائي. فحص أخضر ونصوص رديئة لم يقرأها بشر.

للمزيد من القراءة

• اختبار المحتوى: تدقيق CLI، واجهة برمجة التطبيقات البرمجية وتأكيدات الواجهة
• قواعد إضافة ESLint، بما فيها no-raw-text و no-unused-content
• autoFill: إنشاء ملفات الإعلان لكل لغة
• مرجع الإعدادات: locales, requiredLocales, defaultLocale
• تقارير المقارنة المعيارية عبر أطر العمل
• محول التوافق مع i18next
• ما يشمله التدويل الفعلي
• التدويل على مستوى المكونات مقابل التدويل المركزي