Fastry 1.3.0 включает встроенную опциональную интернационализацию. Теперь вы можете запустить сайт на двух (или двадцати) языках, не покидая тему — никаких CLI-инструментов, плагинов или отдельных пакетов. В этом посте мы разберём, что представляет собой эта функция, сколько она стоит (спойлер: ничего, если вы её не используете) и как именно её включить для сайта на английском и русском языках.
Опционально, выключено по умолчанию
Вся функция управляется одним флагом в src/config/i18n.config.ts:
const i18nConfig: I18nConfig = {
enabled: false,
defaultLocale: 'en',
locales: ['en'],
// …
};Когда enabled имеет значение false (по умолчанию), сборка идентична одноязычному сайту байт в байт. Никакой LanguageSwitcher не отображается, никакие теги hreflang не выводятся, никаких дополнительных маршрутов не генерируется, никакой JS для обработки языков не поставляется. Существующие сайты на Fastry при обновлении до 1.3.0 не увидят никаких изменений.
Включите enabled и добавьте второй язык — и весь механизм оживёт.
Что вы получаете при включении
Четыре вещи начинают работать, как только i18n.enabled становится true, а locales содержит как минимум две записи:
- Маршруты с префиксом языка. Ваш язык по умолчанию остаётся в корне сайта. Страница «О нас» на английском всё ещё доступна по адресу
/about. Дополнительные языки находятся по префиксу — русская версия будет по адресу/ru/about. Механизм — это родная маршрутизация i18n в Astro, подключённая условно. - Выпадающий список
LanguageSwitcherв шапке и мобильном меню, автоматически. Он перечисляет все настроенные языки и ссылается на соответствующий путь на той странице, которую посетитель просматривает в данный момент. - Альтернативы
hreflangв<head>каждой страницы, указывающие на версии этого URL для каждого языка, а такжеx-defaultв соответствии с рекомендациями Google для выбора запасного варианта, если ни один язык не подходит. - Вспомогательная функция перевода
t(), работающая на основе JSON-словарей вsrc/i18n/. Английский и голландский языки поставляются «из коробки»; вы можете добавить больше файлов для любого BCP 47 языкового кода.
Никакой клиентской маршрутизации, никакого React или гидратации фреймворков, никакого промежуточного ПО для определения языка. URL с языками генерируются во время сборки, а LanguageSwitcher — это простой выпадающий список на <a> — производительность Fastry сохраняется.
Шаг 1 — включите функцию
Откройте src/config/i18n.config.ts и включите флаг и нужные языки. Вот конфигурация для английского плюс русского:
const i18nConfig: I18nConfig = {
enabled: true,
defaultLocale: 'en',
locales: ['en', 'ru'],
localeNames: {
en: 'English',
ru: 'Русский',
},
detectBrowserLocale: false,
};Три вещи, которые стоит знать:
defaultLocale— это язык, обслуживаемый в корне сайта. Если вы оставите его'en', английские посетители будут попадать на/,/about,/blog. Установите его на'ru'— и русский станет корневым языком, а английский переместится на/en/.... Большинство многоязычных сайтов выбирают в качестве языка по умолчанию язык своей крупнейшей аудитории.locales— это главный список. Порядок не важен для маршрутизации, но он определяет порядок элементов в выпадающем спискеLanguageSwitcher.localeNames— это отображаемые метки в выпадающем списке. Используйте собственное название языка.
Сохраните файл. LanguageSwitcher теперь появится в вашей шапке. Но нажатие на «Русский» приведёт к ошибке 404, потому что русских страниц ещё не существует. Это следующий шаг.
Шаг 2 — создайте страницы на втором языке
Astro использует файловую маршрутизацию, поэтому русская страница «О нас» — это просто новый файл по адресу src/pages/ru/about.astro. Соответствие прямое:
| URL | Исходный файл |
|---|---|
/ | src/pages/index.astro |
/about | src/pages/about.astro |
/contact | src/pages/contact.astro |
/ru/ | src/pages/ru/index.astro (создать) |
/ru/about | src/pages/ru/about.astro (создать) |
/ru/contact | src/pages/ru/contact.astro (создать) |
Вам не обязательно переводить все страницы в первый же день. Страницы, которые не существуют на русском, просто недоступны по русскому URL.
Записи блога и коллекции контента
Коллекции блога и страниц Fastry уже содержат поле locale в своей схеме (src/content.config.ts). Переведённый контент находится в параллельной структуре папок:
src/content/blog/en/astro-rocket-getting-started.mdx
src/content/blog/ru/astro-rocket-getting-started.mdxВ frontmatter русского поста установите locale: ru. Имя папки должно совпадать с кодом языка, который вы используете в i18n.config.ts.
Шаг 3 — переведите встроенные строки интерфейса
LanguageSwitcher, ссылки «Читать далее», метки «Опубликовано» и другие общие строки интерфейса находятся в src/i18n/<locale>.json. Файл ru.json уже создан и содержит все необходимые переводы.
В любом .astro файле вы можете использовать вспомогательную функцию t():
---
import { t, getLocaleFromPath } from '@/i18n';
const locale = getLocaleFromPath(Astro.url.pathname);
---
<a href="/blog">{t('common.readMore', locale)}</a>Отсутствующие ключи возвращают значение языка по умолчанию, а затем сам ключ — частичные переводы видны, но никогда не ломают страницу.
Как работают URL
С настройкой prefixDefaultLocale: false (по умолчанию):
- Язык по умолчанию находится в корне:
/,/about,/blog/hello-world. - Каждый дополнительный язык находится под своим префиксом:
/ru/,/ru/about,/ru/blog/astro-rocket-getting-started.
LanguageSwitcher автоматически строит эти URL. Если посетитель читает /blog/hello-world на английском и нажимает «Русский», он переходит на /ru/blog/hello-world.
Чеклист SEO
Когда i18n включён, SEO-компонент Fastry автоматически генерирует правильные теги. В <head> каждой страницы будут:
<link rel="alternate" hreflang="en" href="https://yoursite.com/about" />
<link rel="alternate" hreflang="ru" href="https://yoursite.com/ru/about" />
<link rel="alternate" hreflang="x-default" href="https://yoursite.com/about" />Это сообщает Google, какая версия страницы соответствует какому языку и какую показывать, если ни один язык не подходит.
Как отключить
Если вы поэкспериментируете с i18n и решите не внедрять его, откат — одна строка. В src/config/i18n.config.ts:
enabled: false,
locales: ['en'],Разверните. LanguageSwitcher исчезнет, теги hreflang перестанут выводиться, и сайт вернётся к одноязычному поведению.
Что дальше
Если вы создаёте что-то с системой i18n и сталкиваетесь с трудностями, откройте issue. Функция появилась потому, что #207 попросил об этом; следующая итерация появится таким же образом.
А пока: включите флаг, создайте копию вашей домашней страницы на втором языке и запускайте.