Astro JS - Internationalization Routing

---

---

What is Internationalization?

Internationalization is a routing features in Astro, that allows to built multi language websites by managing contents and routes based on user's language preference. By setting up internationalization, the Astro application will automatically handles routing for different locales. For example, if the user support English (en) and Spanish (es), then the routes might look like /en/about and /es/about. In this chapter, we will learn features of internationalization and how to set it up in your Astro application.

Setup Internationalization in Astro

Follow the steps below to setup internationalization routing in Astro:

Step 1: Configure i18n Routing

To setup internationalization routing, you need to list down all the supported languages (locales) and a default language (defaultLocale) in astro configuration file. The defaultLocale should be one the listed locale, and it is used when the user's language preference is not supported. Here is an example of how to configure i18n routing in Astro:

// File: astro.config.mjs

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "pt-br"],
    defaultLocale: "en",
  }
})

Step 2: Create Locale Files

Next, you need to create locale files for each supported language. Create individual /[locale]/ folders anywhere within src/pages/ and Astros file-based routing will create your pages at corresponding URL paths. For example, if you have a file src/pages/en/about.astro, it will be available at /en/about.

/src/pages/
   en/
      index.astro
      about.astro
      contact.astro
   es/
      index.astro
      about.astro
      contact.astro
   fr/
      index.astro
      about.astro
      contact.astro
   layout.astro

Step 3: Compute Links

After configuring i18n routing, now you can compute links to pages within your site using the helper functions such as 'getRelativeLocaleUrl()' available from the astro:i18n module. The getRelativeLocaleUrl() function takes a locale and a path and returns the URL for that path in the given locale. These generated links will always provide the correct, localized route and can help you correctly use, or check, URLs on your site. Here is an example of how to compute links in Astro:

---
    import { getRelativeLocaleUrl } from 'astro:i18n';

    // defaultLocale is "es"
    const aboutURL = getRelativeLocaleUrl("es", "about");
---

<a href="/get-started/">Vamos!</a>
<a href={getRelativeLocaleUrl('es', 'blog')}>Blog</a>
<a href={aboutURL}>Acerca</a>

The i18n Routing

Astros built-in file-based routing automatically creates URL routes for you based on your file structure within src/pages/. When you configure i18n routing, information about this file structure (and the corresponding URL paths generated) is available to the i18n helper functions so they can generate, use, and verify the routes in your project. Many of these options can be used together for even more customization and per-language flexibility.

Setup Manual Routing

By default, Astro uses automatic routing based on the file structure. However, you can also use manual routing by setting the routing option to "manual" in the i18n configuration. By setting this up, you will be responsible for writing your own routing logic, or executing Astros i18n middleware manually alongside your own.

// File: astro.config.mjs

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: "manual"
  }
})

The prefixDefaultLocale Option

The prefixDefaultLocale option is used to specify whether the default locale should be prefixed to the URL. By default, the default locale is not prefixed to the URL. However, if you want to prefix the default locale to the URL, you can set the prefixDefaultLocale option to true.

• "prefixDefaultLocale: false" (default): URLs in your default language will not have a /[locale]/ prefix. All other locales will.
• "prefixDefaultLocale: true": All URLs, including your default language, will have a /[locale]/ prefix.

// File: astro.config.mjs

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
        prefixDefaultLocale: false
    }
  }
})

The redirectToDefaultLocale Option

The redirectToDefaultLocale option is used to specify whether the user should be redirected to the default locale when they visit the root URL. Setting prefixDefaultLocale: true will also automatically set redirectToDefaultLocale: true in your routing config object. By default, the required src/pages/index.astro file will automatically redirect to the index page of your default locale. If you want to disable this behavior, you can set redirectToDefaultLocale to false.

// File: astro.config.mjs

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
        redirectToDefaultLocale: false
    }
  }
})