تحلیلها
ساخت یک پلتفرم Next.js در ۲۲ زبان: درسهایی از پروژه GAGA
مسیریابی بر اساس لوکیل، صربی لاتین و سیریلیک، قالببندی Intl، فونتها، بررسی ترجمهها در CI و نرخهای ارز بهروز: درسهایی از ساخت یک پلتفرم Next.js در ۲۲ زبان.
تیم مهندسی sigmacode.io10 دقیقه مطالعه
در این صفحه (11)
- به هر لوکیل URL مخصوص خودش را بدهید
- دو خط، یک زبان
- اعداد، ارزها و تاریخها را با Intl قالببندی کنید
- فونتها و پوشش گلیف
- یک گردشکار ترجمه که از ۲۲ زبان جان سالم به در میبرد
- داده بلادرنگ بدون مقادیر کهنه
- یک منبع حقیقت برای PDF، Excel، CSV و XML
- SEO در میان لوکیلهای بسیار
- دسترسپذیری
- تست: مسیرها × لوکیلها
- برای چه چیزهایی برنامهریزی کنید
GAGA Menjačnica یک صرافی و فروشنده فلزات گرانبها با چند شعبه در نوویساد، صربستان است. تیم ما پلتفرم آنها، menjacnicegaga.rs، را با Next.js و React روی Vercel ساخت. این پلتفرم در ۲۲ زبان کار میکند، از جمله صربی به هر دو خط لاتین و سیریلیک، آلمانی، چینی، روسی، ترکی، اوکراینی، یونانی و بلغاری. نرخهای خرید و فروش زنده را کنار نرخهای مرجع بانک ملی صربستان نشان میدهد و شامل یک مبدل ارز، فهرستهای نرخ قابلدانلود در پنج قالب، یابنده شعبه و راهنماهای طلا و نقره سرمایهگذاری است.
بیستودو زبان از نقطهای گذشته که بینالمللیسازی یک «فیچر» باشد. در این مقیاس، معماری را شکل میدهد. این مقاله آنچه را که به باور ما در ساخت چنین پلتفرمی مهم است پوشش میدهد و برای CTOها، مالکان محصول و مهندسان فرانتاندی نوشته شده که یکی را برنامهریزی میکنند. برای خود پروژه، مطالعه موردی GAGA را ببینید.
به هر لوکیل URL مخصوص خودش را بدهید#
مهمترین تصمیم اول میآید: هر نسخه زبانی هر صفحه به URL پایدار و قابلکراول مخصوص خودش نیاز دارد. زبان را با کوکی عوض نکنید یا با تشخیص Accept-Language. موتورهای جستوجو نمیتوانند آن را ایندکس کنند، کاربران نمیتوانند آن را به اشتراک بگذارند و CDNها نمیتوانند آن را تمیز کش کنند.
ما یک پیشوند لوکیل در مسیر را توصیه میکنیم، مانند /sr/...، /de/... و /zh/.... با App Router در Next.js، این یعنی یک سگمنت [locale] در ریشه اپلیکیشن. پراکسی درخواست (proxy.ts، که قبلاً middleware نامیده میشد) میتواند اولین بازدید را بر اساس زبان مرورگر به یک پیشفرض منطقی ریدایرکت کند. پس از آن، URL تنها منبع حقیقت است و یک زبانگردان باید به همان صفحه در لوکیل دیگر لینک دهد، نه به صفحه اصلی آن لوکیل.
شناسههای لوکیل را زود برنامهریزی کنید و در همهجا از تگهای BCP 47 استفاده کنید. صربی بهتنهایی به دو تای آن نیاز دارد: sr-Latn و sr-Cyrl. نگاشت آنها به سگمنتهای URL، مقادیر hreflang و لوکیلهای Intl در یک جا، بعداً از دردسر زیادی میکاهد.
hreflang، x-default و سایتمپها#
هر صفحه باید همه نسخههای جایگزینش را فهرست کند، از جمله خودش، و یک x-default برای کاربرانی که زبانشان را پشتیبانی نمیکنید اضافه کند. در App Router، API متادیتا این کار را برای شما انجام میدهد:
// app/[locale]/rates/page.tsx
import type { Metadata } from "next";
const BASE = "https://example.com";
const LOCALES = ["sr-Latn", "sr-Cyrl", "en", "de", "zh", "ru"] as const;
const segment = (l: string) => l.toLowerCase(); // "sr-Latn" -> "sr-latn"
export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }): Promise<Metadata> {
const { locale } = await params;
const path = "/rates";
const languages: Record<string, string> = Object.fromEntries(
LOCALES.map((l) => [l, `${BASE}/${segment(l)}${path}`])
);
languages["x-default"] = `${BASE}/en${path}`;
return {
alternates: { canonical: `${BASE}/${locale}${path}`, languages },
};
}
سایتمپ را از همان فهرست لوکیل و همان رجیستری مسیرها بسازید، با جایگزینهایی برای هر مدخل. وقتی تگهای hreflang و مدخلهای سایتمپ از مسیرهای کد جدا میآیند، سرانجام با هم ناسازگار میشوند و موتورهای جستوجو بیصدا دیگر به هیچیک اعتماد نمیکنند.
دو خط، یک زبان#
صربی به هر دو خط لاتین و سیریلیک نوشته میشود و بسیاری از خوانندگان ترجیح قوی دارند. آنها را دو لوکیل کامل در نظر بگیرید، نه یک لوکیل با یک کلید نمایش. هر کدام URL، مقدار hreflang و صفت lang مخصوص خود را میگیرند.
وسوسهانگیز است که همهچیز را به یک خط بنویسید و دیگری را بهطور خودکار تبدیل (transliterate) کنید. برای متن جاری، یک مرحله تبدیل خوشتستشده میتواند نقطه شروع منطقی باشد. اما آن را کورکورانه به همهچیز اعمال نکنید:
- اسامی خاص و برندها. نام شرکتها، نام محصولات و واژگان خارجی اغلب حتی در متن سیریلیک شکل لاتین خود را حفظ میکنند. یک مبدل مکانیکی «خیرخواهانه» آنها را به چیزی تبدیل میکند که هیچکس ننوشته است.
- ابهام دوحرفیها.
nj،ljوdžلاتین معمولاً به یک حرف سیریلیک نگاشت میشوند، اما نه همیشه. واژگان مرکب و وامواژههای خارجی قاعده را میشکنند. رفتن از سیریلیک به لاتین قطعی است؛ رفتن از لاتین به سیریلیک نه. - URLها، کدها و شناسهها. کدهای ارز مانند
EUR، آدرسهای ایمیل، اسلاگها و هر چیزی داخل placeholderهای درونیابی هرگز نباید تبدیل شوند. - جستوجو و مرتبسازی. کاربران ممکن است در یک صفحه سیریلیک لاتین تایپ کنند. پیش از مقایسه، هر دو طرف را نرمال کنید.
توصیه ما: مبدأ سیریلیک را ذخیره کنید (جهت قطعی)، یا دو کاتالوگ جدا نگه دارید، و یک فهرست استثنا کوچک داشته باشید که یک گوینده بومی مالک آن است. هر چیزی که یک ماشین تولید کرده باید پیش از عرضه بازبینی شود.
اعداد، ارزها و تاریخها را با Intl قالببندی کنید#
در یک سایت نرخ ارز، اعداد خود محصولاند. صربی از کاما بهعنوان جداکننده اعشاری استفاده میکند، آلمانی هزارگان را با نقطه گروهبندی میکند و کاربران چینی باز هم قراردادهای متفاوتی انتظار دارند. دستی قالببندی نکنید. از APIهای داخلی Intl استفاده کنید و تگ کامل لوکیل را بدهید:
const rateFormatter = (locale: string) =>
new Intl.NumberFormat(locale, {
minimumFractionDigits: 4,
maximumFractionDigits: 4,
});
const moneyFormatter = (locale: string, currency: string) =>
new Intl.NumberFormat(locale, { style: "currency", currency });
const asOf = (locale: string, date: Date) =>
new Intl.DateTimeFormat(locale, {
dateStyle: "long",
timeStyle: "short",
timeZone: "Europe/Belgrade",
}).format(date);
rateFormatter("sr-Latn").format(117.1234); // "117,1234"
rateFormatter("de").format(117.1234); // "117,1234"
moneyFormatter("en", "EUR").format(1250); // "€1,250.00"
asOf("sr-Cyrl", new Date()); // e.g. "18. септембар 2026. 10:30" (exact output depends on the ICU version)
چند نکته برای برنامهریزی. منطقه زمانی را صراحتاً تنظیم کنید. صفحات رندرشده روی سرور در غیر این صورت از منطقه سرور استفاده میکنند که معمولاً UTC است. قالببندها را یکبار بسازید و دوباره استفاده کنید، چون ساخت مکرر آنها در یک جدول بزرگ جمع میشود. و تعداد ارقام اعشاری را هم در لایه داده و هم در UI نگه دارید تا خروجیها و صفحه موافق باشند.
فونتها و پوشش گلیف#
بیستودو زبان یعنی لاتین، لاتین توسعهیافته (صربی، کرواتی، ترکی)، سیریلیک (صربی، روسی، اوکراینی، بلغاری)، یونانی و نویسههای CJK. تایپفیسهای برند کمی همه اینها را پوشش میدهند و آنهایی که پوشش میدهند بزرگاند.
آنچه مهم است:
- پوشش هر خط را پیش از انتخاب تایپفیس بررسی کنید. رشتههای واقعی را تست کنید، نه «Lorem ipsum». سیریلیک صربی حروف و فرمهای ایتالیک محلی خود را دارد، اوکراینی حروفی دارد که روسی ندارد، و بلغاری شکلهای گلیف خود را ترجیح میدهد.
- بر اساس خط سابست کنید و بر اساس لوکیل بارگذاری کنید.
next/fontاز سابستهایی مانندlatin،latin-ext،cyrillicوgreekپشتیبانی میکند. یک صفحه آلمانی نباید گلیفهای سیریلیک دانلود کند. - یک فونت CJK کامل را در هر صفحه self-host نکنید. فونتهای چینی میتوانند چند مگابایت باشند. یک پشته فونت سیستمی برای CJK، مانند
"PingFang SC", "Microsoft YaHei", "Noto Sans SC", sans-serif، اغلب مفاضله درست است. - یک پشته فالبک صریح طراحی کنید و فالبکهای سازگار از نظر متریک تنظیم کنید تا متن هنگام بارگذاری فونت وب جابهجا نشود.
یک گردشکار ترجمه که از ۲۲ زبان جان سالم به در میبرد#
با دو یا سه زبان، یک اسپردشیت و کمی نظم کافی است. با ۲۲، به یک پایپلاین نیاز دارید.
کاتالوگهای پیام با کلیدهای پایدار. برای هر لوکیل یک فایل JSON استفاده کنید، با کلیدهایی که بر اساس معنا نامگذاری شدهاند، مثل rates.table.buy، و هرگز بر اساس متن انگلیسی. برای جمعها و درونیابی از ICU MessageFormat استفاده کنید. قواعد جمع بسیار متفاوتاند: روسی، اوکراینی و صربی چند فرم دارند و چینی هیچکدام.
برابری کلیدها در CI. یک کلید گمشده در یک لوکیل رایجترین باگ در یک سایت چندزبانه است و آسانترین برای گرفتن خودکار:
// scripts/check-i18n.ts — run in CI, fail the build on drift
import { readdirSync, readFileSync } from "node:fs";
const dir = "messages";
const flatten = (o: Record<string, unknown>, p = ""): string[] =>
Object.entries(o).flatMap(([k, v]) =>
v && typeof v === "object" ? flatten(v as Record<string, unknown>, `${p}${k}.`) : [`${p}${k}`]
);
const load = (f: string) => new Set(flatten(JSON.parse(readFileSync(`${dir}/${f}`, "utf8"))));
const source = load("en.json");
let failed = false;
for (const file of readdirSync(dir).filter((f) => f.endsWith(".json") && f !== "en.json")) {
const keys = load(file);
const missing = [...source].filter((k) => !keys.has(k));
const extra = [...keys].filter((k) => !source.has(k));
if (missing.length || extra.length) {
failed = true;
console.error(`${file}: missing ${missing.length}, extra ${extra.length}`, { missing, extra });
}
}
process.exit(failed ? 1 : 0);
همان اسکریپت را گسترش دهید تا بررسی کند placeholderهای درونیابی بین لوکیلها مطابقاند. یک نام placeholder ترجمهشده در زمان اجرا میشکند، نه در زمان بیلد.
ترجمه با کمک هوش مصنوعی، با بازبینی انسانی. ترجمه ماشینی و LLM اکنون پیشنویسهای خوبی تولید میکنند و در ۲۲ زبان این اقتصاد را تغییر میدهد. اما یک صرافی با پول و اعتماد سروکار دارد. برچسبهای نرخ، اطلاعیههای حقوقی و راهنماهای سرمایهگذاری باید پیش از انتشار توسط یک انسان مسلط بازبینی شوند. به مترجمان کانتکست بدهید: اسکرینشاتها، محدودیتهای کاراکتر و یک واژهنامه از اصطلاحات ثابت مانند «نرخ خرید»، «نرخ فروش» و «نرخ مرجع».
داده بلادرنگ بدون مقادیر کهنه#
نرخهای ارز در طول روز تغییر میکنند. تله این است که آنها را به همان شدت بقیه یک سایت استاتیکمحور Next.js کش کنید.
راهبردهای کلی توصیهشده:
- پوسته را از داده جدا کنید. چیدمان صفحه، ترجمهها و راهنماها میتوانند استاتیک باشند یا بهندرت revalidate شوند. جدول نرخها باید پنجره revalidation کوتاه مخصوص خود را داشته باشد، یا روی کلاینت فچ یا استریم شود.
- revalidation را کوتاه و آگاهانه نگه دارید. پنجرهای انتخاب کنید که با دفعات واقعی تغییر نرخها مطابقت دارد و آن را مستند کنید. تا حد ممکن، هنگام انتشار نرخهای جدید از revalidation براساستقاضا استفاده کنید، نه فقط تکیه بر تایمر.
- در لبه با احتیاط کش کنید.
s-maxageکوتاه باstale-while-revalidateصفحات را سریع نگه میدارد، اما مطمئن شوید پنجره کهنگی یکی است که کسبوکار میتواند بپذیرد. - همیشه یک تایماستمپ «از تاریخ» نشان دهید، که برای هر لوکیل در منطقه زمانی شعبه قالببندی شده. این پاسخ صادقانه به سؤالی است که هر سیستم کش مطرح میکند: این چقدر تازه است؟
یک منبع حقیقت برای PDF، Excel، CSV و XML#
GAGA فهرست نرخهایش را برای دانلود بهصورت PDF، JPG، Excel، CSV و XML منتشر میکند. پنج قالب پنج فرصت برای ناسازگاری اعداد ایجاد میکند.
قاعده: هر خروجی را از همان ساختار داده نرمالشده بسازید، همان که جدول روی صفحه را رندر میکند. گرد کردن، ترتیب و متادیتای ارز را در آن ساختار بگذارید، نه در هر صادرکننده. هر قالب سپس یک سریالایزر نازک میشود. مواردی برای برنامهریزی:
- CSV به یک جداکننده و انکودینگ اعلامشده نیاز دارد. Excel در بسیاری از لوکیلهای اروپایی سمیکالون انتظار دارد و UTF-8 را با BOM بهتر مدیریت میکند.
- Excel باید سلولهای عددی واقعی با قالبهای عددی بگیرد، نه رشتههای ازپیشقالببندیشده، تا کاربران بتوانند با آنها محاسبه کنند.
- XML به یک اسکیمای پایدار و مستند نیاز دارد، چون کسی علیه آن یکپارچهسازی خواهد کرد.
- PDF و تصاویر باید فونتهایی را جاسازی کنند که خط درخواستی را پوشش میدهند، که شما را به پوشش گلیف برمیگرداند.
تایماستمپ «از تاریخ» را نیز در هر خروجی بگذارید.
SEO در میان لوکیلهای بسیار#
فراتر از hreflang و سایتمپها:
- عنوانها، توضیحات و متادیتای Open Graph را برای هر لوکیل ترجمه کنید. متادیتای انگلیسی را روی یک صفحه یونانی رها نکنید.
- اسلاگها را فقط در صورتی محلی کنید که بتوانید آنها را پایدار نگه دارید. یک اسلاگ تغییریافته در یک لوکیل یعنی ریدایرکتها و یک خوشه hreflang شکسته.
- از تکرارهای نازک بپرهیزید. اگر یک لوکیل فقط محتوای جزئی دارد، در نظر بگیرید که آیا اصلاً باید ایندکس شود.
- URLهای canonical باید به خود صفحه اشاره کنند، هرگز به نسخه زبانی دیگر.
دسترسپذیری#
lang را روی المان html برای هر لوکیل تنظیم کنید، با تگ کامل (sr-Latn، sr-Cyrl)، تا صفحهخوانها صدا و تلفظ درست را انتخاب کنند. وقتی یک عبارت به زبان دیگری داخل یک صفحه ظاهر میشود، آن را با lang خودش علامت بزنید.
حتی اگر امروز یک زبان راستبهچپ را پشتیبانی نمیکنید، برای آن برنامهریزی کنید. از ویژگیهای منطقی CSS مانند margin-inline-start بهجای margin-left استفاده کنید و dir را از لوکیل مشتق کنید. افزودن عربی بعداً خیلی ارزانتر است وقتی چیدمان چپبهراست را فرض نکرده باشد.
تست: مسیرها × لوکیلها#
با ۲۲ لوکیل، باگی که فقط در یکی از آنها ظاهر میشود بهآسانی از دست میرود. ما یک تست دود خودکار را توصیه میکنیم که روی هر مسیر عمومی و هر لوکیل حلقه بزند و اصول اولیه را بررسی کند:
- صفحه ۲۰۰ برمیگرداند و بدون خطای زمان اجرا رندر میشود؛
htmlصفتlangدرست را دارد؛- جایگزینهای hreflang کاملاند و به URLهای موجود اشاره میکنند؛
- هیچ کلید پیام خام (مانند
rates.table.buy) یا رشته خالی قابلمشاهده نیست؛ - مبدل و جدول نرخها اعداد را در قالب موردانتظار رندر میکنند.
برای طولانیترین زبانها اسنپشاتهای بصری اضافه کنید. برچسبهای آلمانی و یونانی اغلب چیدمانهایی را میشکنند که در انگلیسی خوب به نظر میرسیدند.
برای چه چیزهایی برنامهریزی کنید#
اگر یک پلتفرم چندزبانه Next.js را شروع میکنید، اینها تصمیماتیاند که باید از روز اول بگیرید: یک راهبرد URL با پیشوند لوکیل، یک رجیستری واحد لوکیلها که مسیریابی، متادیتا و سایتمپها را هدایت میکند، یک سیاست روشن برای خطها و تبدیل آنها، Intl برای همه قالببندیها، یک برنامه فونت برای هر خط، بررسیهای CI برای برابری ترجمه، یک سیاست صریح تازگی برای داده زنده و یک منبع حقیقت واحد برای هر خروجی.
هیچیک از اینها غریب نیست، اما طراحی کردنشان از ابتدا بسیار ارزانتر از بازنشانی است. کار ما توسط یک تکلید با بیش از ۲۰ سال تجربه هدایت میشود و این همان نوع زیرساختی است که در وب و پلتفرمها روی آن تمرکز میکنیم. اگر چیزی مشابه برنامهریزی میکنید، با ما در تماس شوید.