چندزبانی و پشتیبانی راستچین (RTL / LTR)
فرانتاند Next.js پروژه به گونهای پیادهسازی شده است که به صورت نیتیو از زبانهای راستچین (فارسی/عربی) و چپچین (انگلیسی) با استفاده از کتابخانه next-intl پشتیبانی میکند.
برای افزودن هر زبان جدید (مانند ترکی، فرانسوی، آلمانی یا اسپانیایی)، ابتدا این فایل کامل انگلیسی شامل تمام ۸۶۳ کلید استاندارد فروشگاه را دانلود کرده و مقادیر آن را ترجمه کنید:
{name}، {discount}، {total} و تگهای HTML مثل <tos> متغیرهای پویای سیستم هستند و نباید ترجمه یا حذف شوند.تنظیم Direction و Locales در Next.js
تنظیم ویژگی dir بر اساس زبان فعال در فایل src/app/[locale]/layout.tsx:
import { NextIntlClientProvider } from "next-intl"import { getMessages } from "next-intl/server"import { isRtlLocale } from "@lib/util/is-rtl" export default async function StoreLayout({ children, params,}: { children: React.ReactNode params: Promise<{ countryCode: string }>}) { const { countryCode } = await params const messages = await getMessages() const isRtl = isRtlLocale() const dir = isRtl ? "rtl" : "ltr" return ( <html lang={countryCode} dir={dir}> <body className={isRtl ? "font-vazirmatn" : "font-inter"}> <NextIntlClientProvider messages={messages}> {children} </NextIntlClientProvider> </body> </html> )}ساختار فایلهای ترجمه (messages)
فایلهای کلید-مقدار ترجمه در پوشه messages/ قرار دارند:
{ "HomePage": { "title": "Medusa Store", "subtitle": "Best products for you" }, "Cart": { "title": "Cart", "checkout": "Go to checkout" }, "Product": { "actions": { "add_to_cart": "Add to cart", "out_of_stock": "Out of stock" } }}تنظیمات متغیرهای محیطی (Environment Variables)
جهت تنظیمات پیشفرض زبان و منطقه در پروژهی Store، باید متغیرهای زیر در فایل .env تنظیم شوند:
# منطقه پیشفرض در صورت عدم تشخیص از Header هاNEXT_PUBLIC_DEFAULT_REGION=IR # زبان پیشفرض فروشگاهDEFAULT_LOCALE=fa-IR- NEXT_PUBLIC_DEFAULT_REGION: برای تعیین کشور پیشفرض کاربر در مواردی که امکان شناسایی آن از طریق Headerها (مثلاً
x-vercel-country) وجود نداشته باشد استفاده میشود (مانندIRبرای ایران). - DEFAULT_LOCALE: تعیینکننده زبان پیشفرض فرانتاند است که در اینجا
fa-IRبرای زبان فارسی در نظر گرفته شده است.
افزودن زبان جدید به فروشگاه بدون نیاز به کدنویسی (No-Code)
Strapi Storefront Settings + Medusa Locales
پلتفرم Loomix از یک معماری چندلایه و کاملاً پویا برای چندزبانی استفاده میکند که به مدیران سایت اجازه میدهد در کمتر از ۳ دقیقه و بدون نیاز به بیلد یا ریاستارت سرور، زبانهای جدید را اضافه کنند:
۱. آمادهسازی و ترجمه فایل JSON
فایل default.json را از باکس بالا دانلود کرده و نام آن را طبق استاندارد BCP-47 به زبان مورد نظر تغییر دهید (مثلاً tr-TR.json برای ترکی یا fr-FR.json برای فرانسوی). سپس مقادیر متنی را ترجمه نمایید.
۲. بارگذاری فایل ترجمه در پنل مدیریت Strapi
وارد پنل مدیریت Strapi شده و به مسیر Content Manager > Single Types > Storefront Setting بروید:
• در بخش Translations روی Add an entry کلیک کنید.
• در فیلد language کد ۴ حرفی استاندارد را وارد کنید (مثال: tr-TR).
• در فیلد file فایل JSON ترجمهشده را در کتابخانه رسانه آپلود و انتخاب کنید.
• در بالای صفحه حتماً ابتدا روی Save و سپس روی Publish کلیک کنید تا کش استورفرانت به صورت زنده پاکسازی شود.
۳. همگامسازی فایل با سورس فرانتاند (اختیاری)
در پنل Strapi به منوی Storefront بروید. زیر بخش Translations & Locales دکمهای به نام Sync Translations from Strapi قرار دارد. این دکمه فایلهای ترجمه آپلودشده را به پوشه محلی store/messages/ دانلود کرده و فایل رجیستری زبانها را مجدداً ایجاد میکند.
آیا بعد از افزودن زبان نیاز به بیلد مجدد (Build) هست؟
deepMerge روی کدهای فروشگاه اعمال میکند.۴. نمایش پرچم و فعالسازی در سلکتور زبان هدر (Medusa Admin)
برای اینکه پرچم کشور و نام زبان جدید در دراپداون هدر سایت اضافه شود، وارد پنل Medusa Admin شوید و در بخش Settings > Store > Locales کد زبان جدید (مانند tr-TR با عنوان Turkish) را ثبت کنید.
چرا زبان جدید بلافاصله در فرانتاند ظاهر نشد؟ (کش ۱ ساعته)
/store/locales را به مدت ۱ ساعت در رم کش میکند (revalidate: 3600). اگر بلافاصله گزینه جدید را در هدر ندیدید، کافیست در سرور دستور زیر را اجرا کنید تا کش خالی شود:docker compose restart storefrontرفع خطای HTTP 403 هنگام همگامسازی ترجمهها
اگر در پنل Strapi هنگام کلیک روی دکمه Sync Translations from Strapi با خطای زیر مواجه شدید:
علت خطا: به طور پیشفرض در استرپی، مجوز دسترسی عمومی (Public Role) برای مشاهده تنظیمات استورفرانت (storefront-settings) فعال نیست و ریکوئست با کد وضعیت 403 مسدود میشود.
مراحل رفع خطا در کمتر از ۳۰ ثانیه:
- وارد پنل مدیریت Strapi شده و به مسیر Settings (آیکون چرخدنده پایین) > USERS & PERMISSIONS PLUGIN > Roles بروید.
- روی نقش Public کلیک کنید تا فرم مجوزها باز شود.
- در لیست افزونهها و جداول، بخش Storefront-setting را پیدا کرده و تیک گزینه find را بزنید.
- همچنین در بخش پلاگینها، وارد قسمت Media Library (رسانهها) شده و تیک گزینه find را فعال کنید (جهت اجازه دسترسی و دانلود فایلهای ترجمه).
- در گوشه بالا سمت راست دکمه Save را بزنید و سپس مجدداً در صفحه Storefront روی Sync کلیک کنید.