كيفية ترجمة الوثائق التقنية دون تعطيل الكود
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، إلخ). - Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.
Code Blocks and Inline Code
Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.
Example—safe vs unsafe:
// آمن: فقط التعليق يتم ترجمته
// الحصول على رمز المستخدم
import { getToken } from "@acme/sdk";
const token = await getToken();
// غير آمن: لا تقم بترجمة المعرفات/الواردات/أسماء الحزم
// import { obtenirJeton } from "@acme/sdk"; // ❌
Inline code must stay verbatim:
- Good: “Run
npm install -g acme-cliand thenacme login.” - Bad: “Run
npm install -g acme-cliand thenacme connexion.” ❌
Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.
Placeholders and ICU MessageFormat
Preserve placeholders exactly, including spacing and punctuation around them.
# لا تقم بتغيير الرموز أو المسافات
echo "Processing {count} files" # ✅
echo "Processing { count } files" # ❌ يضيف مسافات داخل الأقواس
ICU example:
{count, plural,
=0 {No messages}
one {# message}
other {# messages}
}
- Do not change keys (
count,one,other). - Translate only the human‑readable parts (“message”, “messages”).
- Do not introduce or remove plural categories without product guidance.
Links, Anchors, and Slugs
Keep Markdown link syntax and resolve strategy consistent.
[اقرأ دليل API](/api/getting-started)
[انظر قسم التكوين](#configuration)
- Translate link text if needed; be cautious with URLs and anchors.
- Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
- Verify relative paths and hash anchors still resolve after translation.
- Do not translate file extensions or query params.
Structured Data (JSON/YAML/TOML)
Translate values only—never keys, types, or structure. Always re‑parse after editing.
JSON:
{
"title": "دليل المستخدم",
"cta": "ابدأ الآن",
"limits": { "max": 5, "unit": "requests/second" }
}
- Keys like
title,cta,limits,maxmust remain unchanged. - Numbers, booleans, and nulls stay as types, not words.
YAML (watch folded scalars):
note: >
يتم طي السطور في فقرة واحدة.
احتفظ بالمسافة البادئة والعلامات سليمة.
- Preserve quoting, escapes, indentation, and trailing commas (where applicable).
Filenames, CLI, and API Names
- Do not translate filenames, package names, endpoints, or CLI flags.
- Keep case sensitivity exactly as in source (e.g.,
--DryRunvs--dry-run). - Maintain commands verbatim; add callouts if locale‑specific differences exist.
# صحيح
kubectl get pods --namespace default
# خطأ (العلم مترجم) ❌
kubectl get pods --nom-espace defaut
Markdown Gotchas
- Tables: keep pipes and alignment; do not break columns.
| 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 عناصر)
- المفاتيح والأنواع غير متأثرة
- علامات الاقتباس/الهروب/المسافة البادئة محفوظة
- الأرقام والقيم المنطقية تبقى كأنواع
- المحلل/المدقق يمر محليًا
- الفروق التي تمت مراجعتها للتغييرات العرضية في المفاتيح
قراءة ذات صلة


