Internationalization API Reference

Added in: astro@3.5.0

This module provides functions to help you create URLs using your project’s configured locales.

Creating routes for your project with the i18n router will depend on certain configuration values you have set that affect your page routes. When creating routes with these functions, be sure to take into account your individual settings for:

• base
• trailingSlash
• build.format
• site

Also, note that the returned URLs created by these functions for your defaultLocale will reflect your i18n.routing configuration.

For features and usage examples, see our i18n routing guide.

Imports from astro:i18n

Section titled Imports from astro:i18n

import {
  getRelativeLocaleUrl,
  getAbsoluteLocaleUrl,
  getRelativeLocaleUrlList,
  getAbsoluteLocaleUrlList,
  getPathByLocale,
  getLocaleByPath,
  redirectToDefaultLocale,
  redirectToFallback,
  notFound,
  middleware,
  requestHasLocale,
 } from 'astro:i18n';

getRelativeLocaleUrl()

Section titled getRelativeLocaleUrl()

Type: (locale: string, path?: string, options?: GetLocaleOptions) => string

Use this function to retrieve a relative path for a locale. If the locale doesn’t exist, Astro throws an error.

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

getRelativeLocaleUrl("fr");
// returns /fr

getRelativeLocaleUrl("fr", "");
// returns /fr

getRelativeLocaleUrl("fr", "getting-started");
// returns /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// returns /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// returns /blog/fr_CA/getting-started
---

getAbsoluteLocaleUrl()

Section titled getAbsoluteLocaleUrl()

Type: (locale: string, path: string, options?: GetLocaleOptions) => string

Use this function to retrieve an absolute path for a locale when [site] has a value. If [site] isn’t configured, the function returns a relative URL. If the locale doesn’t exist, Astro throws an error.

src/pages/index.astro

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

// If `site` is set to be `https://example.com`

getAbsoluteLocaleUrl("fr");
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", "");
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", "getting-started");
// returns https://example.com/fr/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// returns https://example.com/blog/fr-ca/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// returns https://example.com/blog/fr_CA/getting-started
---

getRelativeLocaleUrlList()

Section titled getRelativeLocaleUrlList()

Type: (path?: string, options?: GetLocaleOptions) => string[]

Use this like getRelativeLocaleUrl to return a list of relative paths for all the locales.

getAbsoluteLocaleUrlList()

Section titled getAbsoluteLocaleUrlList()

Type: (path?: string, options?: GetLocaleOptions) => string[]

Use this like getAbsoluteLocaleUrl to return a list of absolute paths for all the locales.

getPathByLocale()

Section titled getPathByLocale()

Type: (locale: string) => string

A function that returns the path associated to one or more codes when custom locale paths are configured.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

src/pages/index.astro

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

getPathByLocale("fr"); // returns "french"
getPathByLocale("fr-CA"); // returns "french"
---

getLocaleByPath()

Section titled getLocaleByPath()

Type: (path: string) => string

A function that returns the code associated to a locale path.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

src/pages/index.astro

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

getLocaleByPath("french"); // returns "fr" because that's the first code configured
---

redirectToDefaultLocale()

Section titled redirectToDefaultLocale()

Type: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

Added in: astro@4.6.0

Note

Available only when i18n.routing is set to "manual"

A function that returns a Response that redirects to the defaultLocale configured. It accepts an optional valid redirect status code.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  if (context.url.pathname.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(context, 302);
  }
})

redirectToFallback()

Section titled redirectToFallback()

Type: (context: APIContext, response: Response) => Promise<Response>

Added in: astro@4.6.0

Note

Available only when i18n.routing is set to "manual"

A function that allows you to use your i18n.fallback configuration in your own middleware.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();
  if (response.status >= 300) {
    return redirectToFallback(context, response)
  }
  return response;
})

notFound()

Section titled notFound()

Type: (context: APIContext, response?: Response) => Promise<Response> | undefined

Added in: astro@4.6.0

Note

Available only when i18n.routing is set to "manual"

Use this function in your routing middleware to return a 404 when:

• the current path isn’t a root. e.g. / or /<base>
• the URL doesn’t contain a locale

When a Response is passed, the new Response emitted by this function will contain the same headers of the original response.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  const pathNotFound = notFound(context);
  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
})

middleware()

Section titled middleware()

Type: (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Added in: astro@4.6.0

Note

Available only when i18n.routing is set to "manual"

A function that allows you to programmatically create the Astro i18n middleware.

This is useful when you still want to use the default i18n logic, but add only a few exceptions to your website.

middleware.js

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // Custom logic after resolving the response.
  // It's possible to catch the response coming from Astro i18n middleware.

  return response;
});

export const onRequest = sequence(customLogic, middleware({
  prefixDefaultLocale: true,
  redirectToDefaultLocale: false
}))

requestHasLocale()

Section titled requestHasLocale()

Type: (context: APIContext) => boolean

Added in: astro@4.6.0

Note

Available only when i18n.routing is set to "manual"

Checks whether the current URL contains a configured locale. Internally, this function will use APIContext#url.pathname.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  if (requestHasLocale(context)) {
    return next();
  }
  return new Response("Not found", { status: 404 });
})