Internationalization API Reference

هذا المحتوى غير متوفر بلغتك بعد.

أُضيفت في: 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:

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`

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

`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()`

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.

---
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()`

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

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

`getAbsoluteLocaleUrlList()`

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

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

`getPathByLocale()`

Type: (locale: string) => string

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

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

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

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

`getLocaleByPath()`

Type: (path: string) => string

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

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

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

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

`redirectToDefaultLocale()`

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

أُضيفت في: astro@4.6.0

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

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()`

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

أُضيفت في: astro@4.6.0

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

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()`

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

أُضيفت في: astro@4.6.0

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.

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()`

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

أُضيفت في: astro@4.6.0

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

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

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()`

Type: (context: APIContext) => boolean

أُضيفت في: astro@4.6.0

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

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 });
})

ساهم

المجتمع

Internationalization API Reference

Imports from `astro:i18n`

`getRelativeLocaleUrl()`

`getAbsoluteLocaleUrl()`

`getRelativeLocaleUrlList()`

`getAbsoluteLocaleUrlList()`

`getPathByLocale()`

`getLocaleByPath()`

`redirectToDefaultLocale()`

`redirectToFallback()`

`notFound()`

`middleware()`

`requestHasLocale()`

بماذا تفكّر؟

انشئ مشكلة على GitHub

أرسل تعليقات

أرسل تعليقات

Internationalization API Reference

Imports from astro:i18n

getRelativeLocaleUrl()

getAbsoluteLocaleUrl()

getRelativeLocaleUrlList()

getAbsoluteLocaleUrlList()

getPathByLocale()

getLocaleByPath()

redirectToDefaultLocale()

redirectToFallback()

notFound()

middleware()

requestHasLocale()

Imports from `astro:i18n`

`getRelativeLocaleUrl()`

`getAbsoluteLocaleUrl()`

`getRelativeLocaleUrlList()`

`getAbsoluteLocaleUrlList()`

`getPathByLocale()`

`getLocaleByPath()`

`redirectToDefaultLocale()`

`redirectToFallback()`

`notFound()`

`middleware()`

`requestHasLocale()`