الانتقال إلى المحتوى الرئيسي

نظرة عامة

تُكتب تطبيقات Twenty باللغة الإنجليزية: السلاسل في مصدرك وملف البيان هي نص المصدر الإنجليزي، وen هو الإعداد المحلي الذي تترجم منه، وأي إعداد محلي يُترك دون ترجمة يعود إليه افتراضيًا. يحتوي تطبيقك على نوعين من النصوص القابلة للترجمة، وكلاهما يمر عبر نفس كتالوج locales/:
  • تسميات ملف البيان — أسماء الكائنات والحقول، وعناوين العروض، وعناصر القوائم، وسلاسل أخرى مُعلَنة في بيانات التعريف لتطبيقك.
  • سلاسل الواجهة الأمامية (front-component) — نص واجهة المستخدم الذي تقوم مكوّنات React الأمامية لديك بعرضه.
تضع علامات على السلاسل القابلة للترجمة، وتستخرجها إلى كتالوجات لكل إعداد محلي، ثم تترجم هذه الكتالوجات، وتتولّى عملية البناء تقديم اللغة الصحيحة للمستخدم الحالي — دون أي إعداد إضافي.

وضع علامات على سلاسل الواجهة الأمامية (front-component)

قم باستيراد أدوات الترجمة من twenty-sdk/front-component:

متى تستخدم أيًّا منها

  • Trans — نص ثابت في JSX. استخدم الخاصيتين message وvalues من أجل الاستبدال (interpolation)، كما في Trans message="Hi {name}" values={{ name }}؛ لا يمكن استخراج الاستبدال مباشرة في العناصر الفرعية (children) بشكل ثابت.
  • useTranslate().t — سلاسل ديناميكية داخل المكوّن. يُعيد التصيير عندما يغيّر المستخدم اللغة. يفضّل استخدامه داخل التصيير (render).
  • t(...) (مستوردة مباشرة) — ترجمة فورية (eager) يمكن استخدامها في أي مكان، بما في ذلك معالجات الأحداث (event handlers)، والبرامج المساعدة (helpers)، ونطاق الوحدة (module scope) — وليس فقط داخل التصيير.
  • msg(...) — واصف مؤجَّل للسلاسل المُعلَنة كبيانات (ثوابت، التهيئة (config)). قم بحلّه لاحقًا باستخدام t(descriptor).

السياق

مرِّر context لتمييز سلاسل المصدر المتطابقة التي تُترجَم بشكل مختلف:
تظهر السلاسل السياقية في كتالوجات اللغة المحلية كمجموعة مفهرسة حسب سياقها: "\<context>": { "\<message>": "\<translation>" }. تكون تسميات الـ Manifest سياقية بطبيعتها — إذ تحمل كل تسمية دورها في البيانات الوصفية (objectMetadata.labelSingular، fieldMetadata.label، view.name، …)، لذلك يمكن أن تُترجَم الكلمة نفسها بشكل مختلف عندما تكون اسم كائن وعندما تكون اسم عرض.

الاستخراج والترجمة

شغِّل أمر الاستخراج من دليل تطبيقك:
يقوم الاستخراج بجمع كل من تسميات ملف البيان (manifest labels) وسلاسل t()/msg()/Trans من شفرة الواجهة الأمامية (front-component) في locales/\<locale>.json، مفهرسة حسب سلسلة المصدر. املأ الترجمات:
السلاسل غير المرتبطة بسياق هي مدخلات مسطَّحة؛ أما السلاسل المرتبطة بسياق — بما في ذلك كل تسمية في ملف manifest — فهي متداخلة تحت مفتاح السياق الخاص بها. العناصر النائبة مثل {name} تُستبدَل وقت التشغيل — احتفظ بها في الترجمة. أي سلسلة تُترَك فارغة تعود إلى نص المصدر.

كيفية التشغيل

يقوم twenty app build بتجميع الكتالوجات وتقديم اللغة المناسبة للمستخدم الحالي: تُحل تسميات ملف البيان على جانب الخادم، وتُضمَّن كتالوجات المكوّنات الأمامية في كل حزمة مكوّن. وقت التشغيل يقرأ المكوّن اللغة (locale) من سياق التنفيذ الخاص به (لغة المضيف الحالية) ويحل كل سلسلة مقابل كتالوجه، مع الرجوع إلى المصدر عندما تكون الترجمة مفقودة. تغيير اللغة في المضيف يعيد تصيير سلاسل Trans و useTranslate().t مباشرة. تُجمَّع تسميات ملف البيان عند كل مزامنة — سواء عبر twenty app build أو twenty app apply أو المراقبة المستمرة لـ twenty app dev — لذا يكفي تعديل ملف إعداد محلي ومزامنته لرؤية النص الجديد. تُضمَّن كتالوجات المكوّنات الأمامية في كل حزمة مكوّن أثناء الإنشاء، لذا فإن تغيير أحدها لا يزال يعني إعادة تشغيل twenty app build (وإعادة النشر).

سحب الترجمات

يكتب twenty app pull الترجمات المنشورة للتطبيق مرة أخرى في locales/. يُفهرس الكتالوج المنشور حسب معرّف الرسالة، لذا يستعيد السحب الصيغة المقروءة فقط للسلاسل التي يمكنه رؤية مصدرها: تسميات البيانات الوصفية التي سحبها وسلاسل t()/msg()/Trans لمكونات الواجهة الأمامية الموجودة في المشروع. يُحتفظ بكل شيء آخر كما هو في locales/compiled/\<locale>.json، مفهرسًا حسب معرّف الرسالة. تدمج عملية البناء تلك الملفات في الكتالوج (يكون لإدخال في locales/\<locale>.json الأولوية على إدخال مُجمّع له المعرّف نفسه)، ويترك twenty app translations extract هذه الملفات دون تغيير، وتعيد كل عملية سحب كتابتها، لذا يتقلص حجمها كلما أُضيف المزيد من مصدر التطبيق إلى الشجرة. لا تعدّلها يدويًا؛ ترجم في locales/\<locale>.json. لا يحدد مشروع لا يحتوي على مجلد locales/ أي شيء بشأن الترجمات، لذا فإن المزامنة منه تترك ما نشره التطبيق بالفعل دون تغيير. لإزالة الترجمات المنشورة عمدًا، احتفظ بالمجلد واحذف ملفات اللغة داخله: إن مجلد locales/ الذي لا يُجمَّع إلى أي لغة هو إعلان صريح، وتُقلِّم المزامنة وفقًا لذلك. قد تمتد عناصر النص التابعة لـ Trans على عدة أسطر — يتم ضغط المسافات بنفس الطريقة التي يقوم JSX بضغطها، لذلك كلاهما يتم استخلاصه إلى المفتاح Welcome back: