مستنداتبخش برنامه نویسانچندزبانی و پشتیبانی RTL/LTR
next-intl + Strapi CMS + Medusa v2

چندزبانی و پشتیبانی راست‌چین (RTL / LTR)

فرانت‌اند Next.js پروژه به گونه‌ای پیاده‌سازی شده است که به صورت نیتیو از زبان‌های راست‌چین (فارسی/عربی) و چپ‌چین (انگلیسی) با استفاده از کتابخانه next-intl پشتیبانی می‌کند.

دریافت فایل قالب پایه انگلیسی (default.json)

برای افزودن هر زبان جدید (مانند ترکی، فرانسوی، آلمانی یا اسپانیایی)، ابتدا این فایل کامل انگلیسی شامل تمام ۸۶۳ کلید استاندارد فروشگاه را دانلود کرده و مقادیر آن را ترجمه کنید:

دانلود قالب default.json (حجم: ۴۲KB)
نکته مهم در ترجمه: عبارات درون آکولاد مانند {name}، {discount}، {total} و تگ‌های HTML مثل <tos> متغیرهای پویای سیستم هستند و نباید ترجمه یا حذف شوند.

تنظیم Direction و Locales در Next.js

تنظیم ویژگی dir بر اساس زبان فعال در فایل src/app/[locale]/layout.tsx:

src/app/[countryCode]/layout.tsx
typescript
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/ قرار دارند:

messages/default.json
json
{
"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 تنظیم شوند:

.env
bash
# منطقه پیش‌فرض در صورت عدم تشخیص از 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) هست؟
خیر، به هیچ وجه نیازی به بیلد نیست! فرانت‌اند Next.js مجهز به سیستم Dynamic Fetching و On-Demand Revalidation است؛ یعنی بلافاصله فایل ترجمه را از Strapi دانلود کرده و با متد 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 با خطای زیر مواجه شدید:

[Translation Sync] Strapi endpoint returned HTTP 403. Falling back to local messages directory.

علت خطا: به طور پیش‌فرض در استرپی، مجوز دسترسی عمومی (Public Role) برای مشاهده تنظیمات استورفرانت (storefront-settings) فعال نیست و ریکوئست با کد وضعیت 403 مسدود می‌شود.

مراحل رفع خطا در کمتر از ۳۰ ثانیه:

  1. وارد پنل مدیریت Strapi شده و به مسیر Settings (آیکون چرخ‌دنده پایین) > USERS & PERMISSIONS PLUGIN > Roles بروید.
  2. روی نقش Public کلیک کنید تا فرم مجوزها باز شود.
  3. در لیست افزونه‌ها و جداول، بخش Storefront-setting را پیدا کرده و تیک گزینه find را بزنید.
  4. همچنین در بخش پلاگین‌ها، وارد قسمت Media Library (رسانه‌ها) شده و تیک گزینه find را فعال کنید (جهت اجازه دسترسی و دانلود فایل‌های ترجمه).
  5. در گوشه بالا سمت راست دکمه Save را بزنید و سپس مجدداً در صفحه Storefront روی Sync کلیک کنید.