إعدادات الترجمة في كوكب Kawkab
الترجمة هي ميزة أساسية في كوكب Kawkab تتيح لك إدارة واستخدام الترجمات للغات متعددة داخل تطبيقك. تهدف هذه الميزة إلى تسهيل دعم اللغات المتعددة وضمان تقديم تجربة مستخدم مخصصة للغات وثقافات متنوعة.
كيفية إنشاء ملفات الترجمة
لإنشاء ملفات الترجمة داخل تطبيقك باستخدام كوكب Kawkab، يمكنك استخدام الأمر التالي لإنشاء ملف ترجمة جديد باللغة التي تحتاج إليها:
npm run kawkab trans:make <language> [type] [module]تفاصيل المعاملات:
<language>: رمز اللغة التي تريد إنشاء الترجمة لها (مثلًاarللغة العربية).[type]: نوع الملف الذي ترغب في استخدامه (اختياري:tsأوjson، وإذا لم يتم تحديده سيتم استخدامts).[module]: اسم الموديل الذي يحتوي على الترجمة (اختياري، الافتراضي هوmain).
مثال على إنشاء ملف ترجمة:
لنفترض أنك تريد إنشاء ملف ترجمة باللغة العربية في الموديل main. يمكنك تشغيل الأمر التالي:
npm run kawkab trans:make arنتيجة التنفيذ:
- سيتم إنشاء ملف
ar.jsonفي المجلد المخصص للترجمات داخل الموديل، وستكون البنية الأساسية للملف كما يلي:
{
"hello_world": "Hello World!"
}استخدام الترجمة في تطبيقك
بعد إنشاء ملفات الترجمة، يمكنك استيراد الوظائف الخاصة بها واستخدامها في تطبيقك بسهولة. على سبيل المثال:
import { __, t, trans } from "kawkab";الاستفادة من الترجمات:
باستخدام trans.get:
يمكنك استرجاع الترجمة من خلال مفتاح النص الذي ترغب في ترجمته.
trans.get("hello_world", {}, "default value");باستخدام __:
هذه الوظيفة توفر طريقة مختصرة لاسترجاع النصوص المترجمة.
__("hello_world", {}, "default value");باستخدام t:
تعمل بنفس طريقة __.
t("hello_world", {}, "default value");تخصيص اللغة المستخدمة
تحديد اللغة:
يمكنك تغيير اللغة الافتراضية لتطبيقك عن طريق تحديث الإعدادات في ملف app/configuration.ts:
export const app = {
locale: {
default: env.string("LOCALE_CODE", "en"), // اللغة الافتراضية
detect: true, // استكشاف اللغة تلقائيًا
},
};- default:
يُستخدم لاختيار اللغة الافتراضية للتطبيق. في المثال أعلاه، اللغة الافتراضية هي الإنجليزية.
- detect:
يُستخدم لاستكشاف اللغة بشكل تلقائي بناءً على الهيدر Accept-Language من الطلب.
استكشاف لغة المستخدم تلقائيًا
عند تفعيل خيار detect: true في إعدادات التطبيق، يقوم Kawkab تلقائيًا باستكشاف لغة المستخدم بناءً على الهيدر Accept-Language. مثال:
- إذا كان الهيدر يحتوي على:
Accept-Language: ar,en;q=0.9 - سيقوم التطبيق باستخدام اللغة العربية (
ar) إذا كانت مدعومة.
تغيير اللغة أثناء التشغيل:
يمكنك تحديث اللغة المستخدمة أثناء تشغيل التطبيق باستخدام:
trans.setLocale("ar"); // لتحديد اللغة العربية كلغة نشطةميزات إضافية في الترجمة
الاستبدال والمتغيرات:
يمكنك استخدام المتغيرات داخل النصوص لتخصيص الترجمات بشكل ديناميكي. على سبيل المثال:
في ملف الترجمة trans/en.ts:
export default {
hello: "Hello :name!",
};استخدام الترجمة مع استبدال المتغير:
__("hello", { name: "Hassan" });النتيجة:
Hello Hassan!استخدام قيمة احتياطية:
إذا لم يتم العثور على ترجمة لأي مفتاح، يمكنك تحديد قيمة احتياطية تُعرض في حال عدم العثور على الترجمة:
__("hello", { name: "Hassan" }, "Hello there!");النتيجة إذا لم يوجد المفتاح hello:
Hello there!تحديد اللغة عند استرجاع الترجمة:
يمكنك تحديد اللغة عند استرجاع النص المترجم:
__("hello", { name: "Hassan" }, "Hello there!", "ar");إدارة الترجمات
عرض جميع الترجمات:
يمكنك استرجاع جميع الترجمات لجميع اللغات:
trans.all();استرجاع الترجمات للغة معينة:
لاسترجاع الترجمات الخاصة بلغة معينة مثل العربية:
trans.all("ar");أفكار لتطوير الترجمات
-
تسمية مفاتيح واضحة:
- اختر مفاتيح تعبر عن المحتوى لضمان سهولة الفهم والإدارة.
-
تنظيم الملفات:
- احتفظ بالترجمات في مجلدات منفصلة لكل موديل ولغة.
-
استخدام القيم الافتراضية:
- قم دائمًا بتوفير قيم افتراضية لضمان عمل التطبيق حتى في حالة نقص الترجمات.
خاتمة
توفر كوكب Kawkab نظامًا قويًا ومرنًا لإدارة الترجمات ودعم اللغات المتعددة. باستخدام هذه الإعدادات والوظائف، يمكنك تحسين تجربة المستخدم وتقديم تطبيقات تدعم مجموعة متنوعة من الثقافات واللغات بسهولة وفعالية.