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

نیکسی یک وب‌سایت کاملاً فارسی برای یادگیری 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) هرگز به مدل فرستاده نمی‌شوند. بلافاصله پس از پاسخ مدل، همان مسیر apply_fa_orthography (ابرابزار) روی متن اعمال می‌شود.
املای فارسی با ابرابزار
روی کل docs/fa (و هر متن فارسی تازه‌ای) ابزار ابرابزار را اجرا می‌کنیم تا نویسه‌ها، نیم‌فاصله، و علائم یکدست شوند. جزئیات در بخش املا و ابرابزار.
انتشار در سایت
ابزارهای tools/publish/… متن فارسی نهایی را در مسیرهای mdsvex در src/routes/pages/… می‌نویسند.

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

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

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

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

املا و ابرابزار

متن فارسی فقط به مدل سپرده نمی‌شود؛ بعد از ترجمه (و در بازنویسی‌ها و پیشنهادهای واژه‌نامه) یک پس‌پردازش املایی اجرا می‌شود که از ابرابزار ویکی‌پدیای فارسی الهام گرفته و در همین مخزن به‌صورت پایتون پیاده شده‌است:

tools/lib/fa_bot.py: هسته‌ی persianTools (نویسه‌های استاندارد فارسی به‌جای عربی، نیم‌فاصله در «می‌…» ، «ها» ، ماضی نقلی، سجاوندی فارسی و …)
tools/lib/fa_orthography.py: همان منطق را روی Markdown اعمال می‌کند؛ بلوک‌های کد، کد درون‌خطی، URL و مقصد پیوندها دست‌نخورده می‌مانند
قواعد اختصاصی نیکسی روی همان لایه: همیشه ترجمه‌ی (ه + نیم‌فاصله + ی، نه همزه‌ی اضافه) و حذف خط تیره‌های em/en از خروجی مدل
ارقام غربی در مستندات فنی عمداً به ارقام فارسی تبدیل نمی‌شوند

روی کل مجموعه‌ی فارسی می‌توان ابرابزار را جداگانه هم اجرا کرد:

uv run python -m tools.lib.fa_orthography
# یا فقط گزارش بدون نوشتن:
uv run python -m tools.lib.fa_orthography --dry-run -v docs/fa

این همان مرحله‌ای است که بعد از ترجمه‌ی دسته‌ای یا ویرایش انسانی، املا و علائم را با استاندارد نزدیک به ویرایشگر خودکار ویکی‌پدیا هم‌تراز می‌کند تا خواننده بداند فارسیِ سایت «خامِ مدل» نیست.

قواعد سخت مدل

ارائه‌ی تنها متن ترجمه‌شده‌ی 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

جمع‌بندی

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

برای مطالعه‌ی بیشتر درباره‌ی رویکرد ما به هوش مصنوعی، این نوشته را بخوانید:

از هوش مصنوعی نترسید فلسفه‌ی AI · کنترل انسانی · یادگیری بهتر بازگشت به خانه فهرست راهنماها و مستندات نیکسی