---
title: توطين Flutter: ARB وintl وgen-l10n | Smartcat
description: أعدّ توطين Flutter باستخدام ملفات ARB وgen-l10n: العناصر النائبة وصيغ الجمع والمقارنة بين intl وeasy_localization واختبار الكتابة من اليمين إلى اليسار وفحص سير عمل الترجمة.
canonical: https://ar.smartcat.com/flutter-localization/
language: ar
updated: 2026-11-03
---

# توطين Flutter: ARB وintl وgen-l10n | Smartcat

## توطين Flutter: شرح ملفات ARB وintl وgen-l10n

يكيّف توطين Flutter رسائل التطبيق وواجهته مع اللغات المختلفة. في سير العمل المدمج، تدعم flutter_localizations عناصر واجهة إطار العمل المُوطَّنة، بينما تُنتج موارد ARB وgen-l10n واجهة AppLocalizations البرمجية للتطبيق، وتدعم intl الرسائل والتنسيقات الحسّاسة للغة.

- [احجز عرضًا توضيحيًا](https://www.smartcat.com/book-a-demo/?main-cta2-flutter-localization)

- [ابدأ تجربتك المجانية](https://smartcat.com/sign-up?main-cta3-flutter-localization)

## إعداد flutter_localizations وgen-l10n

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

استخدم مولّد توطين واحدًا واجعل مواقع مدخلاته ومخرجاته صريحة. يفترض المثال أدناه وجود تطبيق Flutter قائم بقيود SDK الخاصة به وإعدادات المشروع المعتادة.

ادمج الإدخالات ذات الصلة في pubspec.yaml ، ولا تكرّر قسمَي dependencies أو flutter :

dependencies:
flutter:
sdk: flutter
flutter_localizations:
sdk: flutter
intl: any

flutter:
generate: true حُلّ التبعيات باستخدام flutter pub get . يتّبع الإدخال intl: any نمط الإعداد الرسمي، ما يسمح لآلية حلّ التبعيات باختيار الإصدار المتوافق مع Flutter SDK. واحتفظ بملف القفل الخاص بالتطبيق وبعملية مراجعة التبعيات المعتادة.

أنشئ الملف l10n.yaml في جذر المشروع:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart استخدم [دليل التدويل الحالي في Flutter](https://docs.flutter.dev/ui/internationalization) للإعداد الخاص بكل إصدار من SDK. في سير العمل الحديث، توضع ملفات التوطين المُولَّدة ضمن شجرة المصدر الخاصة بالتطبيق. يستورد المثال من lib/l10n ، فتجنّب نسخ استيراد package:flutter_gen الاصطناعي القديم إلى إعداد جديد. راجع [ملاحظة الترحيل الخاصة بالمصدر المُولَّد](https://docs.flutter.dev/release/breaking-changes/flutter-generate-i10n-source).

## اكتب ملفات ARB مع السياق والعناصر النائبة محدّدة النوع

ملف ARB هو حزمة موارد قائمة على JSON تحتوي على رسائل وبيانات وصفية اختيارية. حافظ على ثبات مفاتيح الرسائل، واكتب رسائل كاملة، واستخدم البيانات الوصفية لتوضيح كيفية استخدام النص.

أنشئ الملف lib/l10n/app_en.arb :

{
"@@locale": "en",
"appTitle": "Reading room",
"@appTitle": {
"description": "Title of the sample reading application"
},
"welcomeName": "Welcome, {name}",
"@welcomeName": {
"description": "Greeting on the home screen",
"placeholders": {
"name": {"type": "String", "example": "Sam"}
}
},
"savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
"@savedBooks": {
"description": "Number of books saved to the user's library",
"placeholders": {
"count": {"type": "int"}
}
},
"readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
"@readingState": {
"description": "Reading status; state is active, paused or another value",
"placeholders": {
"state": {"type": "String"}
}
}
} أنشئ الملف lib/l10n/app_es.arb :

{
"@@locale": "es",
"appTitle": "Sala de lectura",
"welcomeName": "Te damos la bienvenida, {name}",
"savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
"readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
} يحتوي القالب على البيانات الوصفية للعناصر النائبة التي يستخدمها المولّد. ويحافظ الملف المُوطَّن على مفاتيح الرسائل وأسماء العناصر النائبة ومعرّفات select مع تغيير الصياغة الموجّهة للمستخدم. توضّح هذه الأمثلة الإسبانية الآلية فقط، أما لغة الإنتاج فينبغي أن تخضع لمراجعة الناطقين بها في سياق المنتج الفعلي.

شغّل flutter gen-l10n بعد إضافة الموارد أو تغييرها. وتعامل مع أخطاء المولّد على أنها مشكلات حقيقية في الموارد يجب حلّها قبل دمج الملفات في أي إصدار.

## اربط الرسائل المُولَّدة بـ MaterialApp

سجّل المفوّضين المُولَّدين واللغات المدعومة، ثم اقرأ الرسائل المُوطَّنة من سياق يقع أسفل عنصر واجهة التطبيق.

يوضع المثال التالي في lib/main.dart بعد التوليد:

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

class ReadingApp extends StatelessWidget {
const ReadingApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,
home: const ReadingHome(),
);
}
}

class ReadingHome extends StatelessWidget {
const ReadingHome({super.key});

@override
Widget build(BuildContext context) {
final messages = AppLocalizations.of(context)!;
return Scaffold(
appBar: AppBar(title: Text(messages.appTitle)),
body: Padding(
padding: const EdgeInsetsDirectional.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(messages.welcomeName('Sam')),
Text(messages.savedBooks(3)),
Text(messages.readingState('active')),
],
),
),
);
}
} ReadingHome يمكنه الوصول إلى الترجمات التي يوفّرها MaterialApp . أمّا طلب AppLocalizations من سياق عنصر الواجهة الخارجي فسيبحث فوق المزوّد الذي أنشأه ذلك العنصر. وتشرح [وثائق Localizations API](https://api.flutter.dev/flutter/widgets/Localizations-class.html) كيف تُتاح الموارد المُوطَّنة للعناصر الفرعية. تُظهر الواجهة البرمجية المُولَّدة في الشيفرة الفرق بين الرسالة البسيطة والرسالة ذات الوسائط. يُستدعى appTitle كقيمة، بينما تستقبل welcomeName و savedBooks و readingState القيم اللازمة لبناء رسائلها.

## تعامل مع رسائل الجمع والاختيار بعناية

تختار رسائل الجمع الصياغة وفقًا للكمية وقواعد اللغة المستهدفة. وتختار رسائل الاختيار فرعًا بناءً على معرّف يوفّره التطبيق. حافظ على البنية والمعرّفات أثناء ترجمة النص الذي يعرضه كل فرع.

صيغ الجمع

في المثال، يوفّر =0 جملة صريحة للحالة الفارغة. ويغطّي الفرعان one و other الصيغ المستخدمة في لغات المثال، لكنهما ليسا قالبًا عامًا لكل لغة مستهدفة. امنح المراجع سياقًا كافيًا ليقدّم الصيغ التي تتطلّبها اللغة والقيم التي قد يُنتجها تطبيقك.

رسائل الاختيار

القيم مثل active و paused معرّفات برمجية. وترجمتها ستفصل المورد عن الشيفرة التي توفّرها. ويمنح الفرع other الرسالة بديلًا احتياطيًا لأي قيمة لا تطابق فرعًا مسمّى.

رسائل كاملة

تجنّب ربط أجزاء متفرّقة مثل فعل مترجم وعدد واسم مترجم. فالرسالة الكاملة تمنح اللغة المستهدفة التحكّم في ترتيب الكلمات. ووضّح في التكليف القيم والنطاقات المتوقّعة وسياق الشاشة ليقيّم المراجعون الجملة كما سيراها المستخدمون.

## مقارنة حزم توطين Flutter

اختر الحزمة وفقًا لتنسيق الموارد وبنية التطبيق واحتياجات الصيانة. توفّر الحزم أدناه أعرافًا مختلفة، واعتماد أكثر من مولّد للرسائل نفسها يخلق التباسًا لا داعي له.

| | الأسلوب | الموارد المعتادة | توليد الشيفرة | أسلوب الجمع | مفيد عندما

| gen-l10n المدمج | ARB | يولّد دوال وصول Dart محدّدة النوع | بنية رسائل بأسلوب ICU | تريد سير عمل الموارد الرسمي في Flutter

| easy_localization | JSON افتراضيًا، مع توفّر أدوات تحميل إضافية | أدوات توليد اختيارية | واجهات الجمع البرمجية في الحزمة وقواعد مراعية للغة | تفضّل أعرافها في تحميل الأصول وإدارة اللغات

| ترجمات GetX | خرائط مفهرسة حسب اللغة في سير العمل الأساسي الموثّق | غير مطلوب لواجهة الخرائط الأساسية | تستخدم trPlural مفاتيح المفرد والجمع، لذا قيّم القواعد النحوية الأغنى بشكل منفصل | يستخدم تطبيقك GetX بالفعل ونموذج الترجمة فيه يلبّي المتطلّبات

راجع [وثائق easy_localization](https://pub.dev/packages/easy_localization) و[وثائق GetX](https://pub.dev/packages/get) الحالية قبل الاختيار. واختبر السلوك الاحتياطي والمعاملات وفئات الجمع وسير عمل الاستخراج باستخدام رسائلك الفعلية. فوجود واجهة برمجية مريحة للنصوص الإنجليزية لا يثبت التغطية لكل لغة تخطّط لإطلاقها.

ليست intl منصة منافسة لإدارة الترجمة، بل توفّر أدوات تدويل تستخدمها مسارات التوطين. ويولّد gen-l10n دوال الوصول للتطبيق من موارد ARB. كما تولّد [حزمة intl_utils](https://pub.dev/packages/intl_utils) المنفصلة شيفرة التوطين، لكن صفحتها كانت مُعلَّمة بأنها متوقّفة عند التحقّق منها في 30 أكتوبر 2026. تحقّق من حالة الصيانة قبل اعتمادها في مشروع جديد.

## اختبر تبديل اللغة والكتابة من اليمين إلى اليسار وتمدّد النص

اختبر صحة الموارد وسلوك النص المترجم في الواجهة معًا. فنجاح تحليل JSON أو خطوة توليد الشيفرة لا يثبت أن الشاشة مفهومة وقابلة للاستخدام.

تبديل اللغة

لإجراء فحص تطويري مركّز، اضبط MaterialApp.locale على قيمة مدعومة مثل const Locale('es') . أمّا في أداة اختيار اللغة للإنتاج، فاحتفظ باللغة المختارة في حالة التطبيق، واحفظ التفضيل وفقًا لمتطلّبات منتجك، ووفّر خيارًا لاتّباع لغة النظام. وتحقّق من التفضيل المحفوظ مقابل اللغات التي يدعمها إصدار التطبيق الحالي فعليًا.

التخطيطات من اليمين إلى اليسار

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

تمدّد النص

اختبر الترجمات الطويلة وأحجام النصوص الكبيرة. وافحص الأزرار وعلامات التبويب ومربعات الحوار والحالات الفارغة ورسائل الخطأ والتخطيطات الضيّقة. وأدرج قيمًا ديناميكية مثل الأسماء الطويلة والأعداد للتحقّق من التخطيط بالرسالة التي سيتلقّاها المستخدمون فعليًا.

استخدم مصفوفة اختبار عملية:

| | الفحص | مثال

| تغطية الموارد | لكل مفتاح مطلوب في القالب قيمة مُوطَّنة مقصودة أو قيمة احتياطية

| وسائط الرسائل | تظلّ أسماء العناصر النائبة وأنواعها متوافقة مع الدوال المُولَّدة

| سلوك الكميات | الصفر والواحد وقيم تختبر الصيغ الإضافية في اللغة المستهدفة

| سلوك الاختيار | الحالات المعروفة بالإضافة إلى قيمة غير متوقّعة تصل إلى other

| سلوك اللغة | لغة النظام والاختيار الصريح وإعادة التشغيل والتفضيل غير المدعوم

| التخطيط | النص المتمدّد وإعدادات الخط الكبير والمحتوى من اليمين إلى اليسار

| المعنى | مراجعة الناطقين باللغة الأم لرحلات المستخدم المهمة

للجانب اللغوي من العملية، استخدم [سير عمل اختبار التوطين](https://www.smartcat.com/software-localization/testing/). واجعل الاعتماد اللغوي ونتائج الاختبار الوظيفي ظاهرين كدليلين منفصلين على جاهزية الإصدار.

## خطّط لتوطين Flutter للويب وقابلية اكتشافه بشكل منفصل

يمكن لـ Flutter للويب استخدام موارد التطبيق المُوطَّنة، لكن توطين الواجهة لا يُنشئ تلقائيًا موقعًا متعدّد اللغات جاهزًا لـ SEO. فاختيار اللغة والتوجيه والبيانات الوصفية وقابلية اكتشاف المحتوى تظلّ قرارات معمارية.

تصف [الأسئلة الشائعة حول الويب](https://docs.flutter.dev/platform-integration/web/faq) في Flutter تركيزه على تجارب التطبيقات، وتوصي بنهج قائم على المستندات لمحتوى الويب الثابت الغني بالنصوص. فكّر في صفحات تسويقية وصفحات مساعدة وصفحات تحريرية منفصلة قائمة على HTML عندما تحتاج هذه الصفحات إلى الأداء الجيد في البحث العضوي.

حافظ على اتّساق المصطلحات بين التطبيق وتلك الصفحات العامة. فينبغي أن يتعرّف الزائر القادم من البحث على اسم الميزة بعد انتقاله من صفحة الهبوط المُوطَّنة إلى التطبيق، حتى لو استخدم السطحان نظامَي عرض مختلفين.

## تحقّق من سير عمل ترجمة ARB قبل توسيعه

تعامل مع ARB على أنه مورد تطبيق منظّم، لا مجرد ملف من القيم النصية. يجب أن يحافظ تسليم الترجمة على المفاتيح والبيانات الوصفية والعناصر النائبة وبنية الرسائل، ثم يعيد ملفات تجتاز التوليد واختبارات التطبيق.

تشمل تنسيقات مشاريع البرمجيات الموثّقة في Smartcat استيراد JSON وYAML وAndroid XML وiOS .strings وLocJSON. ولا تُثبت الوثائق التي رُوجعت لإعداد هذا الدليل دعمًا أصليًا لـ ARB أو سير عمل مختبَرًا للتحويل من ARB إلى JSON. فلا تفترض أن تغيير امتداد الملف يثبت التوافق. راجع [وثائق مشاريع البرمجيات](https://help.smartcat.com/create-a-software-localization-project/).

استخدم ما يلي كإجراء تحقّق مقترح مع فريق التنفيذ لديك، لا كوصفة موصّل مختبَرة مسبقًا:

- اختر عيّنة ممثِّلة

اختر عيّنة ARB صغيرة تحتوي على نصوص بسيطة وبيانات وصفية وعناصر نائبة محدّدة النوع ورسائل جمع واختيار.

- أكّد الاستيراد والتصدير

أكّد مع فريق المنتج طريقة الاستيراد والتصدير المدعومة، بما في ذلك التعامل مع البيانات الوصفية @ ورسائل ICU.

- وفّر الأصول اللغوية والسياق

وفّر مسردًا وذاكرة ترجمة عند الحاجة وسياقًا واضحًا لكل رسالة.

- ترجِم واحمِ البنية

ترجِم النص الموجّه للمستخدم وراجعه مع حماية المعرّفات البرمجية والبنية.

- قارِن واستعِد

قارِن الموارد المُعادة بعقد المصدر وأعِدها إلى مسارات المشروع المتوقّعة.

- ولّد واختبر

شغّل flutter gen-l10n والتحليل الثابت والاختبارات ذات الصلة في بيئة SDK المثبّتة للمشروع.

- راجِع وسجّل

راجِع الواجهة المُوطَّنة وسجّل إصدار المصدر المعتمد.

لا تؤتمت مزامنة المستودع إلا بعد نجاح هذه الدورة الكاملة. وحدّد من يتولّى تغييرات المصدر، وكيف تُلغى حالة المراجعة، وكيف تُدار الملفات المُولَّدة. واحتفظ بموارد ARB تحت نظام التحكّم في الإصدارات بوصفها المصدر المرجعي لسير عمل التطبيق.

راجِع سير عمل ترجمة Flutter لديك

- [احجز عرضًا توضيحيًا](https://www.smartcat.com/book-a-demo/?main-cta1-flutter-localization)

## الأعطال الشائعة وما يجب فحصه أولًا

| | العَرَض | الفحص الأول

| تعذّر العثور على الاستيراد المُولَّد | نجاح عملية التوليد ومطابقة الاستيراد لمسار مخرجات المصدر المُعدّ

| AppLocalizations.of(context) غير متاح | وقوع السياق أسفل مزوّد التوطين الخاص بالتطبيق

| دالة رسالة تحتوي على وسائط غير متوقّعة | البيانات الوصفية للعناصر النائبة في القالب والواجهة البرمجية المُولَّدة

| رسالة اختيار تعرض دائمًا القيمة الاحتياطية | تطابق معرّف التطبيق مع فرع المورد تمامًا

| لغة مفقودة | ملفات الموارد واللغات المدعومة وإعدادات تحديد اللغة

| تعطّل الترجمة بعد التصدير | سلامة المفاتيح وصحة JSON والبيانات الوصفية وبنية ICU بعد الدورة الكاملة

أصلِح أول عقد معطّل بدلًا من تعديل شيفرة Dart المُولَّدة يدويًا. فالشيفرة المُولَّدة يمكن إعادة توليدها، وأي إصلاح يدوي فيها سيختفي على الأرجح عند تغيّر الموارد في المرة التالية.

## الأسئلة الشائعة

### ما ملف ARB في Flutter؟

حزمة موارد التطبيق ملف قائم على JSON يحتوي على رسائل مُوطَّنة وبيانات وصفية اختيارية. ويستخدم سير عمل gen-l10n في Flutter موارد ARB لتوليد واجهة توطين برمجية بلغة Dart. ويمكن للبيانات الوصفية وصف الرسالة وعناصرها النائبة، ما يمنح المطوّرين والمترجمين عقدًا أوضح لكل مفتاح.

### ما الفرق بين gen-l10n وintl_utils؟

كلاهما يولّد شيفرة التوطين من موارد ARB، لكنهما أداتان منفصلتان بأعراف إعداد ومخرجات مختلفة. فـ gen-l10n جزء من سير العمل المدمج في Flutter، أما صفحة حزمة intl_utils فكانت مُعلَّمة بأنها متوقّفة عند التحقّق منها لإعداد هذا الدليل، لذا تحقّق من حالة صيانتها قبل اختيارها لتنفيذ جديد.

### كيف أترجم ملفات ARB؟

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

### هل يدعم Smartcat العناصر النائبة وصيغ الجمع في ARB؟

لا تُثبت وثائق مشاريع البرمجيات التي رُوجعت هنا دعمًا أصليًا لـ ARB أو مسار تحويل مختبَرًا يحافظ على جميع ميزات ARB. أكّد طريقة الاستيراد والتصدير مع فريق المنتج، وتحقّق من دورة كاملة ممثِّلة قبل الاعتماد. فدعم JSON العام وحده لا يثبت التوافق مع ARB.

### هل يعمل توطين Flutter على الويب؟

يمكن لتطبيقات Flutter للويب استخدام الموارد المُوطَّنة واختيار اللغة. أمّا قابلية الاكتشاف في البحث فمسألة منفصلة، إذ قد يستفيد المحتوى التسويقي ومحتوى المساعدة العام من بنية قائمة على HTML. اختبر التوجيه واختيار اللغة والبيانات الوصفية لتجربة الويب الخاصة بك بدلًا من افتراض أن إعداد توطين تطبيق الجوال يكفي لـ SEO على الويب.

لم تجد إجابتك؟ [تحدّث إلى متخصّص في التوطين](https://www.smartcat.com/book-a-demo/?main-cta4-flutter-localization)

اجعل تسليم الترجمة موثوقًا بقدر موثوقية عقد مواردك

أحضِر عيّنة ARB صغيرة والفحوصات التي يتطلّبها إصدارك. وراجع سير العمل قبل توسيعه ليشمل كل لغة وكل إصدار.

- [احجز عرضًا توضيحيًا](https://www.smartcat.com/book-a-demo/?main-cta5-flutter-localization)

- [استكشف توطين تطبيقات الجوال](https://www.smartcat.com/software-localization/mobile-apps/)