astro-i18n-aut

Because .md and .mdx files cannot be directly translated by the integration, you should use Astro Content Collections to manage translated Markdown content.

Organize your content by language subdirectories within your collection. Then, use .astro files in your pages/ directory to render the content based on the detected locale.

Recommended Folder Structure:

.
└── astro-project/
    └── src/
        ├── pages/
        │   └── blog/
        │       ├── index.astro
        │       └── [id].astro
        └── content/
            └── blog/
                ├── en/
                │   ├── post-1.md
                │   └── post-2.md
                ├── es/
                │   ├── post-1.md
                │   └── post-2.md
                └── fr/
                    ├── post-1.md
                    └── post-2.md

Install the integration using npm to add internationalization support to your Astro project.

npm install astro-i18n-aut

The i18n() integration accepts the following options:

• locales: A record of all language locales.
• defaultLocale: The default language locale. The value must be present in the locales keys.
• redirectDefaultLocale: Determines whether the default locale path (e.g., /en/about/) redirects to the root path (e.g., /about/). Defaults to 308 redirect behavior.
• include: Glob pattern(s) to include in translation. Default is ["pages/**/*"].
• exclude: Glob pattern(s) to exclude from translation. Default is ["pages/api/**/*"].

Since the integration re-runs the Astro frontmatter for every translated page, you must detect the current locale using the getLocale function and the Astro.url object. This allows you to conditionally render content based on the active language.

---
import { getLocale } from "astro-i18n-aut";
import Layout from "../layouts/Layout.astro";

const locale = getLocale(Astro.url);

let title: string;
switch (locale) {
  case "es":
    title = "¡Hola Mundo!";
    break;
  case "fr":
    title = "Bonjour Monde!";
    break;
  default:
    title = "Hello World!";
}
---

<Layout title={title}>
  <h1>{title}</h1>
</Layout>

The integration only supports translating .astro files.

Supported:

• ✅ .astro

Unsupported (must be excluded via glob patterns):

• ❌ .md
• ❌ .mdx
• ❌ .html
• ❌ .js / .ts (endpoints)

To exclude unsupported files, update the exclude option in your configuration. For example, to exclude Markdown files and API endpoints:

exclude: ["pages/api/**/*", "pages/**/*.md"]

Note: The standard Astro feature of prefixing files with an underscore (_) to exclude them from routing is not supported by this integration. You must use the exclude glob pattern instead (e.g., ["pages/api/**/*", "pages/**/_*"]).

The filterSitemapByDefaultLocale function allows you to control whether the sitemap includes pages for the default locale. This is useful for SEO strategies where you might want to exclude or include specific language versions in your sitemap generation.

import { filterSitemapByDefaultLocale } from 'astro-i18n-aut';

// Usage depends on the specific integration implementation

The primary entrypoint for the integration is the i18n object (also available as the default export). You use this to add the i18n capabilities to your Astro configuration.

To use it, import i18n from astro-i18n-aut and include it in the integrations array of your astro.config.mjs file.

import { i18n } from 'astro-i18n-aut';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [i18n()],
});

The edge runtime provides utilities for manipulating URLs and identifying locales in a way that is compatible with edge environments.

Key functions include:

• getLocale(): Retrieves the current locale.
• getLocaleUrl(url, locale): Generates a locale-prefixed URL.
• getLocaleUrlPrefix(locale): Returns the URL prefix for a specific locale.
• getAllLocaleUrls(): Returns all available locale URLs.
• getUrlWithoutLocale(url): Removes the locale prefix from a URL.
• getCollectionParamsSlug(): Retrieves slug parameters for collections.
• resolveTrailingSlash(url): Handles trailing slash resolution.
• filterCollectionByDefaultLocale(collection): Filters collections based on the default locale.

import { getLocale, getLocaleUrl } from 'astro-i18n-aut/edge';

const currentLocale = getLocale();
const localizedUrl = getLocaleUrl('/about', currentLocale);

The edge runtime entrypoint exports several core configuration constants used for managing i18n settings. These include defaultLocale, locales, localeKeys, trailingSlash, and BASE_URL.

import { 
  defaultLocale, 
  locales, 
  localeKeys, 
  trailingSlash, 
  BASE_URL 
} from 'astro-i18n-aut/edge';

The getAllLocaleUrls function takes a given URL (as a string or a URL object) and returns a mapping of all available locales to their corresponding URLs. This is useful for generating language switchers or link lists that cover every supported language in the project.

Key behaviors:

• It automatically handles the baseUrl, defaultLocale, and localeKeys configured in your project.
• It resolves trailing slashes according to your project configuration.
• It correctly identifies if a URL already contains a locale prefix or if it is a base path.
• It strips .html extensions from the input path to ensure clean URL generation.

// Example 1: Inputting a path that already has a locale
getAllLocaleUrls("/es/about") 
// Returns: { en: "/about", "es": "/es/about" }

// Example 2: Inputting a base path
getAllLocaleUrls("/about") 
// Returns: { en: "/about", "es": "/es/about" }