Multi-language Support
Configure your Alokai Storefront to support multiple languages with both static and dynamic content.
Multi-language can be implemented by switching the language settings based on a cookie. This change only requires the frontend adjustments to ensure that the proper cookie is set and passed to your backend.
Alokai Storefront uses a vsf-locale cookie to handle i18n. This cookie is used to request a certain language for your Alokai integrations, such as e-commerce platforms and CMS. The vsf-locale cookie is set by the storefront and used by the middleware to determine which language to use.
- The
vsf-localecookie is used to set the language used by Alokai integrations - In Nuxt,
useLocationcan be used to help interact with thevsf-localecookie. In Next.js, theuseUserSettingshook provides equivalent functionality. next-intland@nuxtjs/i18nare used to handle static content translations, locale detection, and i18n routing.
Next.js app utilizes next-intl to handle static content translations, locale detection, and i18n routing.
Switching Languages
When switching the language, you need to set vsf-locale cookie that will be consumed by the middleware to determine the language of Alokai integrations, such as ecommerce platforms and CMS.
If you are using server-side rendering, these cookies need to be set on the server side as well. In Alokai Storefront applications, we recommend setting the language cookies by leveraging a Nextjs middleware routing.
The Alokai Next.js storefront uses createAlokaiMiddleware from @vue-storefront/next as a wrapper, with locale detection handled via next-intl. The middleware reads the locale from the response headers set by next-intl:
// apps/storefront-unified-nextjs/proxy.ts
import { createAlokaiMiddleware } from '@vue-storefront/next';
import createMiddleware from 'next-intl/middleware';
import { pathnames } from '@/config/navigation';
import { defaultLocale, localePrefix, locales } from '@/i18n';
const i18nMiddleware = createMiddleware({
defaultLocale,
localeDetection: false,
localePrefix,
locales,
pathnames,
});
export default createAlokaiMiddleware(async (request) => {
const response = i18nMiddleware(request);
// Gather locale from the response headers set by next-intl
const locale = response.headers.get('x-middleware-request-x-next-intl-locale') || defaultLocale;
// ... additional middleware logic (auth redirects, cache control, etc.)
return response;
});The i18n.ts configuration file uses the requestLocale async pattern introduced in next-intl v4:
// apps/storefront-unified-nextjs/i18n.ts
import { notFound } from 'next/navigation';
import { getRequestConfig } from 'next-intl/server';
export const locales = ['en', 'de'] as const satisfies string[];
export const defaultLocale = 'en';
export default getRequestConfig(async ({ requestLocale }) => {
let locale = await requestLocale;
if (!locale) locale = defaultLocale;
// Validate that the incoming `locale` parameter is valid
if (!locales.includes(locale as (typeof locales)[number])) notFound();
return {
locale,
messages: (await import(`./lang/${locale}`)).default(),
};
});Routing is configured using defineRouting and createNavigation from next-intl:
// apps/storefront-unified-nextjs/config/navigation.ts
import { createNavigation } from 'next-intl/navigation';
import { defineRouting } from 'next-intl/routing';
import { defaultLocale, localePrefix, locales } from '@/i18n';
export const pathnames = {
'/': '/',
'/cart': '/cart',
// ... other pathnames
};
const routing = defineRouting({
defaultLocale,
localePrefix,
locales,
pathnames,
});
export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);To configure the language settings in NextJS with next-intl refer to following guide.
The Nuxt Alokai Storefront uses @nuxtjs/i18n with the vue-i18n package under the hood to handle i18n.
It provides set of features for handling i18n in your Nuxt app. It's based on an i18n detection module and enables features like auto-redirecting to the user preferred language, loading of translations, different domains for each language or different subdomains per language.
Static content translations are handled by @nuxtjs/i18n that includes .json translation files. But Alokai integrations, such as the Unified Data Layer and CMS, use a specific vsf-locale cookie.
To ensure that proper data is returned from the server, locale and currency state are initialized on the server side via a Nuxt plugin:
// apps/storefront-unified-nuxt/plugins/localization.ts
import type { SfLocale } from '@/types';
export default defineNuxtPlugin((nuxtApp) => {
if (import.meta.client) {
return;
}
const { locale: i18nLocale, locales: i18nLocales } = (
nuxtApp as unknown as { $i18n: { locale: { value: string }; locales: { value: Array<{ code: string } | string> } } }
).$i18n;
const event = useRequestEvent();
const { locale, locales } = storeToRefs(useSfState());
if (!event) {
return;
}
locale.value = i18nLocale.value as SfLocale;
locales.value = i18nLocales.value.map((localeItem) =>
typeof localeItem === 'string' ? localeItem : localeItem.code,
) as SfLocale[];
nuxtApp.hook('app:created', async () => {
const { fetchCurrencies } = useCurrenciesData();
await fetchCurrencies();
});
});You can access the locale information via useI18n() composable and assign the locale to the application state.
To configure the language settings in Nuxt, please follow this guide.
Exceptions
In most integrations, the language is being determined by the vsf-locale cookie - set it to the language code of your choice and the integration will use it as long as your platform is configured to support the language.
However, there are some exceptions. For example, in bigcommerce, due to the limitations of the platform we need to use the config switcher approach, as the platform supports only one language per store.
If you need more detailed explanations on multi-language support for specific platforms needed, please refer to the dedicated documentation for each integration.