Enabling internalisation for your sites

Single tenancy mode:

This guide will take you through adding internationalisation for your single-tenanted site. We will assume that you want to serve an english version of your site at www.exampledomain1.com and a german version at www.exampledomain1.de.

Step 1: Add an i18n key to your buildConfig

Add www.exampledomain1.com and www.exampledomain1.de to your domains key at the top level of your build config:

// config/site.js
export default {
  domains: ["www.exampledomain1.com", "www.exampledomain1.de"],
  commerce: {
    endpoint: "https://horizon-api.www.example.com/graphql",
  },
  kv: [
    // ...your kv config
  ],
};

Step 2: Add the i18n key to your config

We will add an i18n key with two locales, english and german. The i18n.locales<Object>.domain key must correspond to the domain you added in the domains array in step 1. i18n.locales<Object>.kv will contain locale-specific keys such as language files and locale-specific settings.

// config/site.js
export default {
  domains: ["www.exampledomain1.com", "www.exampledomain1.de"],
  commerce: {
    endpoint: "https://horizon-api.www.example.com/graphql",
  },
  kv: [
    // ...top-level kv
  ],
  i18n: {
    locales: [
      {
        prefix: "en-gb",
        domain: "www.exampledomain1.com",
        icons: {
          flag: await fetchIcon("circle-flags", "gb"),
        },
      },
      {
        prefix: "de-de",
        domain: "www.exampledomain1.de",
        kv: [
          {
            key: "tenant1",
            namespace: "config",
            local: tenant1Config,
          },
          {
            key: "tenant1.de_de.properties",
            namespace: "lang",
            local: tenant1Lang,
          },
        ],
        icons: {
          flag: await fetchIcon("circle-flags", "de"),
        },
      },
    ],
    fallbackLocale: "en-gb",
    exclusionList: ["api"],
    localeCookie: "locale_V6",
  },
};

Please see the i18n config reference for a full list of required and optional keys.

Step 3: Support rewrites in astro folder structure

When i18n is enabled, astro-integration rewrites every request to /pathname to /localePrefix/pathname

This means that your storefront must have the appropriate request handlers. Please nest your normal handlers in the /pages directory into pages/[locale],

Example directory structure:

pages
├── [...https].astro
├── [locale]
│   ├── [...https].astro
│   ├── basket.astro
│   ├── c
│   │   └── [...slug]
│   │       └── index.astro
│   ├── create-review
│   │   └── [...handle]
│   │       └── index.astro
│   ├── index.astro
│   ├── kv
│   │   └── sessionSettings.js
│   ├── p
│   │   └── [...handle]
│   │       └── index.astro
│   ├── reviews
│   │   └── [sku].astro
│   ├── robots.txt.js
│   └── search.astro
└── 404.astro

At request time, astro-integration will use the X-Forwarded-Host header (in production) to decide which config to read. In local development, it will read the x-altitude-instance header to determine which tenantConfig to use.

Step 4:

Restart the dev server to apply the changes.

$ npm run dev

You should no longer be able to view your app without an x-altitude-instance header. Requests to / are rewritten to /en-gb/ when the x-altitude-instance header is www.exampledomain1.com and to to /de-de/ when the x-altitude-instance header is www.exampldomain1.de. In production, the X-Forwarded-Host header will be used to determine which tenantConfig to use.

New context variables

When i18n is enabled, the following new variables are available in the context of your pages: altitude.locale and altitude.availableLocales. See the global context reference for more information on their types and usage.

Multitenancy mode.

This guide will take you through the process of turning on internationalisation for your sites if astro-integration is running in multitenancy mode.

Prerequisites:

Before you begin, make sure you have:

• astro-integration running in multitenancy mode. See guide for more information.

Step 1: Add i18n keys to each buildConfig in the tenants array

Make sure every tenant in the tenants array has an i18n key.

import tenants from "./config/index";
// astro.config.js
export default defineConfig({
  integrations: [
    altitudeMiddleware({
      config: tenants,
      api: { enabled: true, graphql: gqlIndex },
    }),
  ],
});

import tenant1 from "./tenant1";
import tenant2 from "./tenant2";
import altitudedemo from "./altitudedemo";

export default [tenant1, tenant2, altitudedemo];

tenant1.js and tenant2.js should both have an i18n key. To see all the required fields, see the i18n config reference.

Step 2: Support rewrites in astro folder structure

When i18n is enabled, astro-integration rewrites every request to /pathname to /localePrefix/pathname

This means that your storefront must have the appropriate request handlers. Please nest your normal handlers in the /pages directory into pages/[locale],

Example directory structure:

pages
├── [...https].astro
├── [locale]
│   ├── [...https].astro
│   ├── basket.astro
│   ├── c
│   │   └── [...slug]
│   │       └── index.astro
│   ├── create-review
│   │   └── [...handle]
│   │       └── index.astro
│   ├── index.astro
│   ├── kv
│   │   └── sessionSettings.js
│   ├── p
│   │   └── [...handle]
│   │       └── index.astro
│   ├── reviews
│   │   └── [sku].astro
│   ├── robots.txt.js
│   └── search.astro
└── 404.astro

At request time, astro-integration will read the x-altitude-instance header (in dev mode) or the X-Forwarded-Host header (in production) to decide which tenantConfig to read.

New context variables

When i18n is enabled, the following new variables are available in the context of your pages. altitude.locale and altitude.availableLocales. See the global context reference for more information on their types and usage.