github-actions[bot]
128abcc433
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
111 lines
6.3 KiB
Plaintext
111 lines
6.3 KiB
Plaintext
---
|
|
title: الترجمات
|
|
description: قدّم تطبيقك بعدة لغات — ترجم تسميات ملف البيان وسلاسل واجهة المستخدم عبر كتالوج إعدادات محلية واحد.
|
|
icon: language
|
|
---
|
|
|
|
تُكتب تطبيقات Twenty باللغة **الإنجليزية**: السلاسل في شفرتك وملف البيان هي نص المصدر بالإنجليزية، و`en` هي الإعداد المحلي الذي تترجم منه، وأي إعداد محلي يُترك دون ترجمة يعود إليه افتراضيًا.
|
|
|
|
يحتوي تطبيقك على نوعين من النصوص القابلة للترجمة، وكلاهما يمر عبر نفس
|
|
كتالوج `locales/`:
|
|
|
|
* **تسميات ملف البيان** — أسماء الكائنات والحقول، وعناوين العروض، وعناصر القوائم، وسلاسل أخرى مُعلَنة في بيانات التعريف لتطبيقك.
|
|
* **سلاسل الواجهة الأمامية (front-component)** — نص واجهة المستخدم الذي تقوم مكوّنات React الأمامية لديك بعرضه.
|
|
|
|
تضع علامات على السلاسل القابلة للترجمة، وتستخرجها إلى كتالوجات لكل إعداد محلي، ثم تترجم هذه الكتالوجات، وتتولّى عملية البناء تقديم اللغة الصحيحة للمستخدم الحالي — دون أي إعداد إضافي.
|
|
|
|
## وضع علامات على سلاسل الواجهة الأمامية (front-component)
|
|
|
|
قم باستيراد أدوات الترجمة من `twenty-sdk/front-component`:
|
|
|
|
```tsx
|
|
import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';
|
|
|
|
const STATUSES = [
|
|
{ id: 'draft', label: msg('Draft') },
|
|
{ id: 'sent', label: msg('Sent') },
|
|
];
|
|
|
|
const Card = ({ count, name }: { count: number; name: string }) => {
|
|
const { t } = useTranslate();
|
|
|
|
return (
|
|
<section>
|
|
{/* Static text — reactive to the user's locale */}
|
|
<Trans>Loading postcard…</Trans>
|
|
|
|
{/* Disambiguate identical sources with a context */}
|
|
<Trans context="card-title">Untitled</Trans>
|
|
|
|
{/* Interpolation: pass values explicitly */}
|
|
<p>{t('Hi {name}', { name })}</p>
|
|
<p>{t('Saved {count} cards', { count })}</p>
|
|
|
|
{/* Resolve a lazily-declared descriptor */}
|
|
<ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>
|
|
</section>
|
|
);
|
|
};
|
|
```
|
|
|
|
### متى تستخدم أيًّا منها
|
|
|
|
* **`<Trans>…</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` لتمييز سلاسل المصدر المتطابقة التي تُترجَم بشكل مختلف:
|
|
|
|
```tsx
|
|
t({ message: 'Open', context: 'door' });
|
|
t({ message: 'Open', context: 'window' });
|
|
<Trans context="card-title">Untitled</Trans>
|
|
```
|
|
|
|
## الاستخراج والترجمة
|
|
|
|
شغِّل أمر الاستخراج من دليل تطبيقك:
|
|
|
|
```bash
|
|
twenty dev:translations-extract # collect strings into locales/en.json
|
|
twenty dev:translations-extract --locale fr-FR # also scaffold a target locale
|
|
```
|
|
|
|
يقوم الاستخراج بجمع كل من تسميات ملف البيان (manifest labels) وسلاسل `t()`/`msg()`/`\<Trans>` من شفرة الواجهة الأمامية (front-component) في `locales/\<locale>.json`، مفهرسة حسب سلسلة المصدر. املأ الترجمات:
|
|
|
|
```json
|
|
// locales/fr-FR.json
|
|
{
|
|
"Loading postcard…": "Chargement de la carte…",
|
|
"Hi {name}": "Bonjour {name}",
|
|
"Saved {count} cards": "{count} cartes enregistrées"
|
|
}
|
|
```
|
|
|
|
العناصر النائبة مثل `{name}` تُستبدَل وقت التشغيل — احتفظ بها في
|
|
الترجمة. أي سلسلة تُترَك فارغة تعود إلى نص المصدر.
|
|
|
|
## كيفية التشغيل
|
|
|
|
يقوم `twenty dev:build` بتجميع الكتالوجات وتقديم اللغة الصحيحة للمستخدم
|
|
الحالي: يتم حل تسميات ملف البيان (manifest labels) على جانب الخادم، ويتم تضمين كتالوجات الواجهة الأمامية (front-component)
|
|
داخل كل حزمة مكوّن. وقت التشغيل يقرأ المكوّن
|
|
اللغة (locale) من سياق التنفيذ الخاص به (لغة المضيف الحالية) ويحل كل سلسلة مقابل كتالوجه، مع الرجوع إلى المصدر عندما تكون الترجمة مفقودة. تغيير اللغة في المضيف يعيد تصيير سلاسل `\<Trans>` و
|
|
`useTranslate().t` مباشرة.
|
|
|
|
نظرًا إلى أنّ الكتالوجات تُجمَّع في وقت البناء، فإن تحديث ترجمة ما يعني
|
|
إعادة تشغيل `twenty dev:build` (وإعادة النشر)، تمامًا مثل أي تغيير آخر.
|
|
|
|
<Note>
|
|
يتم تجميع الترجمات بواسطة `twenty dev:build` (و`twenty apply`). تشغيل المراقبة المستمرة `twenty dev`
|
|
يعرض سلاسل المصدر، لذا اختبر المخرجات المترجمة ببناء (build) لمرة واحدة.
|
|
</Note>
|
|
|
|
قد تمتد عناصر النص التابعة لـ `<Trans>` على عدة أسطر — يتم ضغط المسافات
|
|
بنفس الطريقة التي يقوم JSX بضغطها، لذلك كل من `<Trans>Welcome\n back</Trans>`
|
|
ومفتاح الاستخراج يصبحان `Welcome back`.
|