چگونه مستندات فنی را بدون خراب کردن کد ترجمه کنیم

OpenL Team Oct 13, 2025
چگونه مستندات فنی را بدون خراب کردن کد ترجمه کنیم

TABLE OF CONTENTS

مستندات فنی بی‌رحم هستند: یک حصار کد شکسته، جای‌نگهدار یا لنگر می‌تواند ساخت‌ها را خراب کند، خوانندگان را گیج کند یا باعث شکست‌های کپی‑پیست شود. این راهنما به شما یک جریان کاری قابل تکرار و ایمن برای ترجمه مستندات فنی با اطمینان می‌دهد—در حالی که کد را دست‌نخورده و مستندات را قابل انتشار نگه می‌دارد.

این برای چه کسانی است: نویسندگان فنی، مدافعان توسعه‌دهنده و مترجمان که بر روی مستندات توسعه‌دهنده، راهنماهای API و محتوای سبک README کار می‌کنند.

به‌طور خلاصه:

  • درک کنید چه چیزی هرگز نباید ترجمه شود (کد، کلیدها، توکن‌ها)
  • حفظ نحوی که ابزارها تجزیه می‌کنند (حصارها، آکولادها، لنگرها)
  • اعتبارسنجی داده‌های ساختاریافته و لینک‌ها پس از ویرایش‌ها
  • استفاده از اتوماسیون برای شناسایی مشکلات قبل از انتشار

آماده‌سازی پیش از ترجمه

  1. موجودی انواع محتوا
  • Markdown (سرفصل‌ها، لینک‌ها، جداول)، بلوک‌های کد، کد درون‌خطی
  • داده‌های ساختاریافته: قطعات JSON/YAML/TOML و فایل‌های پیکربندی
  • اسکرین‌شات‌ها، نمودارها و تصاویر جاسازی‌شده
  1. تعریف توکن‌های غیرقابل ترجمه
  • مسیرهای فایل، نام‌های بسته، واردات، نام‌های API، پرچم‌های CLI، متغیرهای محیطی
  • جای‌نگهدارها و متغیرها: {count}, %s, $HOME, {{token}}
  • نام فایل‌ها و پسوندها: config.yaml, .env, .md, .json
  1. ایجاد ریل‌های محافظتی برای سازگاری
  • واژه‌نامه/پایگاه اصطلاحات برای اصطلاحات حوزه و نام‌های محصول
  • راهنمای سبک: لحن، رسمی بودن، نقطه‌گذاری، حروف بزرگ، قوانین سرفصل
  • استراتژی لنگر/اسلاگ برای هر محل (پایدار در مقابل محلی‌سازی‌شده)
  1. راه‌اندازی اعتبارسنجی ایمن
  • ساخت مرحله‌ای برای اعتبارسنجی Markdown/لینک‌ها پس از هر دسته
  • تجزیه‌کننده‌ها/لینترها برای JSON/YAML/TOML
  • بررسی‌کننده لینک و اعتبارسنج لنگر در CI

محافظ‌های اصلی

  • کد، شناسه‌ها، کلیدها، نام فایل‌ها، متغیرهای محیطی یا پرچم‌ها را ترجمه نکنید.
  • نقطه‌گذاری و نحوی که ابزارها تجزیه می‌کنند را حفظ کنید (بک‌تیک‌ها، آکولادها، لوله‌ها).
  • فضای سفید مهم را حفظ کنید: تورفتگی برای ساختار کد و لیست.
  • از بلوک‌های کد حصارکشیده با برچسب زبان به‌طور مداوم استفاده کنید (js, bash, etc.).
  • 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:

// SAFE: Only the comment is localized
// Obtains a user token
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSAFE: Do not translate identifiers/imports/package names
// import { obtenirJeton } from "@acme/sdk"; // ❌

Inline code must stay verbatim:

  • Good: “Run npm install -g acme-cli and then acme login.”
  • Bad: “Run npm install -g acme-cli and then acme 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.

# Do not alter tokens or spacing
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ adds spaces inside braces

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.

Keep Markdown link syntax and resolve strategy consistent.

[Read the API guide](/api/getting-started)  
[See the config section](#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": "User Guide",
  "cta": "Get Started",
  "limits": { "max": 5, "unit": "requests/second" }
}
  • Keys like title, cta, limits, max must remain unchanged.
  • Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

note: >
  Lines are folded into a single paragraph.
  Keep indentation and markers intact.
  • 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., --DryRun vs --dry-run).
  • Maintain commands verbatim; add callouts if locale‑specific differences exist.
# Correct
kubectl get pods --namespace default

# Wrong (flag translated) ❌
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 را ترجمه نکنید.
  • برای جلوگیری از خطاهای 404، آدرس‌های اینترنتی را با استراتژی لنگر خود هماهنگ کنید.

جریان کار و اتوماسیون

  • از یک جریان کاری CAT/LLM استفاده کنید که کد اسپن‌ها و تگ‌ها را حفظ کند.
  • اصطلاحات را با یک واژه‌نامه و لیست عدم ترجمه قفل کنید.
  • قلاب‌های پیش‌تعهد را برای لیند کردن Markdown و اعتبارسنجی JSON/YAML اضافه کنید.
  • یک بررسی‌کننده لینک و اعتبارسنجی انکر را بر روی هر PR اجرا کنید.
  • تغییرات را در بخش‌های کوچک و قابل بررسی دسته‌بندی کنید و تفاوت‌ها را پیگیری کنید.

ابزار پیشنهادی (متناسب با استک خود تنظیم کنید):

  • لیندینگ Markdown و بررسی لینک در CI
  • مرحله تجزیه JSON/YAML برای گرفتن رگرسیون‌های نحوی
  • بسته‌های Regex برای اسکن جای‌نگاه‌ها و فرمت‌های عددی

QA و اعتبارسنجی

این بررسی‌ها را قبل از ادغام اجرا کنید:

  • سایت را بسازید تا مشکلات نحوی را بگیرید: pnpm build
  • بررسی‌های نوع/محتوا (مجموعه‌های محتوای Astro): pnpm astro check
  • پیش‌نمایش و تست کلیدی صفحات: pnpm preview
  • اعتبارسنجی نمونه‌های کد کامپایل یا اجرا (در صورت امکان)
  • یک بررسی‌کننده لینک و انکر اجرا کنید؛ هر 404 یا هش شکسته را اصلاح کنید

مشکلات رایج

  • ترجمه کلیدها/جای‌نگاه‌ها به‌طور تصادفی.
  • شکستن حصارهای کد یا لوله‌های جدول.
  • بومی‌سازی مسیرهای فایل، پرچم‌ها، یا نام‌های API.
  • تغییر عناوین بدون به‌روزرسانی لینک‌های انکر.
  • معرفی نقل‌قول‌های هوشمند داخل کد یا JSON.

پیوست: چک‌لیست‌های سریع

پیش‌پرواز (5 مورد)

  • واژه‌نامه و لیست عدم ترجمه آماده
  • توکن‌ها/جای‌نگاه‌ها تعریف و محافظت شده
  • استراتژی انکر/اسلاگ تأیید شده
  • اهداف لینک نقشه‌برداری شده (داخلی در مقابل خارجی)
  • ساخت مرحله‌ای موجود

ایمنی نمونه کد (5 مورد)

  • حصارها و راهنمای زبان دست‌نخورده
  • شناسه‌ها/واردات دست‌نخورده؛ فقط نظرات بومی‌سازی شده
  • جای‌نگاه‌ها و نقل‌قول‌ها حفظ شده
  • تست کپی-پیست پاس شده
  • قطعات قدیمی به نگهدارندگان علامت‌گذاری شده

داده‌های ساختاریافته (5 مورد)

  • کلیدها و نوع‌ها دست‌نخورده
  • نقل‌قول‌ها/فرارها/تورفتگی حفظ شده
  • اعداد و بولی‌ها به عنوان نوع‌ها باقی می‌مانند
  • تجزیه‌کننده/لیندر محلی پاس شده
  • تفاوت‌ها برای تغییرات کلید تصادفی بررسی شده

مطالعه مرتبط