Flutter ARB

ما هو Flutter ARB؟

Flutter ARB (Application Resource Bundle) هو تنسيق قائم على JSON يستخدمه إطار عمل Flutter من Google لإدارة النصوص المترجمة. يدعم البيانات الوصفية والعناصر النائبة وتنسيق رسائل ICU لبناء تطبيقات مترجمة أصلياً.

ما هو Lingo.dev CLI؟

Lingo.dev CLI هو واجهة سطر أوامر مجانية ومفتوحة المصدر لترجمة التطبيقات والمحتوى باستخدام الذكاء الاصطناعي. تم تصميمه ليحل محل برامج إدارة الترجمة التقليدية مع التكامل مع خطوط الأنابيب الحالية.

لمعرفة المزيد، راجع نظرة عامة.

حول هذا الدليل

يشرح هذا الدليل كيفية ترجمة ملفات Flutter ARB باستخدام Lingo.dev CLI.

ستتعلم كيفية:

• إنشاء مشروع من الصفر
• تكوين خط أنابيب الترجمة
• إنشاء ترجمات باستخدام الذكاء الاصطناعي

المتطلبات الأساسية

لاستخدام Lingo.dev CLI، تأكد من تثبيت Node.js الإصدار 18 أو أحدث:

❯ node -v
v22.17.0

الخطوة 1. إعداد المشروع

في دليل مشروعك، أنشئ ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يحدد هذا الملف سلوك خط أنابيب الترجمة، بما في ذلك اللغات المراد الترجمة بينها ومكان وجود المحتوى القابل للترجمة في نظام الملفات.

لمعرفة المزيد حول الخصائص المتاحة، راجع i18n.json.

الخطوة 2. تكوين اللغة المصدر

اللغة المصدر هي اللغة والمنطقة الأصلية التي تمت كتابة المحتوى بها. لتكوين اللغة المصدر، قم بتعيين خاصية locale.source في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يجب توفير اللغة المصدر كـ علامة لغة BCP 47.

للحصول على القائمة الكاملة لرموز اللغات التي يدعمها Lingo.dev CLI، راجع رموز اللغات المدعومة.

الخطوة 3. تكوين اللغات المستهدفة

اللغات المستهدفة هي اللغات والمناطق التي تريد ترجمة محتواك إليها. لتكوين اللغات المستهدفة، قم بتعيين خاصية locale.targets في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

الخطوة 4. إنشاء المحتوى المصدر

إذا لم تكن قد قمت بذلك بالفعل، قم بإنشاء ملف ARB واحد أو أكثر يحتوي على المحتوى المراد ترجمته. يجب أن تكون هذه الملفات موجودة في مسار يتضمن اللغة المصدر في مكان ما من المسار (على سبيل المثال، كاسم دليل مثل en/ أو كجزء من اسم الملف مثل messages.en.arb).

بالنسبة لملفات Flutter ARB، تنطبق المتطلبات التالية:

• يجب أن يكون لكل مفتاح رسالة قيمة ترجمة مقابلة
• يتم الحفاظ على إدخالات البيانات الوصفية (التي تبدأ بـ @) ولكن لا تتم ترجمتها
• يحدد حقل البيانات الوصفية @@locale اللغة
• يتم الحفاظ على العناصر النائبة ({name}) أثناء الترجمة
• يتم دعم تنسيق رسائل ICU للجمع والاختيار

على سبيل المثال:

{
  "@@locale": "en",
  "welcome_message": "Welcome to our Flutter app",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen"
  },
  "login_button": "Log In",
  "greeting_with_name": "Hello {name}!",
  "@greeting_with_name": {
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}

الخطوة 5. إنشاء حاوية

1. في ملف i18n.json، أضف كائن "flutter" إلى كائن buckets:

   {
     "$schema": "https://lingo.dev/schema/i18n.json",
     "version": "1.10",
     "locale": {
       "source": "en",
       "targets": ["es"]
     },
     "buckets": {
       "flutter": {}
     }
   }
   

2. في كائن "flutter"، حدد مصفوفة من نمط include واحد أو أكثر:

   {
     "$schema": "https://lingo.dev/schema/i18n.json",
     "version": "1.10",
     "locale": {
       "source": "en",
       "targets": ["es"]
     },
     "buckets": {
       "flutter": {
         "include": ["./[locale]/example.arb"]
       }
     }
   }
   

   تحدد هذه الأنماط الملفات المراد ترجمتها.

   الأنماط نفسها:

   • يجب أن تحتوي على [locale] كعنصر نائب للغة المكونة
   • يمكن أن تشير إلى مسارات الملفات (على سبيل المثال، "[locale]/config.arb")
   • يمكن استخدام النجوم كعناصر نائبة بدل (على سبيل المثال، "[locale]/*.arb")

   أنماط glob العودية (على سبيل المثال، **/*.arb) غير مدعومة.

الخطوة 6. تكوين نموذج لغوي كبير

يستخدم Lingo.dev CLI نماذج لغوية كبيرة (LLMs) لترجمة المحتوى بالذكاء الاصطناعي. لاستخدام أحد هذه النماذج، تحتاج إلى مفتاح API من مزود مدعوم.

للبدء والتشغيل بأسرع وقت ممكن، نوصي باستخدام Lingo.dev Engine — منصتنا المستضافة الخاصة التي توفر 10,000 رمز مميز من الاستخدام المجاني الشهري:

1. قم بالتسجيل للحصول على حساب Lingo.dev.

2. قم بتشغيل الأمر التالي:

   npx lingo.dev@latest login
   

   سيؤدي هذا إلى فتح متصفحك الافتراضي ومطالبتك بالمصادقة.

3. اتبع التعليمات.

الخطوة 7. إنشاء الترجمات

في الدليل الذي يحتوي على ملف i18n.json، قم بتشغيل الأمر التالي:

npx lingo.dev@latest run

يقوم هذا الأمر بـ:

1. قراءة ملف i18n.json.
2. العثور على الملفات التي تحتاج إلى ترجمة.
3. استخراج المحتوى القابل للترجمة من الملفات.
4. استخدام نموذج اللغة الكبير المُكوَّن لترجمة المحتوى المستخرج.
5. كتابة المحتوى المترجم مرة أخرى إلى نظام الملفات.

في المرة الأولى التي يتم فيها إنشاء الترجمات، يتم إنشاء ملف i18n.lock. يتتبع هذا الملف المحتوى الذي تمت ترجمته، مما يمنع إعادة الترجمة غير الضرورية في عمليات التشغيل اللاحقة.

مثال

en/example.arb

{
  "@@locale": "en",
  "welcome_message": "Welcome to our Flutter app",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen",
    "context": "greeting"
  },
  "login_button": "Log In",
  "signup_button": "Sign Up",
  "greeting_with_name": "Hello {name}!",
  "@greeting_with_name": {
    "description": "Greeting message with user's name",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "The user's display name"
      }
    }
  },
  "item_count": "{count, plural, =0 {No items} one {# item} other {# items}}",
  "@item_count": {
    "description": "Message showing the number of items with proper pluralization",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "The number of items"
      }
    }
  }
}

es/example.arb

{
  "@@locale": "es",
  "welcome_message": "Bienvenido a nuestra aplicación Flutter",
  "@welcome_message": {
    "description": "The main welcome message shown on the home screen",
    "context": "greeting"
  },
  "login_button": "Iniciar sesión",
  "signup_button": "Registrarse",
  "greeting_with_name": "¡Hola {name}!",
  "@greeting_with_name": {
    "description": "Greeting message with user's name",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "The user's display name"
      }
    }
  },
  "item_count": "{count, plural, =0 {Sin elementos} one {# elemento} other {# elementos}}",
  "@item_count": {
    "description": "Message showing the number of items with proper pluralization",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "The number of items"
      }
    }
  }
}

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "flutter": {
      "include": ["./[locale]/example.arb"]
    }
  }
}

i18n.lock

version: 1
checksums:
  88559ecadc7cff52625bd3a47e51dd78:
    welcome_message: 9c56d00796c3c7facba6a25275de5b7b
    login_button: 0029e5a35676c0051e761fcd046ef9ee
    signup_button: 0dd2ae69be4618c1f9e615774a4509ca
    error_network: e0becd5fc88e85a97c6987b96c80fb11
    success_message: e6dcd73052dc41dbe05d86af9887d2c4
    user_profile_title: bee775ff7216747b2111e93cefa57ddc
    settings_screen_title: 8df6777277469c1fd88cc18dde2f1cc3
    cancel_action: 2e2a849c2223911717de8caa2c71bade
    confirm_action: 90930b51154032f119fa75c1bd422d8b
    greeting_with_name: 218521f06746e82ba44d68c8a5bb210c
    item_count: d8d083b56bc155cf0997ea6ae989b83f
    user_status: 903b5a6edde5368dd9089accdc1b1f9d