Интернационализация

Xingluo поставляется с двуязычной поддержкой интерфейса (zh-CN / en), используя стратегию маршрутизации prefixDefaultLocale: false, чтобы язык по умолчанию не имел префикса URL.

Стратегия маршрутизации

Конфигурация i18n Astro (см. astro.config.ts):

ts
i18n: {
  locales: ["zh-cn", "en"],
  defaultLocale: "zh-cn",
  routing: { prefixDefaultLocale: false },
}

Важно: prefixDefaultLocale: false не создаёт автоматически локализованные копии страниц — вы должны вручную поддерживать зеркальные маршруты [locale]/.

Подход Xingluo:

Корневые страницы = язык по умолчанию (zh-cn), без префикса URL, напр. /posts/welcome/
src/pages/[locale]/ зеркалит все страницы; getStaticPaths использует getLocaleParams() для генерации только нестандартных локалей, напр. /en/posts/welcome/
Зеркальные страницы также являются тонкими обёртками, повторно использующими тот же компонент View для логики рендеринга


/                      → главная (zh-cn)
/en/                   → главная (en)
/posts/welcome/        → запись (zh-cn)
/en/posts/welcome/     → запись (en)

Разрешение локали

Компоненты View используют Astro.currentLocale для автоматического разрешения:

Корневые страницы → zh-cn
Страницы с сегментом [locale] → en (или другие нестандартные локали)

Проверки пути на уровне компонентов не требуются; useTranslations(locale) напрямую получает соответствующие строки.

Структура модуля i18n

src/i18n/:

Файл	Ответственность
`index.ts`	`import.meta.glob("./lang/*.ts", {eager:true})` загружает языки; экспортирует `DEFAULT_LOCALE`, `LOCALES`, `useTranslations(locale)`, `tplStr`
`types.ts`	Полный интерфейс `UIStrings` (все строки для локализации)
`routing.ts`	`getLocalePrefix`, `withLocale(path, locale)`, `parseLocaleFromPath(pathname)`
`staticPaths.ts`	`NON_DEFAULT_LOCALES`, `getLocaleParams()`
`format.ts`	`tplStr(template, vars)` — замена плейсхолдера `{{key}}`
`lang/zh-cn.ts`	Упрощённый китайский (по умолчанию)
`lang/en.ts`	Английский

Структура UIStrings

Интерфейс UIStrings определяет все строки UI для локализации, организованные в группы:

nav: навигация (главная/записи/теги/о нас/архив/поиск/rss)
post: запись (дата, поделиться, теги, назад, редактировать, TOC, копирование кода, лайтбокс изображений и т.д.)
pagination: пагинация
home: главная страница (социальные ссылки, избранное, последнее)
archives: архив (количество, месяцы)
footer: подвал (авторские права)
pages: заголовки и описания страниц
a11y: ярлыки доступности
languageSwitcher: переключатель языка
notFound: 404
comments: раздел комментариев

Шаблонные строки

Строки с плейсхолдерами используют {{key}}, заменяемые через tplStr:

ts
import { tplStr } from "@/i18n";

// archives.postCount = "{{count}} posts"
tplStr(t.archives.postCount, { count: 5 }); // "5 posts"

SEO многоязычные объявления

Заголовок Layout.astro выводит:

<link rel="alternate" hreflang="..." href="..."> для каждого языка
x-default указывает на язык по умолчанию
Интеграция sitemap позволяет конфигурации i18n автоматически генерировать hreflang
Записи нестандартных локалей имеют canonical, указывающий на оригинал локали по умолчанию (чтобы избежать штрафов за дублированный контент; см. SEO)

Добавление языка

Пример: добавление японского ja:

astro.config.ts: добавьте "ja" в i18n.locales и сопоставление "ja": "ja-JP" в sitemap i18n.locales
src/i18n/lang/: создайте ja.ts, экспортирующий полный UIStrings (скопируйте en.ts и переведите)
src/i18n/staticPaths.ts: NON_DEFAULT_LOCALES автоматически включает ja (вычисляется из LOCALES)
src/pages/[locale]/: зеркальные страницы автоматически генерируют версию ja (getLocaleParams покрывает это)
Переключатель языка: добавьте "ja": "日本語" в languageSwitcher.names в zh-cn.ts и en.ts

Перевод на уровне контента

Xingluo поддерживает многоязычный контент записей через поля frontmatter locale и translationKey.

Базовое использование

Запись на языке по умолчанию: поместите в src/content/posts/<slug>.md, установите translationKey как идентификатор группы:

yaml
# src/content/posts/welcome.md
---
title: "欢迎来到星罗"
locale: zh-cn
translationKey: welcome-to-xingluo
tags: [公告, Astro]
---

Перевод: поместите в языковой подкаталог src/content/posts/<locale>/<slug>.md, используя тот же translationKey:

yaml
# src/content/posts/en/welcome.md
---
title: "Welcome to Xingluo"
locale: en
translationKey: welcome-to-xingluo
tags: [announcement, Astro]
---

Структура каталогов


src/content/posts/
├── welcome.md              # Язык по умолчанию (zh-cn)
├── en/
│   └── welcome.md          # Английский перевод
├── ja/
│   └── welcome.md          # Японский перевод
└── another-post.md         # Независимая запись (без translationKey)

Имена языковых подкаталогов должны соответствовать кодам языка в i18n.locales из astro.config.ts
Языковые подкаталоги фильтруются из URL-слага (напр. /posts/welcome/, не /posts/en/welcome/)
Записи без translationKey являются независимыми и не связаны между языками

Поведение маршрутизации

Сценарий	Поведение
Доступ локали по умолчанию к записи `zh-cn`	Отображает оригинал на языке по умолчанию
Нестандартная локаль с переводом	Отображает соответствующий перевод
Нестандартная локаль без перевода	Возвращается к оригиналу на языке по умолчанию (идентичное содержимое, canonical защищает SEO)

Дедупликация списка

Страницы списков (главная, список записей, теги, архив, RSS) используют getPostsForLocale для выбора репрезентативных записей по языку: каждая группа перевода показывает только одну карточку на целевом языке, предотвращая дублирование записей по одной теме.

canonical и SEO

Имеет независимый перевод: canonical указывает на собственный URL перевода, может индексироваться отдельно поисковыми системами
Нет перевода (возврат): canonical указывает на оригинал на языке по умолчанию, избегая штрафов за дублированный контент
Объявления hreflang охватывают все языки, сообщая поисковым системам о связях между языковыми версиями

См. SEO.