كيفية ترجمة ملفات Markdown دون إفساد الشيفرة أو الروابط أو البيانات الأمامية

لترجمة ملف Markdown، ترجم النص العادي واترك البنية التقنية كما هي: مفاتيح البيانات الأمامية، والشيفرة، وعناوين URL، وتسميات الروابط، ووسوم المكونات، وتسميات الحواشي يجب أن تعود بايتًا ببايت. ثم تحقق من ثلاثة أمور لا تزال الترجمة الدقيقة تفسدها: الروابط إلى العناوين، وتعليقات الشيفرة، وفي الصينية أو اليابانية أو الكورية، المسافات حول النص العريض ونطاقات الأرقام.

ترجمنا صفحة MDX من 73 سطرًا إلى الصينية المبسطة تسع مرات باستخدام نموذج محلي، مع ثلاث مطالبات مختلفة، وفحصنا كل نتيجة بسكربت. الأجزاء التي يقلق الناس بشأنها عادةً نجت في المحاولات التسع جميعًا: الشيفرة، والشيفرة المضمنة، وعناوين URL، والجدول، ومكوّن JSX، وقائمة المهام. لكن ثلاثة أمور أخرى أخفقت. انكسر الرابط إلى عنوان في المحاولات التسع جميعًا. وتُرجمت تعليقات الشيفرة في المحاولات الست جميعًا التي أرسلت الملف كاملًا، بما في ذلك ثلاث محاولات قال فيها نص المطالبة بعدم المساس بالشيفرة. أما المطالبة التي أخفت الصياغة خلف عناصر نائبة، والتي تبدو الخيار الأكثر أمانًا، فقد أفسدت البيانات الأمامية في محاولاتها الثلاث جميعًا.

إجابة سريعة: ما يجب ترجمته وما يجب تركه كما هو

كل ما عدا ذلك نثر عادي: الفقرات وعناصر القوائم وخلايا الجداول والاقتباسات.

ما الذي اختبرناه

كتبنا sample-source.mdx، وهي صفحة توثيق لتطبيق قراءة خيالي يُدعى Shelfmark. وهي مكتوبة بأسلوب MDX الذي تستخدمه Docusaurus والمواقع التوثيقية المشابهة، مع مثال واحد لكل تركيب في الجدول أعلاه، إضافة إلى فاصل سطر صلب بمسافتين، ورابط عريض، وعبارة عريضة تنتهي بقوس، ونطاقين رقميين مكتوبين بشرطات en، ورابط داخل الصفحة إلى العنوان "احتفظ بمسرد واحد للكتاب بأكمله."

ثم طلبنا من نموذج محلي ترجمتها إلى الصينية المبسطة بثلاث طرق:

1. الملف كاملاً. الصق الملف بأكمله واطلب إعادة الملف المترجم.
2. مع التعليمات. الأمر نفسه، مع ست قواعد: احتفظ بمفاتيح front matter، ولا تغيّر شيئاً داخل الشيفرة، واحتفظ بعناوين URL وتعريفات المراجع، واحتفظ بالاستيرادات والوسوم والتعليقات، واحتفظ بتسميات الحواشي وعلامات التنبيه، وترجم العناوين ونصوص الروابط والنصوص البديلة وسمة title.
3. محمي. استبدل الشيفرة والشيفرة المضمّنة وعناوين URL والوسوم والتعليقات وتسميات الحواشي وعلامات التنبيه وأسطر front matter بعناصر نائبة مرقّمة مثل ⟦12⟧، ثم ترجم الباقي، ثم أعد الأصل. تُركت قيمتا title و description مكشوفتين للترجمة، وكذلك — كما اتضح — أسطر --- في front matter وعلامات الاقتباس الختامية.

كان النموذج Qwen 3.6 27B (Q4_K_M) في LM Studio، مع إيقاف التفكير ودرجة حرارة 0.3، على جهاز Apple M4 Max بذاكرة 64 غيغابايت. شغّلنا كل حالة ثلاث مرات، أي تسع تشغيلات إجمالاً، في 25 أكتوبر 2026. السكربت هو run_llm_markdown_test.py، وجميع المخرجات التسعة منشورة دون تحرير؛ ويسرد README كل ملف. إذا لم تكن قد أعددت نموذجاً محلياً من قبل، فإن دليل الترجمة بنموذج LLM محلي يغطي الإعدادات.

كان هذا اختباراً صغيراً لنموذج واحد وزوج لغوي واحد وصفحة واحدة. يوضح المشكلات التي تحدث وكيفية اكتشافها. ولا يصنّف النماذج أو المطالبات.

النتيجة: نجت البنية؛ أما الروابط والقرارات فلم تنجُ

فحصنا كل مخرج باستخدام check_markdown_translation.py وعرضنا كل واحد منها باستخدام remark ومترجم MDX. مخرجات الفاحص الكاملة موجودة في check-results.txt، ويحتوي results.csv على صف واحد لكل تشغيل.

الصفوف الأولى هي الأخبار السارة. أعاد هذا النموذج صياغة Markdown سليمة عندما لصقنا الملف كاملاً؛ لم نجد شيئًا لإصلاحه في الشيفرة أو عناوين URL أو الجداول. الصفوف الأربعة الأخيرة هي موضع العمل، ولا يظهر أي منها كخطأ عند بناء الموقع.

1. العناوين المترجمة تكسر الروابط المؤدية إليها

يربط النموذج بقسم المصطلحات الخاص به عبر [glossary section](#keep-one-glossary-for-the-whole-book). ترجمت كل محاولة العنوان كما ينبغي، وأبقت كل محاولة هدف الرابط كما ينبغي. النتيجة رابط إلى معرّف لم يعد موجودًا.

تبني معظم أدوات Markdown معرّفات العناوين من نص العنوان. تصف وثائق Pandoc المعرّف بأنه "مبني على نص العنوان"، وتحذر Docusaurus من أنك قد ترغب في تغيير عنوان أو ترجمته "دون تحديث المعرّف الحالي لتجنب كسر الروابط". بمجرد أن يصبح العنوان 为整本书保留一个术语表، يصبح معرّفه المولّد بالصينية، ولا يؤدي #keep-one-glossary-for-the-whole-book إلى أي مكان. لا تزال الصفحة تُبنى، لذا لا شيء يخبرك بذلك.

لا يمكنك إصلاح ذلك بتعديل الرابط بعد الترجمة أيضًا. عبر تسع محاولات كتب النموذج العنوان نفسه بأربع طرق مختلفة، لذا سيتغير المعرّف المولّد مع كل إعادة ترجمة. الإصلاح يجب أن يسبق الترجمة: أعطِ كل عنوان مرتبط معرّفًا ثابتًا.

• في Docusaurus MDX، استخدم ## Keep one glossary for the whole book {/* #keep-one-glossary */}. تشير Docusaurus إلى أن الصيغة الأقدم {#id} "لم تعد صياغة MDX صالحة"، ويضيف أمر write-heading-ids الخاص بها معرّفات إلى كل مستند نيابة عنك.
• في Pandoc وفي معالجات Markdown التي تتبع PHP Markdown Extra، استخدم {#keep-one-glossary} في نهاية العنوان.

يبقى المعرّف بعد ذلك كما هو في كل لغة، ويعامله المدقق كهدف الرابط.

2. تُترجم تعليقات الشيفرة، ولا تُترجم السلسلة المرئية

يحتوي النموذج على تعليق shell وتعليق YAML:

library:
  name: "My books"   # shown in the sidebar
  sort: title

جميع المحاولات الست التي أرسلت الملف كاملاً ترجمت كلا التعليقين، بما في ذلك الثلاث التي قال فيها الموجه "لا تغير أي شيء داخل كتل الشيفرة المسورة." لم تُمس الشيفرة نفسها في أي من المحاولات التسع. وفي الوقت نفسه، بقي "My books"، الذي يقول التعليق إنه يظهر في الشريط الجانبي، بالإنجليزية في جميع المحاولات التسع. فعل النموذج عكس ما تحتاجه صفحة مترجمة: ترجم الملاحظة للمطورين وترك التسمية التي سيراها القراء.

لا يوجد خيار خاطئ في كل الحالات. بالنسبة لبرنامج تعليمي سينسخ قراؤه الشيفرة إلى مشروعهم الخاص، تساعد التعليقات المترجمة. بالنسبة لوثائق مرجعية يجب أن تتطابق شيفرتها مع مستودع، تجعل الصفحة تختلف عن المصدر. اتخذ القرار مرة واحدة للمشروع، وافحص قيم السلاسل في أمثلة التكوين يدويًا، لأن لا أداة يمكنها التمييز بين تسمية عرض ومعرّف. ولهذا السبب يبلغ المدقق عن التغييرات في التعليقات فقط كتحذيرات.

3. الطريقة التي تبدو آمنة كسرت البيانات الأمامية

فعل الشرط المحمي ما وعد به: عادت جميع العناصر النائبة الـ 32 في المحاولات الثلاث، لذا تمت استعادة الشيفرة وعناوين URL والوسوم بشكل مثالي. لكن سكربتنا ترك شيئين صغيرين خارج العناصر النائبة: سطر --- الذي يفتح البيانات الأمامية، وعلامة الاقتباس الختامية بعد العنوان والوصف المترجمين. أسقطها النموذج جميعًا في المحاولات الثلاث. بدأ الملف هكذا:

title: "导出您的书库
description: "在更换设备之前，请备份您的笔记和书籍。
slug: export-library

بدون --- الافتتاحية، لم يعد محلل Markdown يرى البيانات الأمامية. يقرأ أسطر YAML الستة بالإضافة إلى --- الختامية كعنوان، لذا ستفتح الصفحة بعنوان كبير يحتوي على YAML. لا يزال يُترجم كـ MDX. إعادة --- ليست كافية أيضًا: يرفض محلل YAML علامتي الاقتباس غير المغلقتين.

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

النص العريض والنطاقات في الصينية واليابانية والكورية

لم تظهر مشكلتان إضافيتان في محاولاتنا التسع، لكن يجدر التحقق منهما لأنهما تكسران الصفحات بصمت، وقد أصابتا مدونة BookTranslator نفسها. المدونة مكتوبة بـ MDX وتُترجم آليًا إلى 27 لغة، وفي إحدى جولات الترجمة المجدولة فشل مقالان كوريان في فحص البنية لدينا ثلاث مرات متتالية. كانت الأسباب هما النمطان أدناه.

خط عريض ينتهي بعلامة ترقيم. يقرر CommonMark ما إذا كان ** يمكنه فتح أو إغلاق الخط العريض من خلال النظر إلى الأحرف على جانبيه. يجب أن يتبع ** الإغلاق الذي يأتي مباشرة بعد علامة ترقيم مسافة أو علامة ترقيم أو نهاية السطر؛ وهذه هي قاعدة الجناح الأيمن. تحتوي الإنجليزية دائمًا على مسافة هناك. أما الصينية واليابانية والكورية فغالبًا لا تحتوي عليها. لذا فإن 打开**设置 → 导出（测试版）**并选择 تظهر كنجوم حرفية، لأن الخط العريض ينتهي بقوس عرض كامل ويتبعه مباشرة حرف 并. السطر نفسه بدون القوس يُعرض بخط عريض، وكذلك السطر الذي يحتوي على مسافة بعد **. الرابط العريض يعاني من المشكلة نفسها، لأن الرابط ينتهي بـ ): 点击**[导出](./export-options.md)**打开 يفشل، وكذلك الكورية **[API](./api.md)**는.

وضع نموذجنا مسافة على جانبي كل عبارة عريضة، لذا عُرض ناتجه بشكل صحيح. المحرر الذي يزيل تلك المسافات لاحقًا لاتباع قواعد التنضيد الصينية يعيد الخطأ. يمكنك تجربة المتغيرات السبعة كلها في render-cases.md.

نطاقات الأرقام مع التلدة. غالبًا ما تكتب النصوص الصينية واليابانية النطاقات على شكل 3~5. مواقع GitHub Flavored Markdown المبنية على remark تحول التلدات المفردة إلى نص مشطوب افتراضيًا: خيار remark-gfm singleTilde يكون true ما لم تغيره. نطاقان في فقرة واحدة، مثل 需要 3~5 分钟，生成 10~20 MB 的文件夹، يُعرضان والنص بينهما مشطوب. استخدم نموذجنا شرطات قصيرة، واحتفظت ثمانية تشغيلات بها بينما كتب التاسع 3 到 5. اطلب شرطات قصيرة أو كلمات في النطاقات، أو اضبط singleTilde: false في إعداد remark الخاص بك.

يشير المدقق البنيوي إلى كلا النمطين. للتأكد مما يُعرض فعليًا، يحصي render_check.mjs الخط العريض والمائل والمشطوب والنجوم المتبقية في المصدر والترجمة، ويجرب تجميع MDX:

npm install @mdx-js/mdx@3 unified@11 remark-parse@11 remark-gfm@4
node render_check.mjs source.mdx translated.mdx

عدد أقل من عقد الخط العريض أو نجوم حرفية أكثر في الترجمة يعني أن بعض التوكيد توقف عن الإغلاق.

سير عمل يصمد

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

2. أخرج البيانات الأمامية من الصفحة. ترجم فقط القيم الموجهة للقارئ مثل title وdescription، كسلاسل منفصلة، وأعد كتابتها في YAML الأصلي.

3. حدد سياسة الشيفرة. التعليقات مترجمة أم لا؛ سلاسل العرض في أمثلة التكوين مترجمة أم لا. اكتبها في مسرد الترجمة بجانب أسماء المنتجات التي يجب ألا تتغير، مثل Shelfmark في نموذجنا.

4. ترجم النص الأساسي. استخدم أداة تحلل Markdown، أو أرسل الصفحة كاملة بقواعد صريحة. في اختبارنا، أبقى إرسال الصفحة كاملة الصياغة سليمة؛ إذا استخدمت عناصر نائبة، احمِ البنى الكاملة ولا تترك شيئًا نصف مكشوف.

5. شغّل الفحص البنيوي.

   python3 check_markdown_translation.py source.mdx translated.mdx --keep Shelfmark
   

   يقارن مفاتيح وقيم البيانات الأمامية، والاستيرادات، وكتل الشيفرة، والشيفرة المضمنة، وأهداف الروابط، وتعريفات المراجع، ومستويات العناوين، وأهداف الروابط داخل الصفحة، ووسوم وسمات JSX، وتعليقات MDX، وعلامات التنبيه، وتسميات الحواشي، وشكل الجدول، ومربعات قوائم المهام، وفواصل الأسطر الصلبة، والتوكيد الذي لا يمكن إغلاقه، ونطاقات التلدة، والمصطلحات التي تطلب الاحتفاظ بها. لا يحكم على جودة الترجمة.

6. افحص العرض للأهداف CJK باستخدام render_check.mjs، وأضف مسافة بعد أي ** إغلاق يتبع علامة ترقيم.

7. ابنِ الموقع وانقر على الروابط. افتح الصفحة بكل لغة، وانقر على كل رابط داخل الصفحة، واقرأ أمثلة التكوين. البناء الناجح يثبت فقط أن الملف يُجمّع.

بالنسبة للتوثيق حيث تهم الدقة، تنطبق خطوات المصطلحات والمراجعة في سير عمل الترجمة التقنية فوق هذا.

أين يتناسب BookTranslator

مترجم TXT من BookTranslator يقبل ملفات .txt و.md و.mdx. وفقًا لصفحة المنتج، يترجمها مع الحفاظ على الفقرات وفواصل الأسطر والأحرف الخاصة وبنية النص، ويقسم الملفات الكبيرة إلى مقاطع للترجمة الواعية بالسياق، لذا يمكنك رفع دليل كامل أو كتاب مكتوب بصيغة Markdown بدلاً من لصقه قطعًا.

لا تصف صفحة المنتج معالجة خاصة للبيانات الأمامية أو كتل الشيفرة أو مكونات MDX، ولم نشغّل هذا النموذج عبر BookTranslator لهذا المقال. أيًا كانت الأداة التي تستخدمها، نفذ الخطوات من 1 إلى 3 قبل الترجمة والخطوات من 5 إلى 7 بعدها. العنوان بدون معرف ثابت يفقد روابطه، والنطاق المكتوب بتلدات يتحول إلى نص مشطوب. إذا كنت تنشر كتابًا بعدة لغات، فإن دليلنا للنشر الذاتي بعدة لغات يغطي بقية تلك المهمة.

احصل على ملفات الاختبار

كل شيء من هذا الاختبار مجاني لإعادة الاستخدام:

• sample-source.mdx: النموذج الإنجليزي المكون من 73 سطرًا؛
• check_markdown_translation.py: المدقق البنيوي (مكتبة Python القياسية فقط)؛
• render_check.mjs وrender-cases.md: فحص العرض وحالات اختبار CJK السبع؛
• run_llm_markdown_test.py: شروط المطالبة الثلاثة لأي خادم محلي متوافق مع OpenAI؛
• المخرجات التسعة في مجلد المخرجات، مع check-results.txt وresults.csv.