Çok Dilli Mimari ve Yerel RTL/LTR Desteği
7 küresel dili otomatik yönlendirme ve önbellek desteğiyle kusursuz yöneten next-intl altyapısı.
To add any new language (such as Turkish, French, German, or Spanish), download this complete base English template containing all 863 standard storefront keys and translate its values:
{name}, {discount}, {total} and HTML tags like <tos> are dynamic system interpolation variables and must NOT be modified or translated.1. Rota Tabanlı Dil Yönetimi (Locale Routing)
Uluslararası SEO uyumluluğu için her URL'nin başına dil kodu (örn: /tr veya /en) eklenir.
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> )}2. CSS Mantıksal Özellikler Stratejisi (Logical Properties)
Arayüzün RTL ve LTR dillerinde bozulmadan akması için Tailwind CSS mantıksal sınıfları (ms, me, start, end) kullanılır.
{ "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" } }}Ortam Değişkenleri Yapılandırması (Environment Variables)
Store projesinde varsayılan dil ve bölge ayarlarını yapılandırmak için .env dosyasında aşağıdaki değişkenler tanımlanmalıdır:
# Başlıklardan tespit edilemezse varsayılan bölge alternatifiNEXT_PUBLIC_DEFAULT_REGION=us # Varsayılan mağaza arayüzü diliDEFAULT_LOCALE=en-US- NEXT_PUBLIC_DEFAULT_REGION: Konumlandırma başlıklarının (
x-vercel-countrygibi) bulunmadığı durumlarda varsayılan ülke kodunu belirler (uluslararası mağazalar içinus, Türkiye içinTRönerilir). - DEFAULT_LOCALE: Ön yüzün varsayılan dilini belirler (İngilizce mağazalar için
en-US, Türkçe içintr-TRönerilir).
Adding a New Language Without Writing Code (No-Code)
Strapi Storefront Settings + Medusa Locales
The Loomix platform uses a dynamic, multi-layered architecture for localization, allowing store managers to add complete languages in under 3 minutes without rebuilding or restarting containers:
1. Prepare and Translate the JSON File
Download the base default.json file above, rename it following standard BCP-47 naming (e.g., tr-TR.json for Turkish or fr-FR.json for French), and translate the string values.
2. Upload in Strapi CMS
Log in to Strapi Admin and navigate to Content Manager > Single Types > Storefront Setting:
• Under the Translations section, click Add an entry.
• In the language field, enter the standard 4-letter compound code (e.g., tr-TR).
• In the file field, upload and select the translated JSON file.
• Click Save and then Publish to invalidate the storefront cache via on-demand ISR webhooks.
3. Local Source Synchronization (Optional)
In Strapi Admin, open the Storefront management page. Under the Translations & Locales card, click Sync Translations from Strapi. This downloads uploaded files directly into store/messages/ and regenerates the local language registry.
Is a production rebuild required after adding a language?
deepMerge over base strings, making changes live instantly without rebuild or downtime.4. Activate Header Flag Selector (Medusa Admin)
To display the country flag and language name in the storefront header dropdown, navigate to Medusa Admin > Settings > Store / Locales and add the new locale (e.g., code tr-TR with name Turkish).
Why is the new language not immediately visible? (1-Hour Cache)
/store/locales API response in memory for 1 hour (revalidate: 3600) for high throughput. If the flag does not appear immediately, simply run the following command on your VPS to clear the cache:docker compose restart storefrontResolving HTTP 403 Forbidden on Translation Sync
If clicking Sync Translations from Strapi outputs the following error:
Root Cause: In Strapi, the Public role does not have read permissions granted for the storefront-settings endpoint by default, causing requests to be rejected with status 403.
Resolution Steps (Under 30 Seconds):
- Log into Strapi Admin and go to Settings (bottom gear icon) > USERS & PERMISSIONS PLUGIN > Roles.
- Click on the Public role to open permission settings.
- Under content types, find Storefront-setting and check the find permission.
- Under the Plugins list, navigate to Media Library and ensure the find permission is checked (to permit downloading translation files).
- Click Save in the top right corner, then return to the Storefront page and click Sync again.