VirtoCommerce · ivan-kalachikov · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025
@@ -252,6 +252,17 @@ If command "dot" is missing - install graphviz on your OS
 The generated graph will also be saved in the `artifacts` folder.
 
 ## Localization
+### Language Flow
+- Locale selection checks the URL first - using the supported languages list to tell real locale segments from ordinary path parts (full culture like `fr-FR` or an unambiguous short alias such as `fr`), then your “pinned” locale - your last choice saved in localStorage, then your account’s preferred culture, and finally the store default.
+
+- When a locale is chosen, useLanguages.initLocale lazy-loads its translation file (`xx-YY.json`; if missing it falls back to `xx.json`, then to `en.json`), wires it into Vue I18n and Yup, updates the `<html lang>` tag, and rewrites the URL so default or mismatched locale segments vanish.
+
+- Switching via the header selector stores the new culture, captures the exact slug and culture you were on at that moment (previousCultureSlug in session storage), strips any stale locale prefix from the URL, broadcasts a data refresh, and reloads so the whole app restarts in the new language.
+
+- After that reload, useSlugInfo notices previousCultureSlug; while you stay on the same path it asks the backend for slug data using the recorded culture, so `/hello` is resolved with `en-US` instead of the new `fr-FR`, preventing empty responses before the localized slug is known.
+
+- When product, category, brand, or CMS data brings back a localized permalink (updateLocalizedUrl in those page modules), it uses history.pushState to refresh the browser address with the localized path - keeping locale prefix, query string, and hash - so users see the correct URL without triggering router navigation or extra data fetching.
+
 ### Check for missing locale keys
 ```
 yarn check-locales --source en.json -- path/to/locales_folder path/to/**/locales

@@ -15,7 +15,7 @@ import {
   extensionPointsPlugin,
   permissionsPlugin,
 } from "@/core/plugins";
-import { extractHostname, getBaseUrl, Logger } from "@/core/utilities";
+import { extractHostname, Logger } from "@/core/utilities";
 import { createI18n } from "@/i18n";
 import { init as initModuleBackInStock } from "@/modules/back-in-stock";
 import { init as initCustomerReviews } from "@/modules/customer-reviews";
@@ -66,17 +66,16 @@ export default async () => {
 
   app.use(authPlugin);
 
-  const { fetchUser, user, twoLetterContactLocale, isAuthenticated } = useUser();
+  const { fetchUser, user, isAuthenticated } = useUser();
   const { themeContext, addPresetToThemeContext, setThemeContext } = useThemeContext();
   const {
-    detectLocale,
     currentLanguage,
-    supportedLocales,
+    currentMaybeShortLocale,
+    defaultStoreCulture,
     initLocale,
     fetchLocaleMessages,
-    getLocaleFromUrl,
-    pinedLocale,
-    mergeLocales,
+    mergeLocalesMessages,
+    resolveLocale,
   } = useLanguages();
   const { currentCurrency } = useCurrency();
   const { init: initializeHotjar } = useHotjar();
@@ -104,22 +103,18 @@ export default async () => {
 
   setThemeContext(store);
 
-  // priority rule: pinedLocale > contactLocale > urlLocale > storeLocale
-  const twoLetterAppLocale = detectLocale([
-    pinedLocale.value,
-    twoLetterContactLocale.value,
-    getLocaleFromUrl(),
-    themeContext.value.defaultLanguage.twoLetterLanguageName,
-  ]);
-
   /**
    * Creating plugin instances
    */
   const head = createHead();
-  const i18n = createI18n(twoLetterAppLocale, currentCurrency.value.code, fallback);
-  const router = createRouter({ base: getBaseUrl(supportedLocales.value) });
 
-  await initLocale(i18n, twoLetterAppLocale);
+  const currentCultureName = resolveLocale();
+  const isDefaultLocaleInUse = defaultStoreCulture.value === currentCultureName;
+
+  const i18n = createI18n(currentCultureName, currentCurrency.value.code, fallback);
+  await initLocale(i18n, currentCultureName);
+
+  const router = createRouter({ base: isDefaultLocaleInUse ? "" : currentMaybeShortLocale.value });
 
   /**
    * Setting global variables
@@ -167,9 +162,9 @@ export default async () => {
   app.use(configPlugin, themeContext.value);
 
   const UIKitMessages = await getUIKitLocales(FALLBACK_LOCALE, currentLanguage.value?.twoLetterLanguageName);
-  mergeLocales(i18n, currentLanguage.value?.twoLetterLanguageName, UIKitMessages.messages);
+  mergeLocalesMessages(i18n, currentLanguage.value?.twoLetterLanguageName, UIKitMessages.messages);
   if (currentLanguage.value?.twoLetterLanguageName !== FALLBACK_LOCALE) {
-    mergeLocales(i18n, FALLBACK_LOCALE, UIKitMessages.fallbackMessages);
+    mergeLocalesMessages(i18n, FALLBACK_LOCALE, UIKitMessages.fallbackMessages);
   }
   app.use(uiKit);