Справочник API интернационализации

Добавлено в: astro@3.5.0

Этот модуль предоставляет функции, помогающие создавать URL-адреса с использованием настроенных локалей вашего проекта.

Создание маршрутов для вашего проекта с помощью i18n-маршрутизатора будет зависеть от определенных настроек конфигурации, которые влияют на маршруты страниц. При создании маршрутов с помощью этих функций обязательно учитывайте ваши индивидуальные настройки для:

Также обратите внимание, что URL-адреса, созданные этими функциями для вашей defaultLocale (локаль по умолчанию), будут отражать вашу конфигурацию i18n.routing.

Информацию о функциях и примеры использования смотрите в нашем руководстве по маршрутизации i18n.

Импорт из `astro:i18n`

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

`getRelativeLocaleUrl()`

Тип: (locale: string, path?: string, options?: GetLocaleOptions) => string

Используйте эту функцию для получения относительного пути для локали. Если локаль не существует, Astro выдаст ошибку.

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

getRelativeLocaleUrl("fr");
// возвращает /fr

getRelativeLocaleUrl("fr", "");
// возвращает /fr/

getRelativeLocaleUrl("fr", "getting-started");
// возвращает /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// возвращает /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// возвращает /blog/fr_CA/getting-started
---

`getAbsoluteLocaleUrl()`

Тип: (locale: string, path?: string, options?: GetLocaleOptions) => string

Используйте эту функцию для получения абсолютного пути для локали, когда [site] имеет значение. Если [site] не настроен, функция возвращает относительный URL. Если локаль не существует, Astro выдаст ошибку.

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

// Если `site` установлен как `https://example.com`

getAbsoluteLocaleUrl("fr");
// возвращает https://example.com/fr

getAbsoluteLocaleUrl("fr", "");
// возвращает https://example.com/fr/

getAbsoluteLocaleUrl("fr", "getting-started");
// возвращает https://example.com/fr/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// возвращает https://example.com/blog/fr-ca/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// возвращает https://example.com/blog/fr_CA/getting-started
---

`getRelativeLocaleUrlList()`

Тип: (path?: string, options?: GetLocaleOptions) => string[]

Используйте это аналогично getRelativeLocaleUrl, чтобы вернуть список относительных путей для всех локалей.

`getAbsoluteLocaleUrlList()`

Тип: (path?: string, options?: GetLocaleOptions) => string[]

Используйте это аналогично getAbsoluteLocaleUrl, чтобы вернуть список абсолютных путей для всех локалей.

`getPathByLocale()`

Тип: (locale: string) => string

Функция, которая возвращает path (путь), связанный с одним или несколькими codes (кодами), когда настроены пользовательские пути локалей.

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

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

getPathByLocale("fr"); // возвращает "french"
getPathByLocale("fr-CA"); // возвращает "french"
---

`getLocaleByPath()`

Тип: (path: string) => string

Функция, которая возвращает code (код), связанный с path (путем) локали.

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

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

getLocaleByPath("french"); // возвращает "fr", так как это первый настроенный код
---

`redirectToDefaultLocale()`

Тип: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

Добавлено в: astro@4.6.0

Функция, возвращающая Response, который перенаправляет на настроенную defaultLocale (локаль по умолчанию). Она принимает необязательный валидный код статуса перенаправления.

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

Тип: (context: APIContext, response: Response) => Promise<Response>

Добавлено в: astro@4.6.0

Функция, которая позволяет использовать вашу конфигурацию i18n.fallback в вашем собственном 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()`

Тип: (context: APIContext, response?: Response) => Promise<Response> | undefined

Добавлено в: astro@4.6.0

Используйте эту функцию в вашем middleware маршрутизации для возврата 404, когда:

текущий путь не является корневым (например / или /<base>)
URL не содержит локаль

Когда передается Response, новый 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()`

Тип: (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Добавлено в: astro@4.6.0

Функция, которая позволяет программно создать middleware Astro i18n.

Это полезно, когда вы все еще хотите использовать логику i18n по умолчанию, но добавить лишь несколько исключений для вашего сайта.

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

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

  // Пользовательская логика после разрешения ответа.
  // Можно перехватить ответ, поступающий от middleware Astro i18n.

  return response;
});

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

`requestHasLocale()`

Тип: (context: APIContext) => boolean

Добавлено в: astro@4.6.0

Проверяет, содержит ли текущий URL настроенную локаль. Внутренне эта функция будет использовать 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 });
})

`normalizeTheLocale()`

Тип: (locale: string) => string

Заменяет подчеркивания (_) на дефисы (-) в заданной локали перед возвратом версии в нижнем регистре.

---
import { normalizeTheLocale } from "astro:i18n";

normalizeTheLocale("it_VT") // возвращает `it-vt`
// Предполагая, что текущая локаль `"pt-PT"`:
normalizeTheLocale(Astro.currentLocale) // возвращает `pt-pt`
---

`pathHasLocale()`

Тип: (path: string) => boolean

Добавлено в: astro@4.6.0

Проверяет, содержит ли данный путь настроенную локаль.

Это полезно для предотвращения ошибок перед использованием утилиты i18n, которая зависит от локали из пути URL.

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

---
import { pathHasLocale } from "astro:i18n";

pathHasLocale("italiano"); // возвращает `true`
pathHasLocale("es"); // возвращает `true`
pathHasLocale('/es/blog/'); // возвращает `true`
pathHasLocale("it-VT"); // возвращает `false`
---

`toCodes()`

Тип: (locales: Locales) => string[]

Добавлено в: astro@4.0.0

Извлекает настроенные коды локалей для каждой локали, определенной в вашей конфигурации. Когда с локалью связано несколько кодов, в массив будет добавлен только первый.

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

---
import { i18n } from "astro:config/client";
import { toCodes } from "astro:i18n";

toCodes(i18n!.locales); // ["it-VT", "es"]
---

`toPaths()`

Тип: (locales: Locales) => string[]

Добавлено в: astro@4.0.0

Извлекает настроенные пути локалей для каждой локали, определенной в вашей конфигурации.

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

---
import { i18n } from "astro:config/client";
import { toPaths } from "astro:i18n";

toPaths(i18n!.locales); // ["italiano", "es"]
---

Справочник API интернационализации

Импорт из astro:i18n

getRelativeLocaleUrl()

getAbsoluteLocaleUrl()

getRelativeLocaleUrlList()

getAbsoluteLocaleUrlList()

getPathByLocale()

getLocaleByPath()

redirectToDefaultLocale()

redirectToFallback()

notFound()

middleware()

requestHasLocale()

normalizeTheLocale()

pathHasLocale()

toCodes()

toPaths()

Импорт из `astro:i18n`

`getRelativeLocaleUrl()`

`getAbsoluteLocaleUrl()`

`getRelativeLocaleUrlList()`

`getAbsoluteLocaleUrlList()`

`getPathByLocale()`

`getLocaleByPath()`

`redirectToDefaultLocale()`

`redirectToFallback()`

`notFound()`

`middleware()`

`requestHasLocale()`

`normalizeTheLocale()`

`pathHasLocale()`

`toCodes()`

`toPaths()`