# الترجمات

> كيف تُترجم Octa Pass، وأين توجد النصوص والتوثيق العربي، ودور Weblate، وقواعد النص من اليمين إلى اليسار، وكيف تضيف لغة جديدة.

Source: https://octap.app/ar/docs/contributing/translations/
Status: in-progress
Project: Octa Pass

:::note[قيد التطوير]
الإنجليزية والعربية موجودتان في المستودع. مشروع Weblate لم يُفتح بعد: سيُفتح عندما يصبح المستودع عامًا. إلى ذلك الحين، أرسل التصحيحات في طلبات دمج.
:::

الإنجليزية هي اللغة المصدر. وكل اللغات الأخرى تتبعها.

## ما الذي يُترجم

| ماذا | المصدر | الترجمات |
|---|---|---|
| خزنة الويب، وتستخدمها كل التطبيقات | `apps/web/src/i18n/en.ts` | `ar.ts`، و`translations/web/<language>.json` |
| إضافة المتصفح | `apps/extension/src/i18n.ts` | `translations/extension/<language>.json` |
| تطبيق سطح المكتب | `apps/desktop/src/i18n.ts` | `translations/desktop/<language>.json` |
| تطبيقات الهاتف | `apps/web/src/i18n/phone.ts` | `translations/phone/<language>.json` |
| الموقع | `apps/website/src/i18n/landing/en.json` | `<language>.json` بجانبه |
| واجهة التوثيق | `apps/website/src/content/i18n/en.json` | `<language>.json` بجانبه |
| صفحات التوثيق | `docs/<path>.md` | `docs/<language>/<path>.md` |

يبقى سجل التغييرات بالإنجليزية. أما تطبيقا iPhone وAndroid الأصليان فيأخذان نصوصهما من كتالوجي الويب والهاتف عبر `tools/native-resources`، فلا يحتاجان إلى ترجمة خاصة بهما.

## تصحيح ترجمة

افتح **Weblate** عندما يعمل، أو عدّل الملف في طلب دمج:

- **نصوص التطبيقات:** عدّل `ar.ts` أو الكتلة `ar` في كتالوج التطبيق، ثم شغّل `node tools/translations/sync.mjs export`. يتحقق CI من تطابق الاثنين.
- **التوثيق:** عدّل الصفحة الموجودة تحت `docs/ar/`.

يُنفّذ Weblate commits على ملفات `translations/` وعلى `docs/ar/`. شغّل `node tools/translations/sync.mjs import` لنقل التصحيحات العربية من `translations/` إلى كتالوجات TypeScript.

## إبقاء التوثيق متزامنًا

يعرض الأمر `node tools/translations/check-docs.mjs` الصفحات الإنجليزية التي لا ترجمة لها، ويفشل عند وجود ترجمات فقدت صفحتها الإنجليزية، أو غيّرت قيمة `status` لصفحة، أو تشير إلى صفحة إنجليزية. الصفحة التي لا ترجمة لها تعرض النص الإنجليزي مع تنبيه، فلا تترك أي صفحة إنجليزية جديدة فجوة في الموقع.

## قواعد العربية

- العربية الفصحى المعاصرة، بسيطة ومباشرة، وبالنبرة نفسها كما في الإنجليزية.
- استخدم الكلمات التي تستخدمها التطبيقات. الكتالوج العربي `apps/web/src/i18n/ar.ts` هو المسرد: مثلًا «الخزنة» مقابل vault و«البريد المُقنَّع» مقابل masked email.
- تبقى أسماء المنتجات بالأحرف اللاتينية: Octa Pass وTouch ID وWindows Hello وWeblate.
- الأرقام الغربية (0–9)، كما في التطبيقات.
- الأوامر والشيفرة وأسماء الملفات وأسماء الإعدادات مثل `OCTAPASS_PUBLIC_URL` والروابط تبقى كما هي.
- الرسائل ذات العدد تحتاج إلى أشكال الجمع الستة كلها: zero وone وtwo وfew وmany وother.
- لا تباعد بين أحرف النص العربي: فهو يكسر اتصال الحروف.

## إضافة لغة

1. افتح اللغة في Weblate، أو أضف `translations/<component>/<language>.json` يدويًا.
2. أضفها إلى `LOCALES` في `apps/web/src/i18n/core.ts` مع اتجاهها، وحمّل كتالوجاتها في كل تطبيق.
3. أضفها إلى `locales` في `apps/website/astro.config.mjs`.
4. ترجم ما تستطيع من [صفحات التوثيق](#ما-الذي-يُترجم). وتعود البقية إلى الإنجليزية.

الخطوة 2 تغيير في الشيفرة عن قصد: تُطلق اللغة عندما تكتمل نصوص تطبيقاتها، لأن مدير كلمات المرور المترجم جزئيًا يسهل أن يُساء فهمه.

## إعداد Weblate

للمشرفين. يشير الملف `.weblate` بعميل `wlc` إلى المشروع، ويسرد `translations/weblate.json` كل مكوّن مع قناع الملف وصيغته وإعداداته. تستخدم صفحات التوثيق مكوّن Markdown واحدًا لكل صفحة، تنشئه إضافة اكتشاف المكوّنات، مع تفعيل **Translate front matter values**. راجع `translations/README.md`.