Руководство 7: сделать блог доступным на других языках
Выберите языки, адреса главной, тексты интерфейса и переводы контента.
На этой странице
Китайские строки в примерах locales.zh сохранены намеренно: они показывают настройку китайского контента без изменения других языков. Китайские и английские значения по умолчанию в таблицах — цитаты из темы, а не пропущенный перевод.
Это руководство 7 из 8. Порядок всех руководств · Справочник настроек.
Можно сначала писать на одном языке, а переводы добавить позже. Тема предоставляет многоязычный интерфейс и маршруты, но не переводит статьи автоматически. Включение языка, изменение интерфейса и публикация перевода — разные действия.
Все настройки объединяйте с существующим defineThemeConfig({...}) в src/site.config.ts. Сохраняйте i18n и остальные личные значения, не добавляйте второй одноимённый объект.
1. Решите, какие языки нужны
По умолчанию включены девять языков, стандартный — en:
| Код | Язык |
|---|---|
en |
English |
zh |
简体中文 |
zh-hant |
繁體中文 |
ja |
日本語 |
ko |
한국어 |
es |
Español |
pt-br |
Português (Brasil) |
de |
Deutsch |
ru |
Русский |
Если нужны только китайский и английский со стандартным китайским, можно выбрать такую настройку. Иначе сохраните исходные значения:
i18n: {
defaultLocale: 'zh',
locales: {
zh: { meta: { enabled: true } },
en: { meta: { enabled: true } },
ja: { meta: { enabled: false } },
ko: { meta: { enabled: false } },
es: { meta: { enabled: false } },
'pt-br': { meta: { enabled: false } },
de: { meta: { enabled: false } },
ru: { meta: { enabled: false } },
'zh-hant': { meta: { enabled: false } },
},
},
Отсутствие языка в конфигурации не отключает его: значения объединяются со стандартными. Нужен явный meta.enabled: false. Стандартный язык всегда включён: нельзя выбрать defaultLocale: 'zh' и ожидать, что отключение zh его скроет.
Отключение убирает языковой вход и генерацию стандартных страниц, не удаляя статьи каталога. После повторного включения сохранённые файлы снова создадут страницы. Смена кода меняет каталоги и адреса, а не только подпись; старые ссылки существующего сайта обслуживайте самостоятельно.
2. Выберите адрес главной стандартного языка
Добавьте или измените routing внутри существующего i18n:
i18n: {
defaultLocale: 'zh',
routing: { defaultLocalePrefix: 'never' },
},
Пример при стандартном zh:
| Настройка | / |
/zh/ |
/en/ |
|---|---|---|---|
'always', стандарт темы |
Статический переход на /zh/ |
Китайская главная | Английская главная, если включён |
'never' |
Сразу китайская главная | Статический переход на / |
Английская главная, если включён |
Стандартный язык задаётся конфигурацией, не выбирается автоматически по браузеру посетителя. Перенаправление — собранная HTML-страница без дополнительного сервера приложений; подсказка перехода может ненадолго появиться.
Настройка меняет только главную стандартного языка. Блог, статьи, About, Decoder и Fragments китайского сохраняют /zh/, например /zh/blog/my-first-post/ не становится /blog/my-first-post/. Смена стандартного языка не перемещает и не переводит файлы.
3. Заполните главную и интерфейс разных языков
Задайте собственные тексты соответствующего языка, например:
i18n: {
locales: {
zh: {
meta: { label: '简体中文' },
site: {
homeTitle: '小林的数字花园',
hero: '记录开发、阅读和生活。',
},
messages: {
siteDescription: '小林的个人博客,分享项目和学习笔记。',
nav: { home: '首页', blog: '文章', about: '关于我' },
},
},
en: {
site: {
homeTitle: "Lin's Digital Garden",
hero: 'Notes on code, books and everyday life.',
},
messages: { siteDescription: 'Projects and learning notes by Lin.' },
},
},
},
meta.label— имя в языковом меню. Замена «简体中文» на «中文» не переименовывает код zh или URL.site.homeTitleменяет только видимый большой заголовок главной текущего языка; общее название задаётся верхнимsite.titleили переменными среды.site.hero— видимое вступление под большим заголовком.messages.siteDescription— метаописание главной, не видимое вступление. Одного верхнегоsite.descriptionможет быть недостаточно для замены встроенного описания главной.messages.navменяет тексты элементов интерфейса, не маршруты или статьи.
Аналогично i18n.locales.<locale>.about задаёт About языка, а модули messages — соответствующие тексты. Страницы About/Decoder по-прежнему подчиняются глобальным переключателям: наличие перевода их не включает. Примеры — в настройке страниц.
Метаданные языков и адреса — в справочнике языков, три разных текста главной — в справочнике главной.
4. Откуда берутся незаполненные поля
meta.fallback выбирает языки отката конфигурации. Например, для дополнения отсутствующих китайских настроек английскими объедините:
i18n: {
locales: {
zh: { meta: { fallback: ['en'] } },
},
},
Этот en должен существовать в конфигурации языков проекта. Стандартный язык добавляется в необходимую цепочку остальных языков. Сам язык, повторы и неизвестные языки отфильтровываются. Массив заменяется целиком, поэтому перечисляйте весь нужный порядок сразу.
Правила различаются по полям:
| Содержимое | Текущее поведение |
|---|---|
Обычные messages |
Начинает со встроенного английского, объединяет встроенные пакеты и личные переопределения по цепочке, текущий язык приоритетнее; встроенные переводы тоже участвуют |
homeTitle главной |
Ищет непустой заголовок после trim текущего и резервных языков, затем общее название сайта |
hero главной |
Ищет определённое значение текущего и резервных языков; '' намеренно очищает и прекращает поиск |
| About | Начинает со стандартного About, объединяет личные настройки языков по цепочке |
messages.home.transmission главной |
Отдельно: личное текущего языка → личное английского → Knock, knock., без обычной полной цепочки |
Изменение английского меню не означает, что встроенное китайское меню получит этот текст. Чтобы явно изменить язык, переопределите его. Отключение страниц языка не удаляет конфигурацию: если он в цепочке отката, его значения могут дополнять другие языки.
Откат касается только конфигурации и интерфейса: он не переносит английские статьи в китайский блог и не создаёт файлы других языков. Это не сервис перевода контента.
5. Добавьте новый язык
Например, добавьте fr в существующий locales, сохранив включённые и отключённые языки:
i18n: {
locales: {
fr: {
meta: {
label: 'Français',
hreflang: 'fr',
ogLocale: 'fr_FR',
enabled: true,
fallback: ['en'],
},
site: {
homeTitle: 'Le jardin de Lin',
hero: 'Notes de lecture et projets.',
},
messages: {
siteDescription: 'Le blog personnel de Lin.',
nav: { home: 'Accueil', blog: 'Articles', about: 'À propos' },
},
},
},
},
fr — код каталога и маршрута. Рекомендуется стандартный нижний регистр. Команды создания принимают две-три буквы с необязательным одним суффиксом через дефис, например fr, pt-br, zh-hant, не путь или пробелы. Пример сохраняет текущий стандартный язык и не делает французский стандартным автоматически.
hreflang — язык альтернативных ссылок страницы, без поля используется код. ogLocale — языковой/региональный идентификатор Open Graph, например fr_FR, в другом формате, чем путь. Эти метаданные не переводят контент и не гарантируют индексацию поисковиком.
У нового языка нет полного встроенного пакета. Пример переводит только несколько входов, остальные тексты откатываются. Для полного французского интерфейса дополните используемые поиск, пагинацию, комментарии, инструменты, About и другие модули. Начните с видимых областей: ради одной статьи менять реализацию темы не нужно.
6. Добавьте перевод статьи
Создайте одновременно китайскую и английскую заготовки:
npm run new-post -- my-first-post --locales zh,en
Напишите китайский текст в src/content/blog/zh/my-first-post.md, английский — в src/content/blog/en/my-first-post.md. Для нового языка можно выполнить npm run new-post -- french-note --locales fr и заполнить содержимое.
Существующую китайскую статью можно скопировать в целевой языковой каталог с тем же именем, затем перевести заголовок, описание и текст. Относительные изображения вычисляются от нового файла; после смены глубины каталогов проверьте пути. Создатель пропускает одноимённый существующий файл без перезаписи.
Связь переводов определяется полным slug без языкового каталога. zh/my-first-post и en/my-first-post — переводы. Переименование английского в my-story делает его другой статьёй, даже при одинаковом заголовке. Вложенные каталоги тоже должны совпадать.
Языковое меню статьи открывает перевод с тем же slug или список блога целевого языка при отсутствии. SEO-альтернативы объявляют только реальные включённые переводы, не выдают список за переведённую статью.
--locales создаёт выбранные файлы, не включая язык. Без него используется ANGLEFEINT_LOCALES, затем включённые языки; явный параметр приоритетнее среды. Создание заготовки и перевод текста — отдельные действия.
7. Языки заметок и остальных страниц
Переводы заметок связывает одинаковый id frontmatter, не имя файла. Для позднего перевода скопируйте файл в целевой каталог, сохраните id/pubDate, переведите заголовок и текст. Повторный new-fragment создаёт другую идентичность и не подходит.
Один запуск npm run new-fragment -- --locales zh,en создаёт заготовки двух языков с общими ID/временем. Языковое меню списка всегда ведёт на первую страницу целевого языка, не обязательно на ту же заметку. Подробности — в руководстве заметок.
Для общих комментариев статей отдельно включите theme.comments.shareAcrossLocales, по умолчанию false. Заметки делят обсуждение по одинаковому ID. Язык интерфейса и связь обсуждения независимы, текст комментариев не переводится. См. руководство комментариев.
new-page создаёт маршруты включённых языков из одного исходного Astro-файла. Предоставьте языковые варианты контента сами: отдельные копии или переводы страниц автоматически не создаются.
8. Что проверить после изменений
Откройте главные включённых языков в dev, проверьте названия меню, заголовок, вступление и About. Проверьте статью с переводом и без него и ожидаемое переключение. Коды конфигурации и каталогов должны точно совпадать.
Перед публикацией остановите dev и выполните:
npm run doctor
npm run preview
doctor включает проверки и сборку; повторять check/build сразу после успеха не нужно. Поиск языков проверяйте в preview: ищется текущий язык, не все языки вместе. RSS каждого включённого языка — /<locale>/rss.xml с его статьями.
Проверьте домен и разверните весь dist/ заново. Включение языков, адреса и контент требуют новой сборки; локальная настройка онлайн-страницу не меняет. При размещении убирайте старые результаты: отключение языка не создаёт перенаправления старых URL автоматически.
| Симптом | Что проверить |
|---|---|
| Ненужный язык остался в меню | Не удалили ли вы только переопределение вместо явного enabled: false |
| Стандартный язык не отключается | Остался ли он defaultLocale; сначала выберите другой |
| Файл создан, страницы нет | Включён ли язык, совпадают ли коды, выполнена ли новая сборка |
| Остался английский | Не переведена ли только часть нового языка, есть ли его About |
| Заголовок не изменился | Какое поле меняли: общее site.title, homeTitle, hero или messages; проверьте среду |
| Смена языка ведёт в список | Нет ли перевода с тем же slug; это текущий откат |
| После never у статьи остался префикс | Переключатель влияет только на главную стандартного языка, это ожидаемо |
Данные сайта и обновление — в установке, повседневное письмо — в первой статье.
Навигация по руководствам и настройкам
Назад: комментарии · Далее: публикация на домене · Все восемь руководств.
Связанные настройки: языки, адреса и откат, общие комментарии переводов. Полные пути, значения и ограничения — в общем справочнике.