upstream-twenty/packages/twenty-docs/l/ar/developers/extend/apps/operations/translations.mdx

---
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`** — نص ثابت في 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>
```

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

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

شغِّل أمر الاستخراج من دليل تطبيقك:

```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",
  "door": {
    "Open": "Ouvrir"
  },
  "objectMetadata.labelSingular": {
    "Postcard": "Carte postale"
  }
}
```

السلاسل غير المرتبطة بسياق هي مدخلات مسطَّحة؛ أما السلاسل المرتبطة بسياق — بما في ذلك كل تسمية في ملف manifest — فهي متداخلة تحت مفتاح السياق الخاص بها.

العناصر النائبة مثل `{name}` تُستبدَل وقت التشغيل — احتفظ بها في
الترجمة. أي سلسلة تُترَك فارغة تعود إلى نص المصدر.

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

يقوم `twenty dev:build` بتجميع الكتالوجات وتقديم اللغة الصحيحة للمستخدم
الحالي: يتم حل تسميات ملف البيان (manifest labels) على جانب الخادم، ويتم تضمين كتالوجات الواجهة الأمامية (front-component)
داخل كل حزمة مكوّن. وقت التشغيل يقرأ المكوّن
اللغة (locale) من سياق التنفيذ الخاص به (لغة المضيف الحالية) ويحل كل سلسلة مقابل كتالوجه، مع الرجوع إلى المصدر عندما تكون الترجمة مفقودة. تغيير اللغة في المضيف يعيد تصيير سلاسل `Trans` و
`useTranslate().t` مباشرة.

تُصرَّف تسميات Manifest عند كل مزامنة — `twenty dev:build` و`twenty apply`
وكذلك المراقبة المستمرة `twenty dev` — لذا يكفي تعديل ملف لغة
والمزامنة لرؤية النص الجديد. تُضمَّن كتالوجات مكوّنات Front في
كل حزمة مكوّنات وقت البناء، لذا فإن تغيير أحدها لا يزال يعني
إعادة تشغيل `twenty dev:build` (وإعادة النشر).

قد تمتد عناصر النص التابعة لـ `Trans` على عدة أسطر — يتم ضغط المسافات
بنفس الطريقة التي يقوم JSX بضغطها، لذلك كلاهما يتم استخلاصه إلى المفتاح `Welcome back`:

```tsx
<Trans>Welcome back</Trans>
<Trans>
  Welcome
  back
</Trans>
```