إعداد ترجمة Flutter باستخدام flutter_localizations وgen-l10n وملفات ARB، مع placeholders وتوليد AppLocalizations وربط اللغات بالتطبيق.
المولد الصحيح للترجمة
gen-l10n مدمج بأدوات Flutter ولا يحتاج flutter_gen_runner لتوليد رسائل ARB. أضف flutter_localizations من SDK واجعل قيد intl متوافقًا معها ثم فعّل generate في قسم flutter. حدد arb-dir وtemplate-arb-file وoutput-localization-file في l10n.yaml، واستعمل flutter gen-l10n عند الحاجة. مسار الاستيراد يعتمد مكان خرج المولد الفعلي، لا مسارًا افتراضيًا من دليل قديم.
الرسائل معاملات وليست جمع نصوص
عرّف placeholder وبياناته في ARB ثم استدع الدالة التي يولدها AppLocalizations بدل استبدال اسم متغير داخل String يدويًا. اربط localizationsDelegates وsupportedLocales الناتجين بالتطبيق، واترك locale دون قيمة لإتباع سياسة الجهاز أو عيّن اختيارًا محفوظًا عمدًا. اختبر صيغة الجمع والتاريخ واتجاه layout وعدم وجود مفتاح مترجم، لا كلمتي زر فقط.
ملفات ARB وحدود الرسالة
ضع ملفًا افتراضيًا مثل app_en.arb وملفًا عربيًا بالرسائل نفسها. لكل رسالة key ثابت لا يعتمد على النص الذي يراه المستخدم، ويمكن إضافة وصف سياق للمترجم. إن كان النص يتضمن اسمًا أو عددًا فاستعمل placeholder أو صيغة جمع بدل جمع أجزاء جملة؛ ترتيبها قد يختلف بين اللغات. لا تجعل الترجمة تغيّر معرف منتج أو قيمة تحفظ في قاعدة البيانات، ولا تنقل تنسيق الحقل المالي إلى استبدال نص عشوائي.
التوليد والإعدادات
عرّف flutter_localizations من SDK وintl بما يحله SDK المستعمل، وفعّل generate في قسم flutter الموجود بدل تكرار قسم جديد. l10n.yaml ملف منفصل عن pubspec ويحدد مجلد ARB والملف القالب واسم خرج الترجمة. شغل flutter pub get ثم flutter gen-l10n واقرأ أي خطأ في أسماء placeholders أو بنية JSON. لا تعدل AppLocalizations المولد يدويًا لأنه سيعاد إنتاجه من الملفات، ولا تفترض أن حفظ الملف وحده شغل المولد في كل بيئة IDE.
ربط الشجرة واتجاهها
استورد الملف من مسار خرج المولد الحقيقي ثم استخدم localizationsDelegates وsupportedLocales التي يولدها. اقرأ AppLocalizations.of(context) من سياق داخل MaterialApp لا من سياق يسبق وجود delegates. ترك locale بلا اختيار صريح يتيح سياسة حل اللغات المدعومة، أما اختيار المستخدم فيحتاج State وحفظًا إذا أردت استمراره. اتجاه العربية يأتي من منظومة WidgetsLocalizations؛ لا تعكس النصوص يدويًا ولا تبدل كل Row دون مراجعة دلالته.
فحوص الترجمة
اختبر رسالة ذات اسم عربي وعدد وتاريخ وخطأ تحقق، ولغة جهاز غير مدعومة، ونصوصًا أطول من الإنجليزية. ابحث عن Strings صلبة في الأزرار وtooltips وعناوين النوافذ ورسائل الفشل، لا الصفحة الرئيسية فقط. راجع النص مع سياق فعلي لأن ترجمة key منفصل لا تحدد دائمًا معنى كلمة قصيرة. افحص واجهة في الاتجاهين مع تكبير الخط وتأكد أن حقول البريد والأكواد تظهر بالاتجاه المناسب داخل الصفحة العربية دون تغيير اللغة العامة.
توافق الفريق
ثبت طريقة توليد الرسائل ضمن أوامر المشروع وCI، وتحقق أن ملف ARB الافتراضي موجود وأن كل placeholder مطابق بين اللغات. أضف اختبارًا يبني واجهة بالعربية ويجد رسالة مترجمة بدل key، وآخر يجرب locale غير مدعومة وفق fallback المقصود. هذا يكشف نقص الربط الذي قد لا يظهر في شاشة تعمل بلغة الجهاز الافتراضية.
مراجعة أخيرة للتطبيق
استخدم رسائل ذات سياق يفهمه المترجم.
مثال الشفرة بعد المراجعة
اقرأ التعليقات ومتطلبات الإعداد قبل النقل إلى مشروعك. أمثلة الواجهات ذات main مستقلة، أما العقود والمقاطع الأصلية وملفات الإعداد فموضح نطاقها داخل المثال.
# Merge into pubspec.yaml using versions compatible with your Flutter SDK.
dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any
flutter:
generate: true
# l10n.yaml (separate file):
# arb-dir: lib/l10n
# template-arb-file: app_en.arb
# output-localization-file: app_localizations.dart
# lib/l10n/app_en.arb:
# {"hello":"Hello {name}","@hello":{"placeholders":{"name":{"type":"String"}}}}
# lib/l10n/app_ar.arb:
# {"hello":"مرحبا {name}"}
# Then: flutter pub get && flutter gen-l10n
# Import the generated AppLocalizations from its actual output location.
# Bind its localizationsDelegates and supportedLocales to MaterialApp.الصور والفيديو التوضيحي
قد تعرض الوسائط إصدارًا أقدم. اعتمد الخطوات النصية المصححة عند اختلاف إعدادات المنصة أو أسماء الواجهات.

مرجع للتنفيذ
راجع التوثيق الخاص بهذا الموضوع وطابق إعداداته مع إصدار أدوات مشروعك. اختبر السلوك المستهدف وحالة الفشل قبل إدماج المثال في تطبيق منشور.
تطبيق gen-l10n في Flutter في مشروعك
اجعل مفاتيح الترجمة ثابتة، واستخدم placeholders والجمع بدل تجميع النصوص يدويًا؛ اختبر RTL واللغة الاحتياطية والنص الطويل.
مراجع الموضوع: docs.flutter.dev — internationalization






