---
order: 6
section: features
title: الرموز المضمنة (Inline tokens)
description: >-
  قم بتضمين الروابط، وعناوين URL للأصول، والنصوص غير القابلة للترجمة في محتوى
  MDX باستخدام رموز تتحدث تلقائيًا في كل لغة دون الحاجة لإعادة الترجمة.
noindex: false
canonicalPath: /ar/docs/inline-tokens
---
غالبًا ما تحتاج نصوص MDX إلى قيم يعرفها Scribe مسبقًا، مثل رابط لمدخل آخر، أو عنوان URL عام لأصل معين، أو نص ثابت يجب ألا يُترجم أبدًا، أو سلسلة نصية صغيرة تتكرر في أماكن عدة داخل المستند نفسه. كتابة هذه القيم يدويًا وبشكل ثابت تجعل النصوص هشة (فتغيير اسم معرف الارتباط أو نقل أصل ما سيؤدي إلى كسر الروابط بصمت)، كما أنها تفسد عملية الترجمة (إذ لا ينبغي أبدًا "ترجمة" عناوين URL).

وهنا يأتي دور الرموز المضمنة لحل هذه المشكلة. أنت تكتب الرمز مرة واحدة في النص الإنجليزي، ويتم حله لكل لغة عند القراءة، بينما تتعامل معه عملية الترجمة كعنصر نائب ثابت ومبهم لا يمكن تعديله.

## بناء الجملة

يأخذ الرمز الشكل `${{<kind>:<args>}}`. وهناك أربعة أنواع:

| الرمز | يتم حله إلى | 
| --- | --- |
| `${{static:"text"}}` | النص الحرفي الثابت `text` (وهو سلسلة JSON، لذا فإن علامات الاقتباس وعلامات التخطي محددة بوضوح). لا يُترجم أبدًا، ويكون متطابقًا في كل اللغات. |
| `${{relation:<typeId>:<enSlug>:href}}` | **مسار رابط** يشير إلى المدخل المستهدف (انظر [أوضاع العلاقات](#relation-modes)). لاحقة الوضع مطلوبة هنا. |
| `${{relation:<typeId>:<enSlug>:slug}}` | **معرف الارتباط الإنجليزي** (English slug) الخاص بالهدف، وهو معرف ثابت لمكونات MDX التي تقوم بتحميل محتوى Scribe بنفسها. |
| `${{asset:/web/path.webp}}` | عنوان URL العام للأصل (أي `assets.publicPath` مضافًا إليه المسار). انظر [الأصول](/docs/assets). |
| `${{var:key}}` | قيمة `frontmatter.vars[key]` في المستند ذاته. |

لا يمكن لمعرفات الارتباط (slugs) أن تحتوي على النقطتين الرأسيتين `:`، لذا فإن تحليل العلاقات يكون خاليًا من اللبس. كتابة الرمز `${{relation:<typeId>:<enSlug>}}` مجردًا بدون لاحقة الوضع سيؤدي إلى خطأ في التحقق من الصحة.

### أوضاع العلاقات

يجب أن ينتهي كل رمز علاقة بـ `:href` أو `:slug`.

| الوضع | الغرض |
| --- | --- |
| `:href` | رابط قابل للتنقل. يعتمد الشكل النهائي على المستهلك (كما هو موضح أدناه). |
| `:slug` | الهوية، وهي دائمًا معرف الارتباط الإنجليزي الخاص بالهدف. |

يتم حل الوضع `:href` بطرق مختلفة بناءً على من يقرأ المستند:

| المستهلك | يتم حل `:href` إلى |
| --- | --- |
| `createScribe()` (وقت تشغيل التطبيق) | مسار خالٍ من معلومات اللغة يحتوي على معرف الارتباط المترجم، مثل `/for/vestidos`، ويمرر مباشرة إلى مكون `Link` في موجهك (router). |
| تصدير ملفات `.md` الثابتة | المسار العام الكامل والمترجم مع امتداد الملف، مثل `/es/for/vestidos.md`، بما يتطابق مع بنية ملفات التصدير. |

### مخرج الطوارئ

إن كتابة `${{` (مع وضع شرطة مائلة خلفية بين علامة الدولار والأقواس المعقوفة) ستعرض النص الحرفي `${{` ولن يُعامل كرمز مضمن أبدًا. يمكنك استخدام هذه الطريقة لعرض بناء جملة الرموز في محتوى التوثيق، وهذا بالضبط ما تفعله هذه الصفحة.

## مفتاح `vars` في الترويسة (Frontmatter)

يُعد `vars` سجلاً اختياريًا من النوع `Record<string, string>` يمكن لأي مدخل الإعلان عنه **دون** الحاجة لإضافته إلى مخطط النوع:

```mdx
---
title: تخفيضات الربيع
vars:
  cta: تسوق الآن
---

مستعد؟ ${{var:cta}}. لفترة محدودة فقط.
```

يُعتبر `vars` مفتاحًا محجوزًا، حيث يتم استخراجه قبل التحقق من صحة المخطط (لذا فإن المخطط الصارم لن يرفضه أبدًا)، ولا يُعامل أبدًا كحقل قابل للترجمة، ويتواجد فقط في المستند الإنجليزي. تقرأ المستندات المترجمة `${{var:key}}` من خريطة `vars` الموجودة في مستندها الإنجليزي الأصلي، مما يضمن وجود مصدر وحيد للحقيقة.

## التجزئة والترجمة

يتم استخراج الرموز قبل إجراء عملية التجزئة (hashing). يُستبدل كل رمز بعلامة مرقمة خاملة (`%%1%%`، `%%2%%`، وما إلى ذلك، حسب ترتيب ظهورها)، وهذا *النص الذي يحتوي على العناصر النائبة* هو ما يتم تجزئته وإرساله إلى المترجم. ويترتب على ذلك ما يلي:

- **تغيير قيمة الرمز** (النص الثابت، هدف العلاقة، مسار الأصل، أو قيمة `var`) **لا** يغير التجزئة الإنجليزية، لذا لن تعتبر أي ترجمة قديمة بسبب تعديل يقتصر على القيمة فقط.
- **إضافة أو إزالة أو إعادة ترتيب الرموز** **يؤدي** إلى تغيير التجزئة، وبالتالي تتم إعادة جدولة الترجمات كما هو متوقع.
- **النص الخالي من الرموز** يُجزأ تمامًا كما كان من قبل، لذا فإن البدء في استخدام الرموز لن يتسبب في تقادم أعداد كبيرة من النصوص فجأة.

يتم توجيه المترجم بأن العلامات `%%n%%` ثابتة ولا يمكن تغييرها، حيث يجب تكرار كل علامة مرة واحدة بالضبط، ولا يجوز ترجمتها أو إعادة ترقيمها أبدًا، ولا يُسمح بتحريكها داخل الجملة إلا إذا تطلبت قواعد اللغة ذلك. وبعد استلام الترجمة، يتم إجراء فحص ما بعد الاستلام للتأكد من ظهور كل علامة مرة واحدة بالضبط، وفي حال وجود أي تعارض، سيفشل السطر لتتم إعادة المحاولة. تحتفظ النصوص المترجمة والمحفوظة بالعلامات وتقوم بتعبئتها وقت القراءة.

## الاستبدال وقت القراءة

الاستبدال هو عملية تتم في مسار القراءة، وتُضبط بطريقة مشابهة لحل الأصول. تقوم دالة `createScribe()` بتفعيلها لوقت تشغيل التطبيق، بينما تفعلها عمليات التصدير الثابتة لبنية ملفات `.md`. في المقابل، تحتفظ واجهة سطر الأوامر (CLI)، وأمر `scribe validate`، والاستوديو ببناء جملة الرموز كما هو، حتى تتمكن من فحص النصوص المصدرية وإعادة تجزئتها.

- **المستندات الإنجليزية** يتم استبدال رموزها في مكانها، وحلها للغة الافتراضية.
- **المستندات المترجمة** يتم تعبئة علاماتها `%%n%%` باستخدام قائمة الرموز المستخرجة من النص الإنجليزي **الحالي**، وحلها بناءً على لغة المستند. هكذا يشير رابط العلاقة دائمًا إلى معرف الارتباط المترجم المباشر، حتى وإن كانت الترجمة نفسها أقدم.

هناك حالتان استثنائيتان يتم حلهما إلى سلسلة نصية فارغة أثناء وقت التشغيل (ويقوم `scribe validate` بوضع علامة عليهما)، وهما علاقة لا يمتلك نوع هدفها `path` في وضع `:href`، ومفتاح `var` مفقود.

## التحقق من الصحة

يقوم `scribe validate` بالإبلاغ عن هذه المشكلات على مستوى المدخل:

- **بناء جملة الرمز مشوه** (سلسلة JSON غير صالحة، أو عدد وسائط غير صحيح، أو نوع غير معروف): خطأ.
- **`relation`**: معرف نوع `typeId` غير معروف، أو معرف ارتباط إنجليزي `enSlug` غير معروف، أو وضع مفقود، أو علاقة `:href` تستهدف نوعًا غير قابل للتوجيه: خطأ.
- **`asset`**: الملف غير موجود على القرص: خطأ.
- **`var`**: المفتاح غائب عن خريطة `vars` الخاصة بالمستند، أو أن `vars` ليست سجلاً يربط بين سلاسل نصية: خطأ.

يتم إخفاء الرموز الخام كنص خامل قبل التحقق من صحة نص MDX، لذا فإن الرمز الصالح لن ينتج أبدًا خطأً زائفًا في تحليل MDX.

## مراجع النصوص والحذف

تقوم لوحة "مُستخدم بواسطة" (Used by) في الاستوديو ومتصفح الأصول بمسح النصوص، فتظهر الرموز `${{relation:...}}` كمراجع خلفية (تسمية الحقل `body`)، وتسجل الرموز `${{asset:...}}` كمراجع أصول معلنة. إن حذف مدخل يُشار إليه فقط من **نص** مدخل آخر لن يتسبب أبدًا في حذف متسلسل، أو فصل، أو حظر (انظر [حذف المدخلات](/docs/cli#scribe-delete)). تسرد خطة الحذف هذه المراجع تحت قسم "مراجع النصوص" بغرض التحذير فقط، وسوف تصبح معلقة وتتحول إلى أخطاء في التحقق من الصحة بعد عملية الحذف.