أفضل الممارسات

للوِب

مثال: لعلامة <h2/> مع مرساة

التسمية في اللغة الحالية

تُعد نماذج اللغات الكبيرة (LLM) أكثر فعالية من البشر في حماية الروابط، ويسمح لك LSDE باكتشاف المشاكل بين الإصدارات اللغوية المختلفة.
وبهذا، يمكنك مشاركة رابط سيعمل في جميع اللغات واستخدام LSDE لإدارة استبدال مرساة مهملة.

غموض الكود

تجنب الغموض عند العمل مع النماذج الموجهة بالبيانات.
مثال:
ممارسة سيئة: المصطلح 'key' ليس واضحًا ويجعل البحث عنه صعبًا.

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		key: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		key: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		key: 'software:lsge.name',
	},
];

ممارسة جيدة: اعتمد اصطلاحًا فريدًا ومتسقًا.
المصطلح i18nKey واضح جدًا ويسمح بالبحث الدقيق عن هذه القيمة عبر التعبيرات النمطية (Regex).

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		i18nKey: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		i18nKey: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		i18nKey: 'software:lsge.name',
	},
];

الكسل

الأفكار السيئة تنبع من الكسل.

لا تسعَ لتوفير المفاتيح عن طريق إجراء عمليات لاسترداد المحتوى.
مثال:

javascript
const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

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

تنسيق الوسوم

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

يمكن أن تتضمن الوسوم معرفًا (ID)، لكن إضافة معلومات إضافية لا يُنصح به بشدة عمومًا ويُعتبر ممارسة سيئة.
مثال: لا تفعل
<img src='url' left />
بل افعل
<img id=1 />
ستسترجع بعد ذلك معرف (ID) وسم الصورة لتطبيق الأنماط الضرورية عليها في قاعدة الكود.
يجب استخدام المعرفات (IDs) حرفيًا وليس عبر مؤشرها.
في الواقع، في لغات مختلفة، قد يتم نقل الوسوم ولم تعد تتوافق مع المؤشر الأولي.
كما أن استخدام الفهارس الطبيعية يُدخل تعقيدًا للمطور؛ محاولة تخمين أي مؤشر يتوافق مع الصورة أو الوسم هي صداع حقيقي.
لذا، استخدم الوسوم ذات المعرف عندما ترغب في تخصيصها بعد الاستيفاء.

CSS

لترجمة موقع، عندما يكون لديك فقرات، اختر ارتفاعًا أدنى (`min-height`) بعد الترجمة لتجنب التغييرات المرئية عند تبديل اللغات.
مثال: `mih={'3lh'}`
يتيح لك ذلك تحديد ارتفاع أدنى يعتمد على اللغة التي تشغل أكبر عدد من الأسطر، مما يضمن تجربة مستخدم (UX) متسقة ورصينة.

النطاق

هذا يسهل بشكل كبير إعداد نمط Regex للعثور على مفاتيحك.
مثال: game:a.b.c، common:a.b.c

إدارة إصدارات GIT

تعد مشاريع .lsde ملفات بتنسيق JSON، مما يسهل تتبع إصداراتها باستخدام أدوات مثل Git.
نوصي بشدة بحفظ مشروعك داخل مستودع Git للاستفادة من سجل كامل للأحداث وأمان معزز.
على الرغم من أن LSDE يتضمن نظام نسخ احتياطي خاص به، إلا أن استخدام Git يظل الحل الأمثل لإدارة ملفات البيانات الخاصة بك.

السياق والتحرير

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

أمثلة على مفاتيح صريحة:
game:.scenes.001.events.001.1
game:.scenes.001.events.001.2
game:.scenes.the-ice-land.events.the-lost-house.1
game:.scenes.the-ice-land.events.the-lost-house.2
game:.ui.menus.new-game.label
game:.ui.menus.new-game.description

تسمح هذه المفاتيح بفهم فوري بأنها تشير إلى حوارات أو عناصر واجهة.

أمثلة على ممارسات سيئة:
game:events.001.1 (غامض جداً: أين يُستخدم هذا الحدث؟)
game:.scenes-events-the-lost-house.1 (تكرار في المسار)
game:.ui-menus.new-game-label (دمج غير ضروري)

تجنب التكرار في المسارات. إذا كنت بحاجة إلى تسهيل البحث، فقم بتصدير ملف أنواع (Types) يحتوي على المفاتيح المدمجة بدلاً من إضعاف بنية بيانات JSON الخاصة بك.

يجب ألا تعتمد أي سلسلة نصية أبداً على عنصر خارجي لفهمها (الموقع على الشاشة، اللون، الأيقونة).
مثال: تجنب
"انقر هنا للمتابعة"
يفضل استخدام
"المتابعة إلى الدفع"
يجب أن يظل النص مفهوماً حتى لو تم استخراجه من واجهة المستخدم (UI).
قد لا تتوفر لبعض اللغات ترجمة ممكنة أو قد يكون لها صيغ مختلفة حسب الإجراء وموقع النص.

يجب أن تصف نصوص الإجراءات (Action texts) الإجراء والمفعول به: "الذهاب إلى الدفع"، "تحميل تقرير PDF" وليس "انقر هنا" أو "لمعرفة المزيد" دون تحديد.

لا تنقل مبادئ البرمجة (مثل S.O.L.I.D.) إلى تحرير محتوى i18n. التحرير والبرمجة تخصصان مختلفان.
يفضل استخدام جمل كاملة بدلاً من الشظايا، لأن كل لغة لها قواعدها الخاصة.
على الرغم من أن أطر العمل مثل `i18next` تدعم التداخل (« nesting »)، إلا أن ذلك غالباً ما يولد تعقيداً غير ضروري. إذا كان هناك اختلاف ضروري، أعد كتابة الجملة بالكامل. اقتصر في الاستكمال (interpolation) على المتغيرات البسيطة مثل الأسماء أو الأرقام.

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

لا تدرج أحرفاً خاصة أو رموزاً تعبيرية (emojis) مباشرة في نصوصك.
استخدم المتغيرات (مثال: <t title=) للتحكم في عرضها عبر الكود. يختلف مظهر الرموز التعبيرية بشكل كبير حسب نظام التشغيل وبيئة المستخدم.

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

اكتب كما لو كان المترجم لا يملك حق الوصول إلى الكود ولا إلى واجهة المستخدم (UI).
كل ما هو ضروري للفهم يجب أن يكون موجوداً في المفتاح، أو تسلسله الهرمي، أو بياناته الوصفية.

Technique I18n

فضّل الـ placeholders المُسماة (`{username}`، `{count}`) على الـ index positionnels (`{0}`، `{1}`). يوفر LSDE قسماً مخصصاً للـ variables لتحديد سياقها وضمان تتبعها (traçabilité) داخل مشروعك.

يجب أن يكون كل placeholder ذرياً (atomique) ويمثل معلومة فريدة (اسم، تاريخ، رقم). تجنب الـ variables العامة أو الـ polymorphes التي تُعقد عملية الترجمة والتفسير.

توقع العرض للغات التي تُكتب من اليمين إلى اليسار. يجب أن يظل الـ rendering انسيابياً وصحيحاً هيكلياً دون الحاجة إلى تعديلات يدوية على الـ chaîne de caractères.

لا تقم أبداً بتكوين جملة عبر دمج عدة clés de traduction. لاحترام الـ syntaxes والتوافقات النحوية الخاصة بكل لغة، يجب أن تقابل كل جملة كاملة clé unique واحدة.