‏Paraglide JS: ترجمه‌ی اپ با کامپایلر به‌جای کتابخونه‌ی runtime

Paraglide JS یه ابزار i18n (یعنی چندزبانه کردن متن‌های اپ) هست که رویکردش «اول کامپایلر» هست. کتابخونه‌هایی مثل i18next موقع اجرای اپ، کلید پیام رو تو یه دیکشنری بزرگ پیدا می‌کنن. Paraglide این کارو قبل از ship شدن انجام می‌ده و هر پیام رو به یه تابع ESM تایپ‌دار تبدیل می‌کنه. با React، TanStack Start، SvelteKit، React Router، Astro، Vue، Solid و جاوااسکریپت خالی کار می‌کنه و ادغام رسمی i18n تو SvelteKit هم همینه.

چون هر پیام یه تابع جداست، باندلرهایی مثل Vite و Rollup می‌تونن با tree-shaking (یعنی حذف کدی که هیچ‌جا import نشده) ترجمه‌های بی‌استفاده رو دور بریزن. طبق بنچمارک خود پروژه، با ۵ زبان و ۲۰۰ پیام، Paraglide حدود ۴۷ کیلوبایت تحویل داده و i18next حدود ۲۰۵ کیلوبایت. وقتی تعداد کل پیام‌ها به ۱۰۰۰ رسیده، Paraglide همون ۴۷ کیلوبایت مونده ولی i18next به ۴۱۴ کیلوبایت رسیده.

استفاده‌ش ساده‌ست: پیام‌ها رو از فایل تولیدشده import می‌کنی و صداشون می‌زنی. Provider یا context لازم نیست و غلط تایپی تو اسم کلید، خطای کامپایل می‌ده:

import { m } from "./paraglide/messages.js";
import { setLocale, getLocale } from "./paraglide/runtime.js";

m.greeting({ name: "Ada" });
getLocale(); // "en"
setLocale("de"); // loads the German document

به‌طور پیش‌فرض setLocale() یه ناوبری کامل انجام می‌ده، یعنی یا به URL زبان جدید می‌ره یا صفحه رو دوباره لود می‌کنه. برای SSR هم یه middleware داره که زبان هر درخواست رو تشخیص می‌ده و با AsyncLocalStorage نگهش می‌داره. این یعنی تو درخواست‌های هم‌زمان، هر کاربر زبان درست خودشو می‌گیره. برای مسیریابی هم توابع localizeUrl() و deLocalizeUrl() آدرس‌هایی مثل /de/ueber رو به route اصلی /about وصل می‌کنن و برعکس.

فرمت پیام‌ها پلاگینیه: می‌شه از ICU MessageFormat، فایل‌های i18next، JSON یا XLIFF استفاده کرد. جمع بستن، فرمت عدد و تاریخ هم با APIهای Intl انجام می‌شه. ولی یه محدودیت مهم داره: Paraglide وقتی بهترین کارو می‌کنه که کلیدها موقع بیلد معلوم باشن. اگه بیشتر ترجمه‌ها از CMS و موقع اجرا میان، به گفته‌ی خود مستندات احتمالاً یه کتابخونه‌ی runtime مناسب‌تره.

نکات کلیدی:

• پکیج @inlang/paraglide-js روی نسخه ۲ و با لایسنس MIT هست و آداپتورهایی مثل @inlang/paraglide-js-react روی نسخه ۱ هستن.
• با ۵ زبان و ۲۰۰ پیام، باندل Paraglide حدود ۴۷ کیلوبایت و i18next حدود ۲۰۵ کیلوبایت بوده.
• گزینه‌ی emitTsDeclarations به TypeScript نسخه ۵.۶ یا بالاتر نیاز داره.
• برای مهاجرت از i18next می‌شه فایل‌های ترجمه‌ی قبلی رو با پلاگین i18next نگه داشت.
• اگه کلیدهای پیام فقط موقع اجرا معلوم بشن، tree-shaking و تایپ‌سیفی از دست می‌ره.