Краткое руководство по локализации сайта на Astro

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

Настройка маршрутизации Astro i18n для статического контента

Конфигурирование astro.config.mjs для многоязычной поддержки

Начните с настройки встроенной i18n маршрутизации Astro в файле astro.config.mjs. Это сообщает Astro, какие языки вы поддерживаете и как структурировать ваши URL:

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // Использовать /en/ для английских URL
    }
  }
});

Установка prefixDefaultLocale: true гарантирует, что все языки используют согласованные шаблоны URL (/en/about, /es/about), что упрощает управление ссылками и избегание конфликтов маршрутизации в дальнейшем.

Создание локализованной структуры папок

Организуйте ваши страницы, создав папки для конкретных локалей в src/pages/:

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

Каждая папка соответствует локали, определенной в вашей конфигурации. Astro автоматически генерирует правильные маршруты на основе этой структуры.

Управление статической и динамической локализацией в Astro

Организация коллекций контента по локалям

Для постов блога, документации или любых коллекций контента используйте такую же структуру локалей:

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

При запросе контента фильтруйте по текущей локали:

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

Реализация динамических маршрутов с папками [locale]

Вместо дублирования файлов страниц для каждого языка используйте динамические маршруты. Создайте папку [locale]:

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

На ваших страницах используйте getStaticPaths() для генерации маршрутов для всех локалей:

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Обработка динамических строк интерфейса с помощью Paraglide

Установка и настройка Paraglide для Astro

В то время как Astro обрабатывает маршрутизацию страниц, вам нужно решение для текста интерфейса. Paraglide предлагает отличную поддержку TypeScript и минимальный размер бандла:

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

Создание файлов переводов и ключей сообщений

Храните ваши переводы в messages/ в корне вашего проекта:

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

Импортируйте и используйте переводы в ваших компонентах:

---
import * as m from '../paraglide/messages.js';
---

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

Создание переключателя языков и навигации

Использование getRelativeLocaleUrl() для чистых URL

Astro предоставляет вспомогательные функции для генерации правильных локализованных URL. Всегда используйте getRelativeLocaleUrl() вместо ручного объединения строк:

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

Создайте компонент переключателя языков:

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

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

Избегание распространенных ошибок, таких как маршруты с двойными префиксами

Остерегайтесь этих распространенных ошибок:

1. Двойные префиксы: При использовании динамических маршрутов очищайте ваши slug’и, чтобы избежать URL вида /en/blog/en/my-post:

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. Жестко закодированные пути локалей: Всегда используйте i18n помощники Astro вместо объединения строк
3. Отсутствие локали в ссылках: Каждая внутренняя ссылка нуждается в правильной локализации

Продвинутые возможности Astro i18n

Настройка резервных языков

Настройте резервные варианты для непереведенного контента:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // Показывать резервный контент без перенаправления
    }
  }
});

Настройка сопоставления доменов для продакшена

Для продакшн-сайтов с отдельными доменами для каждого языка:

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

Это требует серверного рендеринга с адаптером @astrojs/node или @astrojs/vercel.

Заключение

Локализация сайта на Astro объединяет два подхода: встроенную i18n маршрутизацию для организации статического контента и внешние библиотеки, такие как Paraglide, для динамических строк интерфейса. Начните со структуры папок и конфигурации маршрутизации, затем добавьте управление переводами. Помните об использовании URL-помощников Astro, чтобы избежать распространенных проблем с маршрутизацией, и рассмотрите резервные варианты и сопоставление доменов для продакшн-развертываний.

Часто задаваемые вопросы

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.