Internationalization (i18n)

/**
 * Gets relative URL for a locale
 */
function getRelativeLocaleUrl(
  locale: string,
  path?: string,
  options?: GetLocaleOptions
): string;

interface GetLocaleOptions {
  prependWith?: string;
  normalizeLocale?: boolean;
}

import { getRelativeLocaleUrl } from 'astro:i18n';

const frenchUrl = getRelativeLocaleUrl('fr', '/about');
// Returns: "/fr/about"

const defaultUrl = getRelativeLocaleUrl('en', '/contact');
// Returns: "/contact" (if 'en' is default locale)

/**
 * Gets absolute URL for a locale
 */
function getAbsoluteLocaleUrl(
  locale: string,
  path?: string,
  options?: GetLocaleOptions
): string;

import { getAbsoluteLocaleUrl } from 'astro:i18n';

const frenchUrl = getAbsoluteLocaleUrl('fr', '/about');
// Returns: "https://example.com/fr/about"

/**
 * Gets all relative locale URLs for a path
 */
function getRelativeLocaleUrlList(
  path?: string,
  options?: GetLocaleOptions
): string[];

import { getRelativeLocaleUrlList } from 'astro:i18n';

const urls = getRelativeLocaleUrlList('/about');
// Returns: ["/about", "/fr/about", "/es/about"]

/**
 * Gets all absolute locale URLs for a path
 */
function getAbsoluteLocaleUrlList(
  path?: string,
  options?: GetLocaleOptions
): string[];

/**
 * Gets path segment for a locale code
 */
function getPathByLocale(locale: string): string;

import { getPathByLocale } from 'astro:i18n';

const path = getPathByLocale('fr');
// Returns: "fr"

const customPath = getPathByLocale('pt-BR');
// Returns: "pt-br" (normalized)

/**
 * Gets locale code for a path segment
 */
function getLocaleByPath(path: string): string;

/**
 * Checks if path contains a locale segment
 */
function pathHasLocale(path: string): boolean;

import { pathHasLocale } from 'astro:i18n';

console.log(pathHasLocale('/fr/about')); // true
console.log(pathHasLocale('/about')); // false

/**
 * Redirects to default locale (manual routing only)
 */
function redirectToDefaultLocale(
  context: APIContext,
  statusCode?: ValidRedirectStatus
): Response | undefined;

type ValidRedirectStatus = 301 | 302 | 303 | 307 | 308;

// src/middleware.ts
import { defineMiddleware, redirectToDefaultLocale } from 'astro:middleware';

export const onRequest = defineMiddleware((context, next) => {
  const response = redirectToDefaultLocale(context, 302);
  if (response) return response;
  return next();
});

/**
 * Returns 404 for paths without locale (manual routing only)
 */
function notFound(
  context: APIContext,
  response?: Response
): Response | undefined;

/**
 * Checks if request has locale (manual routing only)
 */
function requestHasLocale(context: APIContext): boolean;

/**
 * Uses fallback system for missing translations (manual routing only)
 */
function redirectToFallback(
  context: APIContext,
  response: Response
): Promise<Response>;

/**
 * Creates i18n middleware (manual routing only)
 */
function middleware(customOptions: RoutingConfig): MiddlewareHandler;

interface RoutingConfig {
  prefixDefaultLocale?: boolean;
  redirectToDefaultLocale?: boolean;
  fallbackType?: 'redirect' | 'rewrite';
}

/**
 * Normalizes locale code (e.g., en_US -> en-US)
 */
function normalizeTheLocale(locale: string): string;

import { normalizeTheLocale } from 'astro:i18n';

console.log(normalizeTheLocale('en_US')); // "en-US"
console.log(normalizeTheLocale('pt_BR')); // "pt-BR"

/**
 * Normalizes a path by removing trailing slashes
 */
function normalizeThePath(path: string): string;

/**
 * Extracts all locale codes including nested codes
 */
function getAllCodes(locales: Locales): string[];

/**
 * Extracts locale codes from locale configuration
 */
function toCodes(locales: Locales): string[];

type Locales = string[] | LocaleConfig[];

interface LocaleConfig {
  path: string;
  codes: string[];
}

/**
 * Extracts locale paths from locale configuration
 */
function toPaths(locales: Locales): string[];

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'es'],
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: true,
      strategy: 'pathname-prefix-other-locales',
    },
    fallback: {
      fr: 'en',
      es: 'en',
    },
  },
});

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      'en',
      {
        path: 'fr',
        codes: ['fr', 'fr-FR', 'fr-CA'],
      },
      {
        path: 'es',
        codes: ['es', 'es-ES', 'es-MX'],
      },
    ],
  },
});

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'es'],
    routing: {
      strategy: 'domains',
    },
    domains: {
      fr: 'https://example.fr',
      es: 'https://example.es',
    },
  },
});

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

const locales = ['en', 'fr', 'es'];
const currentPath = Astro.url.pathname;
const urls = getRelativeLocaleUrlList(currentPath);
---

<nav>
  {locales.map((locale, index) => (
    <a href={urls[index]}>
      {locale.toUpperCase()}
    </a>
  ))}
</nav>

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

const alternateUrls = getAbsoluteLocaleUrlList(Astro.url.pathname);
const locales = ['en', 'fr', 'es'];
---

<head>
  {alternateUrls.map((url, i) => (
    <link rel="alternate" hreflang={locales[i]} href={url} />
  ))}
</head>

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';
import {
  redirectToDefaultLocale,
  notFound,
  requestHasLocale,
} from 'astro:i18n';

export const onRequest = defineMiddleware((context, next) => {
  if (!requestHasLocale(context)) {
    const response = redirectToDefaultLocale(context);
    if (response) return response;

    return notFound(context);
  }

  return next();
});

---
// src/pages/[locale]/index.astro
export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'fr' } },
    { params: { locale: 'es' } },
  ];
}

const { locale } = Astro.params;
const translations = await import(`../../i18n/${locale}.json`);
---

<h1>{translations.title}</h1>