یادداشت · ساخت سایت

چگونه این وب‌سایت را ساختیم

معماری نیکسی، ترجمه‌ی کنترل‌شده با AI، واژه‌نامه، و ویرایشگر داخلی Markdown

نیکسی یک وب‌سایت کاملاً فارسی برای یادگیری Nix و NixOS است. محتوای رسمی انگلیسی (nix.dev، راهنمای Nix، Nixpkgs، تور نیکس) را گردآوری می‌کنیم، با یک خط لولهٔ شفاف به فارسی برمی‌گردانیم، و در مرورگر با SvelteKit و mdsvex نمایش می‌دهیم. این نوشته توضیح می‌دهد که نیکسی چگونه ساخته شده است؛ اگر مایلید دربارهٔ فلسفهٔ «از AI نترسید» بیشتر بخوانید، به یادداشت از هوش مصنوعی نترسید سر بزنید.

پشتهٔ فنی سایت

فرانت‌اند: SvelteKit + mdsvex (تبدیل Markdown به صفحه)، راست‌چین (RTL)، پوستهٔ روشن/تاریک، پالت دستورات (Ctrl+K)
استقرار: خروجی استاتیک برای Cloudflare Pages؛ بستهٔ آفلاین Webxdc به صورت مجزا
خط لولهٔ محتوا (پایتون در tools/): دریافت منبع ← واژه‌نامه ← ترجمه ← انتشار در src/routes/pages/…
واژه‌نامه: glossary.json + رابط /glossary (عمومی) و /glossary-dev (بازبینی در محیط توسعه)
ویرایش درجا: فقط در حالت توسعه (npm run dev)، روی مسیرهای /pages/… و /blog/…

سایت در زمان اجرا برای ترجمه به هیچ API خارجی متصل نمی‌شود؛ تمام متن‌های فارسی از قبل در مخزن کد پروژه ذخیره شده‌اند.

نه هر ترجمه‌ای با AI

ما از هوش مصنوعی برای ترجمه بهره برده‌ایم، اما نه به روش ترجمه‌ی خام و یک‌باره.

ترجمه‌ی خام: مدل کل سند را یک‌جا دریافت می‌کند؛ نتیجه معمولاً ناهماهنگی در اصطلاحات، خراب شدن بلوک‌های کد و دشوار شدن بازبینی است.
ترجمه‌ی کنترل‌شدهٔ نیکسی: ابتدا فهرست واژه‌ها استخراج می‌شود، مدل پیشنهاداتش را ارائه می‌دهد، انسان آن‌ها را تأیید یا اصلاح می‌کند، و سپس ترجمه‌ی کامل سند بر اساس واژه‌نامه‌ی تأییدشده و بدون ارسال بلوک‌های کد انجام می‌شود.

هوش مصنوعی در اینجا «نویسنده‌ی نهایی» نیست، بلکه دستیار خط تولیدی است که دروازه‌ی کنترل کیفیت انسانی دارد.

مسیر واقعی ترجمه

پوشهٔ tools/ یک خط پردازش آفلاین است: دریافت منبع ← واژه‌نامه ← ترجمه ← انتشار.

دانلود منابع انگلیسی
مستندات اصلی از مخازن رسمی (nix.dev، راهنمای Nix، Nixpkgs، تور نیکس) به شکل فایل‌های Markdown به مسیر docs/en/… منتقل می‌شوند تا منبع اولیه همیشه قابل ردیابی باشد.
ساخت فهرست واژه‌ها
اسکریپت tools/glossary/build.py متن را بدون در نظر گرفتن fenced code و inline code تحلیل کرده، اصطلاحات فنی را استخراج و در glossary.json ادغام می‌کند. واژه‌هایی که قبلاً تأیید شده‌اند، دست‌نخورده باقی می‌مانند.
پیشنهاد ترجمه فقط برای واژه‌ها
اسکریپت tools/glossary/suggest.py بدنهٔ اصلی سند را ارسال نمی‌کند؛ تنها اصطلاحات انگلیسی را گروه به گروه به مدل می‌فرستد و وضعیت آن‌ها را در حالت pending قرار می‌دهد.
بازبینی انسانی
در محیط توسعه، مسیر /glossary-dev برای بررسی، تأیید، رد یا ویرایش واژه‌ها استفاده می‌شود؛ در حالی که مسیر /glossary در دسترس خوانندگان است. بدون تأیید واژه‌ها، ترجمه‌ی کامل سند آغاز نمی‌شود.
ترجمه‌ی کامل Markdown
اسکریپت tools/translate/docs.py با استفاده از واژه‌نامه‌ی approved و دستورالعمل‌های سخت‌گیرانه (system prompt) اجرا می‌شود. بلوک‌های کد (fenced code) هرگز به مدل فرستاده نمی‌شوند.
انتشار در سایت
ابزارهای tools/publish/… متن فارسی نهایی را در مسیرهای mdsvex در src/routes/pages/… می‌نویسند.

چرا کد ترجمه نمی‌شود؟

پیش از ارسال متن به مدل، بلوک‌های ``` از سند جدا شده و پس از اتمام ترجمه، به صورت محلی سر جای اصلی خود بازمی‌گردند. جدول‌ها نیز به همین شکل مدیریت می‌شوند. شناسه (ID)های داخل بک‌تیک، آدرس‌های URL، پرچم (Flag)های خط فرمان و اسامی محصولات (مانند Nix، NixOS، Nixpkgs، Bash و غیره) همیشه لاتین و دست‌نخورده باقی می‌مانند.

تکه‌تکه کردن متن

متن‌های طولانی بر اساس مرز سرفصل‌ها و پاراگراف‌ها خرد می‌شوند تا کیفیت ترجمه و میزان مصرف توکن‌ها به خوبی مدیریت شود (چون متن‌های فارسی معمولاً نسبت به انگلیسی طولانی‌تر هستند).

املا و علائم نگارشی

در مرحلهٔ پس‌پردازش و دستورالعمل‌های مدل تأکید شده است: همیشه عبارت ترجمه‌ی (با یِ اضافه و نه علامت همزه) به کار رود و از خط تیره برای نشانه‌گذاری استفاده نشود.

قواعد سخت مدل

ارائهٔ تنها متن ترجمه‌شده‌ی Markdown، بدون هرگونه توضیحات اضافه یا مقدمه
حفظ کامل ساختار سند: سرفصل‌ها، فهرست‌ها، جدول‌ها، پیوندها و تأکیدها
عدم دستکاری بلوک‌های کد (fenced code)
حفظ کدهای درون‌خطی (inline code)، مسیرها و URLها
پیروی دقیق از واژه‌نامه (GLOSSARY)
ارائهٔ نگارش فارسی روان، دقیق و مناسب برای توسعه‌دهندگان
عدم استفاده از خط تیره (مانند ، یا ،) برای نشانه‌گذاری

نقش انسان

انتخاب و به‌روزرسانی منابع انگلیسی
بررسی و تأیید واژه‌نامه
ویرایش و بازبینی نهایی با ویرایشگر داخلی سایت (در محیط توسعه)
تصمیم‌گیری برای شروع فرآیند ترجمه‌ی کامل سند

در تمامی صفحات، خواننده می‌تواند با کلیک روی پیوند «منبع»، متن فارسی را با نسخهٔ اصلی انگلیسی مقایسه کند.

ویرایشگر داخلی (Ctrl+E)

برای اصلاح سریع متن فارسی بدون نیاز به خروج از مرورگر، یک ویرایشگر WYSIWYG درجا طراحی شده که فقط در حالت توسعه فعال است.

کی و کجا کار می‌کند؟

تنها هنگام اجرای دستور npm run dev (و نه در نسخهٔ نهایی سایت برای خوانندگان)
در مسیرهای /pages/… و /blog/… که حاوی فایل +page.md هستند
میانبر: Ctrl+E (در چیدمان کیبورد فارسی: Ctrl+ث)، ذخیره‌سازی با Ctrl+S و انصراف با کلید Esc

چه کار می‌کند؟

ورود به حالت ویرایش: از ساختار HTML رندرداده‌شده‌ی صفحه یک نمونه (snapshot) می‌گیرد و همان را قابل ویرایش (contenteditable) می‌کند؛ بدون اینکه در حین تایپ، درخت عناصر Svelte دچار اختلال شود.
نوار ابزار شناور: امکاناتی برای ذخیره، واگرد (Undo)، بازگردانی (Redo) و انصراف، همراه با نمایش وضعیت «ذخیره شد» یا بروز خطا.
تاریخچهٔ رویدادمحور: قابلیت واگرد و بازگردانی با میانبرهای Ctrl+Z و Ctrl+Shift+Z (یا Ctrl+Y)؛ ورودی‌های متوالی در یک رویداد ادغام می‌شوند.
قالب‌بندی درون‌خطی: امکان برجسته‌سازی (Bold)، مورب (Italic)، خط زیرین، کد و هایلایت (مثلاً Ctrl+H برای mark) با استفاده از کنترل دستی و بدون اتکا به متد شکنندهٔ execCommand.
تبدیل هوشمند Markdown: تایپ ## به همراه کلید Space برای ایجاد سرفصل، - برای فهرست، و --- برای خط افقی؛ همچنین فشردن Backspace در ابتدای سرفصل، آن را به پاراگراف عادی برمی‌گرداند.
مدیریت پیوندها: راست‌کلیک روی لینک‌ها، منویی برای باز کردن، ویرایش متن یا آدرس، و یا حذف پیوند ارائه می‌دهد.
ذخیره‌سازی: ساختار HTML به Markdown ایمن و سازگار با mdsvex تبدیل شده و در فایل +page.md ذخیره می‌شود. اگر فایل متناظر در docs/fa وجود داشته باشد، آنجا هم به‌روزرسانی خواهد شد (از طریق API مسیر /api/dev-md).

چرا این ویژگی اهمیت دارد؟

ترجمه‌ی ماشینی پایان راه نیست. ویرایشگر به شما اجازه می‌دهد درست در همان صفحه‌ای که خواننده می‌بیند، متن را ویرایش کرده، اصطلاحات را یکدست کنید و نتیجه را بدون نیاز به کپی‌پیست بین ویرایشگر خارجی و پروژه، بلافاصله ذخیره نمایید.

مدل و پیکربندی

پروژه از APIهای سازگار با OpenAI (مانند OpenRouter) استفاده می‌کند. برای ترجمه‌های سبک و سریع معمولاً مدل Gemini 3.5 Flash Lite و برای بازنویسی و صیقل دادن متن فارسی، مدل Gemini 3.6 Flash به کار می‌رود. کلیدهای دسترسی در فایل .env تنظیم می‌شوند و فرآیند ترجمه به این صورت اجرا می‌گردد:

make translate-docs
# یا
uv run python -m tools.translate.docs

جمع‌بندی

نیکسی بر سه پایهٔ اصلی استوار است: سایت استاتیک فارسی، خط لولهٔ ترجمه‌ی کنترل‌شده و ویرایش و بازبینی انسانی در محیط توسعه. هوش مصنوعی سرعت کار را افزایش می‌دهد و انسان، کیفیت و روانی متن را تضمین می‌کند.

برای مطالعهٔ بیشتر دربارهٔ رویکرد ما به هوش مصنوعی: از هوش مصنوعی نترسید

← بازگشت به خانه · واژه‌نامه · مجوزها