ترجمة المستندات الفنية هي الأكثر خوفًا من ترجمة الكود: استخدم Beautiful Soup لحماية كتل التعليمات البرمجية

في ترجمة المستندات الفنية، تعد ترجمة user_id إلى "معرف المستخدم" أو تغيير سمة الفئة في <div class="container"> أمرًا مكلفًا ويصعب استكشاف الأخطاء وإصلاحها. لن يؤدي هذا النوع من الأخطاء عادةً إلى تعطل البرنامج، ولكنه قد يتسبب في قيام التعليمات البرمجية المنسوخة والملصقة بالإبلاغ عن خطأ مباشرةً، أو جعل الأمثلة الموجودة في وثائق واجهة برمجة التطبيقات (API) غير صالحة.

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

كيف تحمي الكود عند ترجمة المستندات الفنية؟ استنتاج جملة واحدة

استخدم Beautiful Soup لتحديد عقد التعليمات البرمجية في شجرة DOM، وقم أولاً بإخفائها أو تجريدها، ثم أرسل فقرات اللغة الطبيعية فقط للترجمة، واستخدم التحقق التلقائي والمراجعة اليدوية كمعايير للتسليم.

##لماذا لا تكفي التعبيرات العادية لحماية التعليمات البرمجية

ستحاول العديد من الفرق استبدال مقتطفات التعليمات البرمجية بالتعبيرات العادية قبل الترجمة، ولكن هذا النهج هش في بنية HTML. HTML ليس نصًا خطيًا، ولكنه بنية شجرة متداخلة. قد تحتوي علامة <code> على تمييز <span>، أو قد يتم تغليفها بواسطة علامة <a> لتكوين رابط. لا تستطيع التعبيرات العادية فهم علاقة التداخل هذه، مما قد يتسبب بسهولة في حدوث أخطاء في إغلاق التسمية أو تفويت شروط الحدود.

باستخدام المحللين اللغويين مثل Beautiful Soup، يمكنك ترقية حماية التعليمات البرمجية من "مطابقة السلسلة" إلى "اجتياز العقدة". وفقًا لـ حساء جميل 4.15.0 الوثائق الرسمية، يمكن للبرامج التعامل مباشرة مع كائنات العلامة في شجرة DOM دون الحاجة إلى البحث عن أنماط أحرف محددة. من خلال تحديد العلامات الدلالية مثل pre، code، kbd، samp، والعناصر ذات الفئات مثل highlight، language-python، وما إلى ذلك، يمكن استهداف المنطقة التي تحتاج إلى الحماية بدقة، بغض النظر عن مدى تعقيد بنيتها الداخلية.

مثال تركيبي: الإخراج الصحيح ومصيدة الحدود

من أجل التحقق من منطق الحماية، يجب إنشاء مجموعة واضحة من حالات الاختبار الاصطناعية. يتم استخدام الإدخال التالي فقط لتوضيح منطق التحليل. إنها ليست بيانات إنتاج حقيقية ولا تتضمن أي قراءة خارجية للملفات.

إدخال HTML الاصطناعي:

<p>请运行 <code class="cmd">pip install -r requirements.txt</code> 来安装依赖。</p>
<pre><code># 初始化配置
config = {"timeout": 30}</code></pre>
<p>注意：<var>timeout</var> 参数单位为秒。</p>

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

1. "الرجاء تشغيل [CODE_0] لتثبيت التبعيات."
2. "ملاحظة: وحدة المعلمة [VAR_0] هي ثوانٍ."

يجب ألا يظهر المحتوى الموجود داخل كتلة <pre> في تدفق النص المراد ترجمته، أو أن يتم تصديره مع عدم تغيير البايتات الأصلية.

الأخطاء النموذجية ومعالجة الحدود:

• العلامات المتداخلة: في <code><b>bold_code</b></code>، إذا قمت باستخراج code.string فقط، فلن تحصل على أي شيء، لأن المحتوى موجود في العقدة الفرعية b. يجب استخدام get_text() أو الاجتياز العودي للأحفاد.
• تسريب قيمة السمة: هدف ترجمة <a href="/api/v1/users">用户接口</a> هو "واجهة المستخدم" فقط، ويجب قفل قيمة السمة href. إذا تم تحويل العلامة بأكملها إلى سلسلة وإرسالها للترجمة، فقد يكون عنوان URL تالفًا.
• علامة الكود الكاذب: <div class="code-snippet"> ليست علامة دلالية قياسية ويجب التقاطها بشكل إضافي من خلال القائمة البيضاء لأسماء فئة CSS، وإلا فسيتم التعامل معها على أنها ترجمة فقرة عادية.

تنفيذ تعريف عقدة الكود بناءً على شجرة DOM

يوضح مثال Python التالي كيفية استخدام Beautiful Soup لاجتياز شجرة المستندات والتمييز بين النص القابل للترجمة والتعليمات البرمجية المحمية. يعد هذا البرنامج النصي عرضًا تعليميًا لعمليات الذاكرة الخالصة ولا يحتوي على طلبات الشبكة أو أوامر Shell أو كتابة الملفات. يوصى بتشغيله في بيئة beautifulsoup4>=4.15.0.

from bs4 import BeautifulSoup, NavigableString, Tag

# 合成示例：包含内联代码、代码块及普通文本（仅用于演示，非真实数据）
HTML_SAMPLE = """
<article>
  <p>使用 <code class="cli">kubectl get pods</code> 查看状态。</p>
  <pre><code>def hello():
    print("Hello World")</code></pre>
  <p>返回值 <var>result</var> 可能为空。</p>
</article>
"""

# 定义需要整体保护的标签集合
PROTECTED_TAGS = {'pre', 'code', 'kbd', 'samp', 'var'}

def extract_translatable_segments(html_content: str) -> list[dict]:
    """
    提取HTML中的文本片段并标记是否可翻译。
    注意：此为教学演示代码，生产环境需增加占位符生成与属性保护逻辑。
    """
    soup = BeautifulSoup(html_content, 'html.parser')
    segments = []

    # 遍历所有文本节点，而非仅顶层标签
    for element in soup.descendants:
        if isinstance(element, NavigableString):
            # 检查父链上是否存在受保护标签
            parent_chain = list(element.parents)
            is_protected = any(
                p.name in PROTECTED_TAGS 
                for p in parent_chain 
                if isinstance(p, Tag)
            )

            text = str(element).strip()
            if not text:
                continue

            segments.append({
                'text': text,
                'translatable': not is_protected,
                'context': element.parent.name if element.parent else 'root'
            })
    return segments

# 执行提取并断言预期行为
results = extract_translatable_segments(HTML_SAMPLE)
translatable_texts = [s['text'] for s in results if s['translatable']]
protected_texts = [s['text'] for s in results if not s['translatable']]

# 验证：普通文本应被标记为可翻译
assert any('查看状态' in t for t in translatable_texts), "普通文本未被识别"
# 验证：代码内容不应出现在可翻译列表中
assert not any('kubectl' in t for t in translatable_texts), "内联代码泄露至翻译区"
assert not any('print' in t for t in translatable_texts), "代码块内容泄露至翻译区"
# 验证：受保护内容被正确归类
assert any('kubectl' in t for t in protected_texts), "内联代码未被保护"

print(f"可翻译片段数: {len(translatable_texts)}")
print(f"受保护片段数: {len(protected_texts)}")

مفتاح هذا الرمز هو التحقق من السلسلة لـ element.parents. حتى إذا كان <code> متداخلاً داخل <p>، فسيتم وضع علامة بشكل صحيح على العقد النصية الموجودة بداخله على أنها غير قابلة للترجمة. تجدر الإشارة إلى أن هذا مجرد عرض محيطي للاستخراج والتحقق، وليس نظامًا كاملاً لاستبدال الترجمة. في الإنتاج الفعلي، يجب أيضًا معالجة تعبئة العناصر النائبة وحماية السمات.

معايير القبول وحدود المراجعة اليدوية

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

غير قابل للتطبيق: ينطبق التحقق الآلي أعلاه فقط على HTML الدلالي جيد التنظيم. بالنسبة إلى كتل التعليمات البرمجية <div> + <span> النقية التي تم إنشاؤها بواسطة عرض Markdown والتي تفتقر إلى العلامات الدلالية، أو أسطر HTML المفردة المبهمة والمضغوطة، قد لا يحدد المحلل اللغوي حدود التعليمات البرمجية بشكل صحيح. يجب تنسيق هذه المستندات وتنظيفها أولاً، أو تسليمها مباشرة للمعالجة اليدوية. بالإضافة إلى ذلك، يضمن هذا التحقق فقط "عدم ترجمة الكود" ولا يضمن جودة اللغة الطبيعية للترجمة.

قم بتطبيق قائمة المراجعة على المستند الفعلي

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

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

📊 المقارنة الأساسية

🎯 ما هي الطريقة المناسبة لك؟

###إذا كنت......

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

❓ الأسئلة الشائعة (الأسئلة الشائعة)

1. لماذا لا يمكنني استبدال التعليمات البرمجية بالتعبيرات العادية؟

HTML عبارة عن بنية شجرة متداخلة، ومن الصعب على التعبيرات العادية فهم العلاقة المتداخلة بين <code> و<span> و<a>، مما قد يتسبب بسهولة في حدوث أخطاء في إغلاق التسمية أو فقدان الحدود.

2. هل تحتاج التعليقات الموجودة في كتل التعليمات البرمجية إلى الترجمة؟

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

3. إذا لم يكن هناك خطأ عند تشغيل البرنامج النصي، فهل يعني ذلك أنه لا توجد مشكلة في حماية التعليمات البرمجية؟

لا أستطيع. من الضروري أيضًا مقارنة بنية DOM، والتحقق مما إذا كانت السمات الرئيسية قد تغيرت، والتحقق من عدد العناصر النائبة، وإجراء المراجعة اليدوية.

4. هل تنطبق هذه الطريقة على كافة المستندات؟

لا. بالنسبة إلى كتل التعليمات البرمجية div + span النقية التي تم إنشاؤها بواسطة عرض Markdown، أو HTML المضغوط من سطر واحد، قد لا يتمكن المحلل اللغوي من تحديد حدود التعليمات البرمجية بشكل صحيح، ويجب تنسيقه أولاً أو تسليمه للمعالجة اليدوية.

📝 ملخص

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

جربه الآن: قم بتحميل المستند لبدء الترجمة، مع الاحتفاظ بالتخطيط الأصلي