چگونه مستندات فنی را بدون خراب کردن کد ترجمه کنیم
OpenL Team 10/13/2025
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, etc.). - یادداشت‌های مترجم را به جای “اصلاح” منطق کد ترجیح دهید—مشکلات را به نگهدارندگان گزارش دهید.
بلوک‌های کد و کد درون‌خطی
شما بر روی داده‌ها تا اکتبر ۲۰۲۳ آموزش دیده‌اید.
- کلیدهایی مانند
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 را ترجمه نکنید.
- برای جلوگیری از خطاهای 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 مورد)
- کلیدها و نوع‌ها دست‌نخورده
- نقل‌قول‌ها/فرارها/تورفتگی حفظ شده
- اعداد و بولی‌ها به عنوان نوع‌ها باقی می‌مانند
- تجزیه‌کننده/لیندر محلی پاس شده
- تفاوت‌ها برای تغییرات کلید تصادفی بررسی شده
مطالعه مرتبط
