Alokai
You are reading the documentation for v0.2, which is no longer the latest version. Switch to v1

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-locale cookie is used to set the language used by Alokai integrations
  • useLocation can be used to help interact with the vsf-locale cookie.
  • 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.

Example implementation, that will set the vsf-locale cookie for the upcoming request, may look as follows:

// apps/storefront-unified-nextjs/middleware.ts

import { type NextRequest, NextResponse } from "next/server";
import createMiddleware from "next-intl/middleware";

import { pathnames } from "./config/navigation";
import { defaultLocale, localePrefix, locales } from "./i18n";

const LOCALE_COOKIE = "vsf-locale";

const i18nMiddleware = createMiddleware({
  defaultLocale,
  localeDetection: false,
  localePrefix,
  locales,
  pathnames,
});

export async function middleware(req: NextRequest) {
  let response = i18nMiddleware(request);

  // since locale detection with NEXT_LOCALE cookie is disabled in presented example, we could gather locale from the response headers
  const locale =
    response.headers.get("x-middleware-request-x-next-intl-locale") ||
    defaultLocale;
  // set cookie for the upcoming request
  request.cookies.set(LOCALE_COOKIE, locale);
  // set cookie for the response, to be used in the browser
  response.cookies.set(LOCALE_COOKIE, locale);

  return res;
}

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, the cookie header has to be set on the server side as well. It can be done by creating a Nuxt 3 plugin:

// apps/storefront-unified-nuxt/plugins/localization.ts

export default defineNuxtPlugin((nuxtApp) => {
  if (import.meta.client) {
    return;
  }
  nuxtApp.hook("vue:setup", () => {
    const { locale } = useI18n();
    const { cookieNames } = useAppConfig();
    const event = useRequestEvent();

    setCookie(event, cookieNames.locale, locale.value);
  });
});

However, Nuxt's setCookie function will only set the cookie for response headers, but for the middleware to also get our vsf-locale cookie, it needs to be set for request headers. This can be achieved by creating a custom setCookie function that will set the cookie for both request and response headers:

// apps/storefront-unified-nuxt/plugins/localization.ts

import { type H3Event, setCookie as setResponseCookie, parseCookies } from "h3";

function setRequestCookie(event: H3Event, name: string, value: string) {
  const { headers } = event.node.req;
  const cookiesObject = {
    ...parseCookies(event),
    [name]: value,
  };

  try {
    headers.cookie = Object.entries(cookiesObject)
      .map(
        (item) =>
          `${encodeURIComponent(item[0])}=${encodeURIComponent(item[1])}`
      )
      .join("; ");
  } catch {
    throw new Error(`Failed to set cookie ${name}=${value}`);
  }
}
function setCookie(event: H3Event, name: string, value: string) {
  setRequestCookie(event, name, value);
  setResponseCookie(event, name, value, {
    sameSite: "strict",
    secure: true,
  });
}

export default defineNuxtPlugin((nuxtApp) => {
  // ...
});

You can access the locale information via useI18n() composable and assign cookies to the request and response objects.

To configure the language settings in Nuxt3, 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 multistore 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.

On this page

Exceptions