### Install astro-i18n-aut
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Install the astro-i18n-aut package using npm.
```shell
npm install astro-i18n-aut
```
--------------------------------
### Configure astro-i18n-aut in Astro Config
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Configure the astro-i18n-aut integration in your Astro config file, including locales and default locale. This example also shows integration with @astrojs/sitemap.
```typescript
import { defineConfig } from "astro/config";
import { i18n, filterSitemapByDefaultLocale } from "astro-i18n-aut/integration";
import sitemap from "@astrojs/sitemap";
const defaultLocale = "en";
const locales = {
en: "en-US", // the `defaultLocale` value must present in `locales` keys
es: "es-ES",
fr: "fr-CA",
};
export default defineConfig({
site: "https://example.com/",
trailingSlash: "always",
build: {
format: "directory",
},
integrations: [
i18n({
locales,
defaultLocale,
}),
sitemap({
i18n: {
locales,
defaultLocale,
},
filter: filterSitemapByDefaultLocale({ defaultLocale }),
}),
],
});
```
--------------------------------
### Astro Page with Locale-Specific Title
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Example of an Astro page that dynamically sets its title based on the current locale using the getLocale helper function.
```astro
---
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!";
}
---
{title}
```
--------------------------------
### Configure Astro site and build settings
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Required Astro configuration options for site, trailingSlash, and build format. These must be set consistently to ensure correct URL routing.
```js
{
site: "https://example.com/",
trailingSlash: "always",
build: {
format: "directory",
},
}
```
```js
{
site: "https://example.com",
trailingSlash: "never",
build: {
format: "file",
},
}
```
--------------------------------
### Add astro_tmp_pages_* to .gitignore
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Add the temporary Astro pages directory to your .gitignore file to prevent it from being tracked by version control.
```gitignore
astro_tmp_pages_*
```
--------------------------------
### Retrieve all locale URLs with getAllLocaleUrls
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Generates an object mapping all configured locales to their respective paths for a given URL. Useful for SEO hreflang tags and language navigation.
```typescript
import { getAllLocaleUrls } from "astro-i18n-aut";
// Get all locale URLs from a Spanish page
getAllLocaleUrls("/es/about");
// Returns: { en: "/about", es: "/es/about", fr: "/fr/about" }
// Get all locale URLs from the default locale page
getAllLocaleUrls("/about");
// Returns: { en: "/about", es: "/es/about", fr: "/fr/about" }
// Works with URL objects
const url = new URL("https://example.com/fr/products/");
getAllLocaleUrls(url);
// Returns: { en: "/products/", es: "/es/products/", fr: "/fr/products/" }
```
```typescript
---
import { getAllLocaleUrls, locales } from "astro-i18n-aut";
const localeUrls = getAllLocaleUrls(Astro.url);
const siteUrl = "https://example.com";
---
{Object.entries(localeUrls).map(([locale, path]) => (
))}
```
--------------------------------
### Generate Localized URLs with getLocaleUrl
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Apply a locale prefix to a URL path for navigation or language switching.
```typescript
import { getLocaleUrl } from "astro-i18n-aut";
// Convert Spanish URL to English (default locale - no prefix)
getLocaleUrl("/es/about", "en"); // Returns: "/about"
// Convert Spanish URL to French
getLocaleUrl("/es/about", "fr"); // Returns: "/fr/about"
// Convert English URL to Spanish
getLocaleUrl("/about", "es"); // Returns: "/es/about"
// Works with URL objects
const url = new URL("https://example.com/fr/contact/");
getLocaleUrl(url, "es"); // Returns: "/es/contact/"
// Building a language switcher component
---
import { getLocale, getLocaleUrl } from "astro-i18n-aut";
const currentLocale = getLocale(Astro.url);
const currentPath = Astro.url.pathname;
---
```
--------------------------------
### Access configuration values via virtual module
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Import library configuration directly from the virtual module for use in edge runtime contexts or locale-aware logic.
```typescript
import {
defaultLocale, // The configured default locale key (e.g., "en")
locales, // Record of all locales (e.g., { en: "en-US", es: "es-ES" })
localeKeys, // Array of locale keys (e.g., ["en", "es", "fr"])
trailingSlash, // Astro trailingSlash config ("always" | "never" | "ignore")
build, // Astro build config { format: "directory" | "file" }
BASE_URL, // Astro BASE_URL (defaults to "/")
} from "astro-i18n-aut";
// Use these values for locale-aware logic
const isSpanish = getLocale(Astro.url) === "es";
const availableLanguages = localeKeys.map(key => ({
code: key,
name: locales[key]
}));
```
--------------------------------
### getLocaleUrlPrefix
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Returns the locale URL prefix for a given URL.
```APIDOC
## getLocaleUrlPrefix
### Description
Returns the locale URL prefix for a given URL, or an empty string if the URL uses the default locale.
### Parameters
#### Path Parameters
- **url** (string | URL) - Required - The URL or path to extract the prefix from.
### Response
- **string** - The locale prefix (e.g., '/es') or an empty string.
```
--------------------------------
### Configure Astro i18n Integration
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Register the i18n integration in astro.config.mjs to enable automatic route generation and sitemap filtering.
```typescript
// astro.config.mjs
import { defineConfig } from "astro/config";
import { i18n, filterSitemapByDefaultLocale } from "astro-i18n-aut/integration";
import sitemap from "@astrojs/sitemap";
const defaultLocale = "en";
const locales = {
en: "en-US", // the `defaultLocale` value must present in `locales` keys
es: "es-ES",
fr: "fr-CA",
};
export default defineConfig({
site: "https://example.com/",
trailingSlash: "always",
build: {
format: "directory",
},
integrations: [
i18n({
locales,
defaultLocale,
// Optional: glob pattern(s) to include (default: ["pages/**/*"])
include: ["pages/**/*"],
// Optional: glob pattern(s) to exclude (default: ["pages/api/**/*"])
exclude: ["pages/api/**/*"],
// Optional: redirect status for default locale URLs (default: 308)
// Set to false to disable redirects, or use a status code like 301, 302, 307, 308
redirectDefaultLocale: 308,
}),
sitemap({
i18n: {
locales,
defaultLocale,
},
filter: filterSitemapByDefaultLocale({ defaultLocale }),
}),
],
});
```
--------------------------------
### Generate static path parameters with getCollectionParamsSlug
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Use this function within getStaticPaths to strip default locale prefixes from content collection slugs. It ensures dynamic routes correctly map to the expected URL structure.
```typescript
import { getCollection } from "astro:content";
import { filterCollectionByDefaultLocale, getCollectionParamsSlug } from "astro-i18n-aut";
// In src/pages/blog/[slug].astro
export async function getStaticPaths() {
const posts = (await getCollection("blog")).filter(filterCollectionByDefaultLocale);
return getCollectionParamsSlug(posts);
}
```
```typescript
---
import { getCollection } from "astro:content";
import {
filterCollectionByDefaultLocale,
getCollectionParamsSlug,
getLocale
} from "astro-i18n-aut";
import Layout from "../../layouts/Layout.astro";
export async function getStaticPaths() {
const posts = (await getCollection("blog")).filter(filterCollectionByDefaultLocale);
return getCollectionParamsSlug(posts);
}
const { slug } = Astro.params;
const locale = getLocale(Astro.url);
const post = await getEntry("blog", `${locale}/${slug}`);
const { Content } = await post.render();
---
{post.data.title}
```
--------------------------------
### getAllLocaleUrls
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Returns an object containing URLs for all configured locales for a given page, useful for SEO hreflang tags.
```APIDOC
## getAllLocaleUrls
### Description
Returns an object containing URLs for all configured locales for a given page. Useful for generating hreflang tags or complete language navigation menus.
### Parameters
#### Path Parameters
- **url** (string | URL) - Required - The current page path or URL object.
### Response
- **Object** - An object where keys are locale codes and values are the corresponding paths.
```
--------------------------------
### getUrlWithoutLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Strips the locale prefix from a URL and returns the base path.
```APIDOC
## getUrlWithoutLocale
### Description
Strips the locale prefix from a URL and returns the base path. Useful for getting a canonical path or comparing pages across locales.
### Parameters
#### Path Parameters
- **url** (string | URL) - Required - The URL or path to strip the locale from.
### Response
- **string** - The base path without the locale prefix.
```
--------------------------------
### Extract Locale with getLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Retrieve the current locale key from a URL or pathname. Returns the default locale if no prefix is detected.
```typescript
import { getLocale } from "astro-i18n-aut";
// In an Astro component's frontmatter
const locale = getLocale(Astro.url);
// Using with different URL paths
getLocale("/es/about"); // Returns: "es"
getLocale("/fr/products"); // Returns: "fr"
getLocale("/about"); // Returns: "en" (default locale)
getLocale("/enigma"); // Returns: "en" (avoids false matches like "/en...")
// Works with URL objects too
const url = new URL("https://example.com/es/contact/");
getLocale(url); // Returns: "es"
// Full usage in an Astro page
// src/pages/about.astro
---
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!";
}
---
{title}
```
--------------------------------
### Normalize URL paths with resolveTrailingSlash
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Ensures consistent trailing slash behavior based on your Astro configuration. It supports both string paths and URL objects.
```typescript
import { resolveTrailingSlash } from "astro-i18n-aut";
// When trailingSlash is "always":
resolveTrailingSlash("/about"); // Returns: "/about/"
resolveTrailingSlash("/about/"); // Returns: "/about/"
// When trailingSlash is "never":
resolveTrailingSlash("/about/"); // Returns: "/about"
resolveTrailingSlash("/about"); // Returns: "/about"
// Root path always stays "/"
resolveTrailingSlash("/"); // Returns: "/"
// Works with URL objects
const url = new URL("https://example.com/products");
resolveTrailingSlash(url); // Returns path with correct trailing slash
```
--------------------------------
### Filter sitemap entries with filterSitemapByDefaultLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Integrate this filter into @astrojs/sitemap to prevent duplicate entries for the default locale. It accepts an optional base path configuration.
```typescript
import { defineConfig } from "astro/config";
import { i18n, filterSitemapByDefaultLocale } from "astro-i18n-aut/integration";
import sitemap from "@astrojs/sitemap";
const defaultLocale = "en";
const locales = {
en: "en-US",
es: "es-ES",
fr: "fr-CA",
};
export default defineConfig({
site: "https://example.com/",
trailingSlash: "always",
build: { format: "directory" },
integrations: [
i18n({ locales, defaultLocale }),
sitemap({
i18n: { locales, defaultLocale },
// Filter out /en/* URLs since they redirect to /* anyway
filter: filterSitemapByDefaultLocale({ defaultLocale }),
}),
],
});
```
```typescript
filterSitemapByDefaultLocale({
defaultLocale: "en",
base: "/docs/"
});
```
--------------------------------
### Strip locale prefixes with getUrlWithoutLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Removes the locale prefix from a URL to obtain the canonical base path. Useful for path comparison or determining the current page regardless of language.
```typescript
import { getUrlWithoutLocale } from "astro-i18n-aut";
// Remove Spanish locale prefix
getUrlWithoutLocale("/es/about"); // Returns: "/about"
// Remove French locale prefix
getUrlWithoutLocale("/fr/contact"); // Returns: "/contact"
// Default locale URLs unchanged
getUrlWithoutLocale("/about"); // Returns: "/about"
// Works with URL objects
const url = new URL("https://example.com/es/products/category/");
getUrlWithoutLocale(url); // Returns: "/products/category/"
```
```typescript
---
import { getUrlWithoutLocale } from "astro-i18n-aut";
const basePath = getUrlWithoutLocale(Astro.url);
const isHomePage = basePath === "/";
const isAboutPage = basePath === "/about/" || basePath === "/about";
---
```
--------------------------------
### Detect locale prefixes with getLocaleUrlPrefix
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Extracts the locale prefix from a URL, returning an empty string if the default locale is used. Useful for constructing locale-aware relative links.
```typescript
import { getLocaleUrlPrefix } from "astro-i18n-aut";
// Get prefix from Spanish URL
getLocaleUrlPrefix("/es/about"); // Returns: "/es"
// Get prefix from French URL
getLocaleUrlPrefix("/fr/contact"); // Returns: "/fr"
// Default locale returns empty string
getLocaleUrlPrefix("/about"); // Returns: ""
// Works with URL objects
const url = new URL("https://example.com/es/products/");
getLocaleUrlPrefix(url); // Returns: "/es"
```
```typescript
---
import { getLocaleUrlPrefix } from "astro-i18n-aut";
const prefix = getLocaleUrlPrefix(Astro.url);
---
```
--------------------------------
### Define ignore glob patterns
Source: https://github.com/jlarmstrongiv/astro-i18n-aut/blob/main/README.md
Glob patterns used to exclude specific file types or directories from being processed by the integration.
```js
["pages/api/**/*", "pages/**/*.md"];
```
```js
["pages/api/**/*", "pages/**/_*"];
```
--------------------------------
### Filter content collections with filterCollectionByDefaultLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Filters Astro content collections to include only entries belonging to the default locale. Useful for rendering lists that should only display default language content.
```typescript
import { getCollection } from "astro:content";
import { filterCollectionByDefaultLocale } from "astro-i18n-aut";
// Filter blog posts to only get default locale entries
const allPosts = await getCollection("blog");
const defaultLocalePosts = allPosts.filter(filterCollectionByDefaultLocale);
```
```typescript
---
import { getCollection } from "astro:content";
import { filterCollectionByDefaultLocale } from "astro-i18n-aut";
const posts = (await getCollection("blog"))
.filter(filterCollectionByDefaultLocale)
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
```
--------------------------------
### filterCollectionByDefaultLocale
Source: https://context7.com/jlarmstrongiv/astro-i18n-aut/llms.txt
Filters content collection entries to only include items that belong to the default locale.
```APIDOC
## filterCollectionByDefaultLocale
### Description
Filters content collection entries to only include items that belong to the default locale. Useful when you need to display a list from the default locale only.
### Parameters
#### Path Parameters
- **entry** (Object) - Required - A content collection entry object.
### Response
- **boolean** - Returns true if the entry belongs to the default locale.
```