كيفية ترجمة الوثائق التقنية دون تعطيل الكود

TABLE OF CONTENTS

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

لمن هذا موجه: الكتاب الفنيون، المدافعون عن المطورين، والمترجمون الذين يعملون على وثائق المطورين، أدلة API، ومحتوى نمط README.

نظرة عامة:

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

التحضير قبل الترجمة

جرد أنواع المحتوى

Markdown (العناوين، الروابط، الجداول)، كتل الكود، الكود المضمن
البيانات المهيكلة: مقتطفات JSON/YAML/TOML وملفات التكوين
لقطات الشاشة، الرسوم البيانية، والمرئيات المدمجة

تعريف الرموز غير القابلة للترجمة

مسارات الملفات، أسماء الحزم، الواردات، أسماء API، أعلام CLI، متغيرات البيئة
العناصر النائبة والمتغيرات: {count}، %s، $HOME، {{token}}
أسماء الملفات والامتدادات: config.yaml، .env، .md، .json

إنشاء حواجز الاتساق

قاموس/قاعدة مصطلحات للمصطلحات المجال وأسماء المنتجات
دليل الأسلوب: النبرة، الرسمية، علامات الترقيم، الكتابة بالأحرف الكبيرة، قواعد العناوين
استراتيجية المراسي/الروابط لكل لغة (ثابتة مقابل محلية)

إعداد التحقق الآمن

بناء مرحلي للتحقق من Markdown/الروابط بعد كل دفعة
محللات/مدققات لـ JSON/YAML/TOML
مدقق الروابط ومرساة في CI

الضمانات الأساسية

لا تقم بترجمة الكود، المعرفات، المفاتيح، أسماء الملفات، متغيرات البيئة، أو الأعلام.
الحفاظ على علامات الترقيم والصياغة التي تقوم الأدوات بتحليلها (العلامات الخلفية، الأقواس، الأنابيب).
الحفاظ على المسافات البيضاء الهامة: المسافة البادئة للكود وهيكل القوائم.
استخدام كتل الكود المسورة مع علامة لغة بشكل متسق (js، bash، إلخ).
تفضيل ملاحظات المترجمين على “إصلاح” منطق الكود - الإشارة إلى المشاكل للصيانة بدلاً من ذلك.

كتل الكود والكود المضمن

أنت مدرب على البيانات حتى أكتوبر 2023.

حافظ على الأسوار البرمجية، تلميحات اللغة، والمحتوى كما هو. قم بترجمة التعليقات والسلاسل القابلة للقراءة البشرية فقط إذا لزم الأمر.

مثال—آمن مقابل غير آمن:

// آمن: فقط التعليق يتم ترجمته
// الحصول على رمز المستخدم
import { getToken } from "@acme/sdk";
const token = await getToken();

// غير آمن: لا تقم بترجمة المعرفات/الواردات/أسماء الحزم
// import { obtenirJeton } from "@acme/sdk"; // ❌

يجب أن تبقى الشيفرات المضمنة كما هي:

جيد: “قم بتشغيل npm install -g acme-cli ثم acme login.”
سيء: “قم بتشغيل npm install -g acme-cli ثم acme connexion.” ❌

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

النماذج النائبة وصيغة رسائل ICU

حافظ على النماذج النائبة تمامًا، بما في ذلك المسافات وعلامات الترقيم حولها.

# لا تقم بتغيير الرموز أو المسافات
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ يضيف مسافات داخل الأقواس

مثال ICU:

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

لا تقم بتغيير المفاتيح (count, one, other).
قم بترجمة الأجزاء القابلة للقراءة البشرية فقط (“message”، “messages”).
لا تقم بإدخال أو إزالة فئات الجمع دون توجيه المنتج.

الروابط، المراسي، والشرائح

حافظ على بناء جملة الروابط في Markdown واستراتيجية الحل متسقة.

[اقرأ دليل API](/api/getting-started)  
[انظر قسم التكوين](#configuration)

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

البيانات المنظمة (JSON/YAML/TOML)

قم بترجمة القيم فقط—لا تقم أبدًا بترجمة المفاتيح، الأنواع، أو البنية. دائمًا قم بإعادة التحليل بعد التحرير.

JSON:

{
  "title": "دليل المستخدم",
  "cta": "ابدأ الآن",
  "limits": { "max": 5, "unit": "requests/second" }
}

يجب أن تظل المفاتيح مثل title، cta، limits، max دون تغيير.
تبقى الأرقام، القيم المنطقية، والقيم الخالية كأنواع، وليس كلمات.

YAML (مشاهدة المتجهات المطوية):

note: >
  يتم طي السطور في فقرة واحدة.
  احتفظ بالمسافة البادئة والعلامات سليمة.

احتفظ بالاقتباسات، الهروب، المسافة البادئة، والفواصل اللاحقة (حيثما ينطبق).

أسماء الملفات، CLI، وأسماء API

لا تقم بترجمة أسماء الملفات، أسماء الحزم، النقاط النهائية، أو أعلام CLI.
احتفظ بحساسية الحالة كما هي في المصدر (مثل --DryRun مقابل --dry-run).
حافظ على الأوامر حرفياً؛ أضف تنبيهات إذا كانت هناك اختلافات خاصة بالمنطقة.

# صحيح
kubectl get pods --namespace default

# خطأ (العلم مترجم) ❌
kubectl get pods --nom-espace defaut

مفاجآت Markdown

الجداول: احتفظ بالأنابيب والمحاذاة؛ لا تكسر الأعمدة.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

التنبيهات/الملاحظات: احتفظ بالعلامات المستخدمة بواسطة أدواتك.
HTML المضمن: تجنب لمس العلامات/السمات.
الحواشي السفلية: احتفظ بالمعرفات والترتيب.
الاقتباسات الذكية: فضل الاقتباسات المستقيمة داخل سياقات الشيفرة.

المرئيات وإمكانية الوصول

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

SEO والبيانات الوصفية

ترجم العناوين، الأوصاف، والعناوين باستخدام الكلمات المفتاحية المناسبة للمنطقة.
احتفظ بعناوين URL الأساسية وhreflang متسقة مع قواعد الموقع.
لا تقم بترجمة مفاتيح الميتا/الخاصية أو مفاتيح JSON-LD.
قم بمحاذاة الأجزاء مع استراتيجيتك للروابط لتجنب 404s.

سير العمل والأتمتة

استخدم سير عمل CAT/LLM الذي يحافظ على نطاقات التعليمات البرمجية والعلامات.
قم بتثبيت المصطلحات باستخدام قائمة مصطلحات وقائمة عدم الترجمة.
أضف خطافات قبل الالتزام لتنقيح Markdown والتحقق من صحة JSON/YAML.
قم بتشغيل مدقق الروابط ومدقق المراسي على كل PR.
تجميع التغييرات في أجزاء صغيرة قابلة للمراجعة وتتبع الفروق.

الأدوات المقترحة (تكييفها مع حزمة الأدوات الخاصة بك):

تنقيح Markdown والتحقق من الروابط في CI
خطوة تحليل JSON/YAML لاكتشاف تراجع بناء الجملة
حزم Regex لمسح العناصر النائبة وتنسيقات الأرقام

ضمان الجودة والتحقق

قم بتشغيل هذه الفحوصات قبل الدمج:

بناء الموقع لاكتشاف مشاكل بناء الجملة: pnpm build
فحوصات النوع/المحتوى (مجموعات محتوى Astro): pnpm astro check
معاينة واختبار الصفحات الرئيسية: pnpm preview
التحقق من تجميع أو تشغيل عينات التعليمات البرمجية (حيثما ينطبق)
تشغيل مدقق الروابط والمراسي؛ إصلاح أي 404s أو تجزئات مكسورة

الأخطاء الشائعة

ترجمة المفاتيح/العناصر النائبة عن طريق الخطأ.
كسر أسوار التعليمات البرمجية أو أنابيب الجداول.
توطين مسارات الملفات أو الأعلام أو أسماء API.
تغيير العناوين دون تحديث روابط المراسي.
إدخال علامات الاقتباس الذكية داخل التعليمات البرمجية أو JSON.

الملحق: قوائم التحقق السريعة

التحقق المسبق (5 عناصر)

قائمة المصطلحات وقائمة عدم الترجمة جاهزة
الرموز/العناصر النائبة محددة ومحمية
استراتيجية المراسي/الشرائح مؤكدة
أهداف الروابط مرسومة (داخلية مقابل خارجية)
بناء مرحلة متاح

سلامة عينات التعليمات البرمجية (5 عناصر)

الأسوار وتلميحات اللغة سليمة
المعرفات/الاستيرادات غير متأثرة؛ التعليقات محلية فقط
العناصر النائبة وعلامات الاقتباس محفوظة
اختبار النسخ واللصق يمر
مقتطفات قديمة مميزة للمحافظين

البيانات المنظمة (5 عناصر)

المفاتيح والأنواع غير متأثرة
علامات الاقتباس/الهروب/المسافة البادئة محفوظة
الأرقام والقيم المنطقية تبقى كأنواع
المحلل/المدقق يمر محليًا
الفروق التي تمت مراجعتها للتغييرات العرضية في المفاتيح

قراءة ذات صلة