Internationalisation

If you’re looking to translate your website to multiple languages, there are a number of factors to consider.

1. Language Dictionary - The collection of language strings. Typically in JSON format.
2. Routing by Language - Path based rules that dictate which language dictionary and configuration to load.
3. API Localisation - A route to request translated data from the API.
4. Domains - How to associate a domian to a specific locale.
5. Previewing Language Strings - How to preview the object structure that represent a particular string on a website. Used to support non-technical stakeholders with understanding what keys to update.

In this guide we will go through how to achieve each of these steps.

Language Dictionaries

Ingenuity Properties and Edge KV (Recommended)

Using Ingenuity’s Properties Service for managing your language dictionary is recommended as this allows non-technical users to manage the language used across the website without a deployment.

Ingenuity Properties Service is a UI for managing your language dictionary. It’s a list of keys and values.

For the purpose of this guide we assume you have access to our Ingenuity Service’s. If you do not, you can request access from your Ingenuity Project team.

Adding Properties

For Altitude deployed sites we syncronise the values in the Ingenuity Properties Service to a key-value store that lives with your deployed website. Typically referred to as an Edge KV.

This allows for high-performance read operations and for the site to update language entries without requiring a deployment.

We will sync any values from Properties Service that begin following the following format: altitude.<anystring>

Linking Properties Service to your KV

:::note This is currently not yet available to all customers. Please contact the Altitude Platform team to enable this feature. :::

Reading Properties

Once you have linked Properties Service to your KV you can begin to read the KV from your codebase. Refer to the framework guides below on how to read from a KV.

If you’re utilising our integrations there are helper methods available for i18n. Refer to the guides referenced below.

Framework Guides

• Astro: Reading from Edge KVs in Astro
• Astro Integration: Edge KV configuration
• Astro Integration: i18n method

Local Dictionary

You can establish a local language dictionary in the codebase by creating local JSON files. For ease of access you can apply these in a middleware to make them accessible across your application.

If you are using the Astro Integration, a local copy of your language dictionary can alternatively be supplied as part of the configuration setup for KV. This enables local environments to read directly from a local JSON file at runtime. See more

Routing by Language

:::note Guide coming soon :::

Localised Domains

Global top level domains or gTLDs provide SEO benefits by providing localised content on a separate domain. The integration provides application owners the flexibility to configure whether valid locales should redirect to an associated gTLD.

To enable localised domains, a locale should supply a domain within its respective locale config file. The integration will rewrite the underlying request to prefix the locale to the request which will resolve to the specific config file the locale and gTLD of the request is associated with. This domain should also be added to the domains.variants array within the sites config file.

To mitigate the risk of duplicate content, any requests directly to the prefix that have not been subject to a rewrite will 404.

Example request pattern:

www.example.com => rewrite => www.example.com/en-gb/
www.example.com/en-gb/ => www.example.com/en-gb/ (404)

Application setup

As well as configuration updates, application owners must amend routing logic within their application. Routes within the application should be nested inside of a dynamic route unless specified in the exclusionList as outlined in the above configuration. The param to use for this dynamic route must be locale.

Further to this, to handle invalid locales as part of the request, an additional catch all page should be created at the root of the pages directory to force on demand rendering. If your application already contains a catch all route, this should be moved inside of the dynamic [locale] route and the following snippet added to the new catch all route.

//pages/[...https].astro
// new catch all page
---
return new Response(null, Astro.response)
---

The 404.astro page should remain at the root of the pages directory to serve any custom 404 pages.

API Localisation

When switching the language of a site either through path based routing or gTLDs (Global top level domains) it might be desired that the copy and content/products on site also change if they are independently traded. The integration is able to seamlessly achieve API switching by enabling applications to configure custom configs per locale for sites, including defining different API endpoints. This value should be supplied in the i18n.locales locale specific config.