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

لترجمة ملف HTML، ترجم النص الذي يقرأه الناس والسمات التي تحمل كلمات موجهة للقارئ، مثل alt وtitle وplaceholder وaria-label ووصف الصفحة التعريفي. اترك الترميز كما هو: أسماء الوسوم، وhref، وsrc، وid، وclass، والنصوص البرمجية، والأنماط، وأي شيء محدد بـ translate="no". ثم غيّر قيمة واحدة يسهل نسيانها، وهي سمة lang في عنصر <html>، حتى تعرف المتصفحات وقارئات الشاشة ومحركات البحث لغة الصفحة الآن.

تبيّن أن الحفاظ على الوسوم سليمة كان الجزء السهل. ترجمنا صفحة مساعدة HTML من 59 سطرًا إلى الصينية المبسطة تسع مرات باستخدام نموذج محلي، بثلاث طرق، وفحصنا كل ناتج بسكربت. حافظت كل جولة على كل وسم ورابط ومعرّف. ما حدث من خطأ كان أهدأ: ترجم النموذج سطرًا داخل كتلة شيفرة <pre> في الجولات الست التي أرسلت الملف كاملًا، وترك aria-label الخاص بالتنقل بالإنجليزية في الجولات الست، والطريقة التي تحافظ على الترميز بأمان أكبر بحكم التصميم، أي ترجمة قطع النص واحدة تلو الأخرى، أنتجت جملة تخبر القارئ بفعل الشيء الخاطئ في جولاتها الثلاث.

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

هذه القائمة ليست من ابتكارنا. يحدد قسم سمة translate في معيار HTML "السمات القابلة للترجمة": title في كل عنصر، وalt في الصور، وplaceholder في حقول الإدخال، وcontent في عناصر meta التي يُعرف أن اسمها قابل للترجمة، وlang التي يقول إنه يجب تغييرها لتطابق اللغة الجديدة. كما يذكر aria-label الخاصة بـ ARIA كمثال على سمة يمكن لمواصفات أخرى إضافتها، ويقول إنه في عنصر translate="no"، "يُترك النص وقيم السمات كما هي عند توطين الصفحة."

ما اختبرناه

كتبنا sample-source.html، وهي صفحة مركز مساعدة لتطبيق القراءة الخيالي نفسه، Shelfmark، الذي استخدمناه في اختبار ترجمة Markdown. تحتوي على مثال واحد لكل صف في الجدول أعلاه، بالإضافة إلى بعض الفخاخ:

• جملة مقسمة بواسطة وسوم مضمّنة: "قبل التصدير، احتفظ بنسخة احتياطية من ملاحظاتك. التصدير ينسخ كتبك، لكنه لا يحذف أي شيء من Shelfmark،" مع اسم المنتج داخل translate="no"؛
• جملة تحتوي على عنصري <code> مضمّنين وترتيبهما مهم: "اكتب المسار إلى مجلد <library> بعد --out"؛
• كتلة <pre><code> تحتوي على أمر وسطر واحد من مخرجات العينة، # Export finished: 128 books؛
• قاعدة CSS تُدرج كلمة "Note:" قبل فقرة؛
• رابط داخل الصفحة إلى #choose-format، ورابط mailto:، ونموذج بحث، وكتلة JSON-LD.

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

1. الملف كاملًا. الصق الملف كاملًا واطلب إعادة الملف المترجم.
2. مع التعليمات. نفس الشيء، بالإضافة إلى ثماني قواعد: احتفظ بكل وسم واسم سمة، لا تغير href وsrc وid وclass والقيم المشابهة، ترجم سمات النص ووسوم meta المدرجة، اترك <code> و<pre> و<script> و<style> دون تغيير باستثناء name وdescription في JSON-LD، احترم translate="no"، احتفظ بمراجع الأحرف والتعليقات، واضبط lang على zh-Hans.
3. المقاطع. نهج الأدوات التي تستخرج النص من HTML: يقوم سكربت بتقسيم الملف إلى وسوم ونص، ويتخطى <code> و<pre> و<script> و<style> وعناصر translate="no"، ويرسل قطع النص المتبقية وسمات النص إلى النموذج كقائمة JSON مرقمة، ثم يعيد كتابة الترجمات في الترميز غير المعدل. كما يضبط lang="zh-Hans" بنفسه.

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

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

النتيجة: نجا الترميز؛ وثلاثة قرارات لم تنجُ

تحققنا من كل ناتج باستخدام check_html_translation.py، وهو أداة فحص تستخدم مكتبة بايثون القياسية فقط. الناتج الكامل موجود في check-results.txt، ويحتوي results.csv على صف واحد لكل تشغيل.

حافظت كل تشغيلات التسعة على نفس الـ 58 وسمًا بنفس الترتيب، وكل href وsrc وid وclass، وهدف الرابط داخل الصفحة، والتعليق، و<library> المهرّب، واسم المنتج داخل translate="no". إذا كنت قلقًا من أن النموذج سيعبث بترميز صفحة بسيطة، فإنه لم يفعل. كانت المشكلات كلها في ما يجب ترجمته.

1. تمت ترجمة مخرجات نموذجية داخل <pre>

ينتهي كتلة الشيفرة في نموذجنا بسطر من مخرجات البرنامج:

<pre><code>shelfmark export --format epub --covers --out ~/Books/export
# Export finished: 128 books</code></pre>

في جميع التشغيلات الست للملف الكامل والتشغيلات الموجّهة، أعاد النموذج # 导出完成：128 本书 على ذلك السطر، بما في ذلك التشغيلات الثلاث التي قال فيها الموجّه بعدم تغيير أي شيء داخل <pre>. لم يُمس الأمر نفسه. تعامل النموذج مع السطر كتعليق، وترجمة التعليقات خيار معقول في درس تعليمي. لكن هذا السطر هو ما يطبعه البرنامج، والقارئ الذي يقارنه بطرفه سيرى الإنجليزية. قرر قبل أن تترجم ما إذا كانت المخرجات النموذجية وتعليقات الشيفرة تُترجم، وأخبر الأداة، أو احمِ كتل <pre> بالكامل.

ترجمت تشغيلات الملف الكامل أيضًا content: "Note: " في CSS داخل كتلة <style>، بينما أبقتها التشغيلات الموجّهة، التي طُلب منها ترك <style> دون مساس، بالإنجليزية. لا شيء من هذا خطأ بحد ذاته. ترجمة ورقة الأنماط صحيحة لصفحة يكون فيها CSS مضمّنًا، وخاطئة لموقع تخدم فيه ورقة أنماط مشتركة واحدة كل اللغات. في كلتا الحالتين، هذا قرار يجب أن يتخذه شخص ما، وليس تفصيلًا ينبغي أن يخمّنه النموذج.

2. تم تخطي تسميات إمكانية الوصول

التنقل عبر مسار التنقل هو <nav aria-label="Breadcrumb">. يعلن قارئ الشاشة تلك التسمية؛ ولا يراها القراء المبصرون أبدًا. في جميع التشغيلات الست للملف الكامل والتشغيلات الموجّهة، بقيت بالإنجليزية، رغم أن الموجّه الموجّه أدرج aria-label ضمن السمات المطلوب ترجمتها. في إحدى التشغيلات الموجّهة، بقي aria-label="Search" لزر البحث بالإنجليزية أيضًا.

ترجمتها طريقة التقسيم في كل مرة، لأن سكربتها جمع كل قيمة aria-label وalt وtitle وplaceholder وطلب ترجمة كل واحدة صراحةً. هذه أقوى حجة لاستخراج سمات النص عمدًا بدلًا من الأمل في أن يلاحظها النموذج.

3. ترجمة الأجزاء حافظت على الوسوم وأفسدت الجملة

طريقة التقسيم آمنة للترميز بحكم بنيتها: لا يرى النموذج أي وسم، فلا يمكنه إتلافه. اجتازت كل فحص هيكلي في الجولات الثلاث. كما أنتجت الترجمة الوحيدة في الاختبار التي أعطت القارئ تعليمات خاطئة.

الجملة الإنجليزية هي "Type the path to the <library> folder after --out." يقسمها <code> المضمّن إلى ثلاثة أجزاء: "Type the path to the"، و"folder after"، ونقطة. تضع الصينية هذه الكلمات بترتيب مختلف، لذا يحتاج المترجم إلى نقل عنصري الكود. لا تستطيع طريقة التقسيم نقلهما. عكست الجولات الثلاث التعليمات. أنتجت الجولة 2 هذا (تقول الجولتان 1 و3 后 بدلاً من 之后، بالمعنى نفسه):

在 <code>&lt;library&gt;</code> 之后输入 <code>--out</code>文件夹的路径。

يُقرأ ذلك "بعد <library>، اكتب مسار مجلد --out،" وهو عكس التعليمات. نقلت الجولات الست كاملة الملف والموجَّهة عنصري الكود وأصابت:

在 <code>--out</code> 后面输入 <code>&lt;library&gt;</code> 文件夹的路径。

ترك التقسيم نفسه مسافات شاذة حيث يلتقي الوسم بالنص الصيني، مثل 前往 <b>设置</b> و<b>书库</b> ，، في جولات التقسيم الثلاث، ستة مواضع في كل جولة. يعرضها المتصفح كفراغات مرئية، بما في ذلك قبل علامات الترقيم الصينية. لم تظهر في الجولات كاملة الملف؛ وكانت في أربعة أو خمسة مواضع في اثنتين من الجولات الموجَّهة الثلاث.

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

فروق أصغر

• lang: غيّرتها الجولات كاملة الملف إلى zh-CN من تلقاء نفسها. استخدمت الجولات الموجَّهة zh-Hans، كما طُلب. كلاهما وسم لغة صالح؛ zh-Hans يسمّي الكتابة (الصينية المبسطة)، وzh-CN يسمّي منطقة. توصي إرشادات W3C حول إعلانات اللغة بإعلان اللغة على عنصر <html> وليس بوسم Content-Language الوصفي.
• JSON-LD: ترجمت الجولات كاملة الملف والموجَّهة قيم name وdescription وأبقت JSON صالحاً. تخطّى نصنا البرمجي محتوى <script>، فبقيت بياناته المهيكلة بالإنجليزية، وهو سلوك أي أداة تتجاهل النصوص البرمجية.
• مراجع الأحرف: أبقت الجولات كاملة الملف والموجَّهة › و  و© ومرجع الرمز التعبيري كما كُتبت. أعادت خمس من تلك الجولات الست كتابة النطاق 2–5 بكلمات صينية (2 到 5 أو 2 至 5)؛ كتبت جولة موجَّهة واحدة شرطة عادية بدلاً من المرجع، رغم أن تعليماتها قالت بإبقاء المراجع. فكّك نصنا البرمجي جميعها وكتب الأحرف مرة أخرى، وهو ما يعرض الشيء نفسه. المرجع المهم، <library> داخل <code>، بقي مهرَّباً في الجولات التسع كلها.

قبل أن تترجم: جهّز الملف

1. حدّد ما يجب ألا يتغير. ضع translate="no" على أسماء المنتجات، وأرقام الطرازات، والسلاسل الشبيهة بالكود في النثر، وأي شيء آخر يجب أن يبقى كما هو. إنه جزء من HTML، ولا يكلّف شيئاً، وقد احترمه النموذج في الجولات الست كلها التي أُرسل إليها الملف كاملاً. أدوات التقسيم التي تقرأه، مثل نصنا البرمجي، تتخطى تلك العناصر كلياً. يغطي دليلنا لما لا يُترجم كيفية تحديد ما يوضع في تلك القائمة.
2. حدّد سياسة الكود. هل تُترجم تعليقات الكود؟ هل يُترجم ناتج العينة؟ هل ورقة الأنماط مشتركة بين اللغات؟ اكتب الإجابة، مع الأسماء التي يجب ألا تتغير، في مسرد ترجمة، وأعطها لمن أو لما يترجم.
3. أبقِ المعرّفات بلغة المصدر. تشير الروابط داخل الصفحة إلى قيم id. إذا ترجم أحدهم id، انكسر كل رابط إليه. لم تفعل أي من جولاتنا ذلك، لكن المترجم الذي "يساعد" بتعريب المراسي سيفعل.
4. اجمع النص المخفي. اسرد السمات التي تحمل كلمات، alt وtitle وplaceholder وaria-label وvalue على الأزرار، ووسوم meta، وJSON-LD، حتى تُفحص ولا تُنسى.
5. لا تترجم سلاسل JavaScript في مكانها. تحتاج الرسائل التي يضبطها نص برمجي، مثل تنبيه أو تسمية زر تُنشأ في الكود، إلى خطوة تعريب منفصلة في الكود. لم تغيّر أي من الجولات الست كاملة الملف أو الموجَّهة كتلة النص البرمجي لدينا، وهو صحيح، لكنه يعني أن تلك السلاسل تبقى بالإنجليزية.

بعد أن تترجم: افحصه

1. شغّل الفحص الهيكلي.

   python3 check_html_translation.py source.html translated.html --lang zh-Hans --keep Shelfmark
   

   يقارن الوسوم وترتيبها، وكل سمة ليست نصاً موجهاً للقارئ، ومحتويات <pre> و<script> و<style>، والكود المضمّن، ومفاتيح JSON-LD، ونص translate="no"، والتعليقات، والروابط داخل الصفحة. يحذّر من سمات نصية لا تزال بالإنجليزية، وقيمة lang تختلف عما تتوقعه، ونص مرئي يبدو غير مترجم، وكود مضمّن تغيّر ترتيبه، ومسافات بين نص صيني أو ياباني أو كوري عبر وسم مضمّن. لا يحكم على جودة الترجمة.

2. اقرأ كل جملة تحتوي على وسم مضمّن. هنا انكسر المعنى في اختبارنا. لا تعتمد على تحذير الفاحص "أُعيد ترتيب الكود المضمّن" للعثور على هذه الجمل: في اختبارنا، كانت الترجمات الخاطئة هي التي أبقت الترتيب الأصلي.

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

4. للغات من اليمين إلى اليسار، اضبط أيضاً dir="rtl" على عنصر <html>. يغطي دليل ترجمة الكتب من اليمين إلى اليسار ما يتغير أيضاً.

5. لـ XHTML، مثل ملفات الفصول داخل EPUB، تأكد أيضاً أن الملف لا يزال XML سليم البنية، مثلاً بـ xmllint --noout chapter.xhtml. يغفر المتصفح وسمًا غير مغلق؛ وقد لا يفعل قارئ الكتب الإلكترونية. تغطي قائمة فحص جودة ترجمة EPUB بقية الكتاب الإلكتروني.

أين يقع BookTranslator من هذا

تقبل صفحة الرفع في BookTranslator ملفات .html و.htm و.xhtml إلى جانب الكتب والمستندات، لذا يمكنك رفع صفحة محفوظة أو مقالة مساعدة ثابتة كملف كامل. لم نُجرِّب هذا النموذج عبر BookTranslator لهذا المقال، ولم نختبر كيفية تعامله مع ترتيب الشيفرة المضمّنة أو محتوى CSS أو JSON-LD، لذا تحقق من مخرجاته بالطريقة نفسها التي تتحقق بها من أي أداة أخرى. ترى السعر قبل أن تدفع.

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

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

كل ما في هذا الاختبار متاح لإعادة الاستخدام مجانًا:

• sample-source.html: النموذج الإنجليزي المكوّن من 59 سطرًا؛
• check_html_translation.py: أداة فحص البنية (مكتبة Python القياسية فقط)؛
• run_llm_html_test.py: الطرق الثلاث، لأي خادم محلي متوافق مع OpenAI؛
• المخرجات التسعة في مجلد المخرجات، مع check-results.txt وresults.csv.