Multi-language Support

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-locale cookie is used to set the language used by Alokai integrations
• In Nuxt, useLocation can be used to help interact with the vsf-locale cookie. In Next.js, the useUserSettings hook provides equivalent functionality.
• next-intl and @nuxtjs/i18n are 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.

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.