Vue Storefront is now Alokai! Learn More
Multi-language Support

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-i18next and @nuxtjs/i18n are used to handle static content translations, locale detection, and i18n routing.

Next.js

Next.js has built in internationalization support that uses a NEXT_LOCALE cookie to handle i18n.

Switching Languages

When switching the language, you need to set both NEXT_LOCALE and vsf-locale cookies.

  • NEXT_LOCALE is used by Next.js and will determine the language of the static content
  • vsf-locale 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 in createGetServerSideProps.ts.

This function is a wrapper around Next.js' getServerSideProps that the storefront can use to set request headers before fetching any data. For example, this code snippet will set the vsf-locale cookie to the default language:

createGetServerSideProps.ts
// ...
const { setCookie } = await import("cookies-next");

const locale = context.locale ?? context.defaultLocale;

if (locale) {
  // If the cookie is not available, the setCookie won't assign a cookie to the request
  if (!context.req.headers.cookie) context.req.headers.cookie = ' ';
  setCookie('vsf-locale', locale, { res: context.res, req: context.req });
  setCookie('NEXT_LOCALE', locale, { res: context.res, req: context.req });
}

// your getServerSideProps function will run after the cookie is set

You can access the locale information via useRouter() and assign cookies to the response object.

To configure the language settings in NextJS, please follow this guide.

Nuxt 3

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:

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:

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.