Справочник настроек: языки, адреса, переводы и откат

$ опубликовано 2026-11-13 | | обновлено 2026-11-14
Контекст: Все публичные поля i18n, настоящие встроенные значения, типы, ограничения, примеры и границы языковых маршрутов.

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


Вывод
слов 1.9k токенов 2.5k

Китайские строки в примерах locales.zh сохранены намеренно: они показывают настройку китайского контента без изменения других языков. Китайские и английские значения по умолчанию в таблицах — цитаты из темы, а не пропущенный перевод.

Для включения языков и переводов по шагам см. языковое руководство, файл конфигурации — в установке. Остальные модули — в общем справочнике.

Здесь регистрация, адреса и разрешение i18n, без повторения всех сообщений модулей. Точные тексты/примеры главной, статей, Fragments, About, Decoder, музыки и комментариев — в их справочниках. Стандарты из пакета, не demo.

i18n.defaultLocale и i18n.locales

Полный путь Тип / стандарт темы Состояние, действие и ограничения Пример
i18n.defaultLocale string / ‘en’ Действует: язык корневой главной/перехода, необходимый откат и стандартные ссылки. Пустота нормализуется в en, браузерный язык не определяет. Стандартный всегда включён несмотря на enabled: false i18n: { defaultLocale: ‘zh’ }
i18n.locales Record<string, LocaleConfig> / девять ниже Действует: ключ — код каталога/адреса. Рекурсивное слияние, отсутствие встроенного языка не удаляет. Новый не получает автоматический перевод, нужны тексты/контент i18n: { locales: { fr: { meta: { label: ‘Français’ } } } }
i18n.locales.<locale> Частичный LocaleConfig / встроенные уже настроены, новые нет Действует: meta/site/messages/about/aiReadableContent. Отсутствующее дополняется слиянием/откатом; {} не очищает язык locales: { zh: { meta: { enabled: false } } }

Ключ не равен label/hreflang. EN не становится en, каталог zh-CN не превращается в zh автоматически. Используйте одинаковые строчные коды в каталогах, конфигурации и CLI, например zh/en/pt-br/zh-hant. Создатели принимают 2–3 буквы и необязательный один суффикс через дефис. Runtime-нормализация не полный валидатор кодов/путей: не вводите пути и произвольную пунктуацию.

Если стандартный язык не зарегистрирован, нормализация добавит конфигурацию с кодом как label. Это не заменяет контент/перевод. Смена defaultLocale не переносит существующие файлы.

Фактические встроенные стандарты

Без переопределений все девять включены, у стандартного en fallback пуст, у остальных en. Порядок регистрации объекта, не meta.label; отдельного language-order нет.

Код meta.label meta.hreflang meta.ogLocale Эффективный enabled Эффективный fallback
en English en en_US true []
ja 日本語 ja ja_JP true ["en"]
ko 한국어 ko ko_KR true ["en"]
es Español es es_ES true ["en"]
zh 简体中文 zh-CN zh_CN true ["en"]
pt-br Português (Brasil) pt-BR pt_BR true ["en"]
de Deutsch de de_DE true ["en"]
ru Русский ru ru_RU true ["en"]
zh-hant 繁體中文 zh-Hant zh_TW true ["en"]

i18n.locales.<locale>.meta: пять метаданных

Относительные поля внутри meta; стандарты встроенных выше. Для нового языка правила ниже. Ввод частичный: типы не требуют каждый раз переписывать всё.

Относительный путь Тип / при отсутствии у нового языка Состояние, действие и ограничения Пример
meta.label string / код языка Действует: имя меню. Пустота возвращает код, пробелы не trim. Каталог/URL не переименовывает ‘Français’
meta.hreflang string, необязателен / код Действует: html lang, hreflang и часть structured data. Не ключ пути; пустота даёт код без проверки формата ‘fr’
meta.ogLocale string, необязателен / отсутствует Условно: язык Open Graph/alternate. Отсутствие/пустота не выводят, регион не выводится автоматически. Пустота очищает встроенное ‘fr_FR’
meta.enabled boolean, необязателен / true Действует: только false отключает нестандартный; стандартный всегда активен. Стандартные страницы/меню, не удаление файлов/custom-страниц и не доступ false
meta.fallback string[], необязателен / нестандартный дополняется стандартным, у стандартного пуст Действует: прямая цепочка конфигурации. Массив целиком, фильтрует себя/повторы/пустоту/незарегистрированные. Нестандартный всегда получает стандартный [‘zh’, ‘en’]

hreflang/ogLocale различаются, не заменяют ключ. Тема не гарантирует региональную корректность custom-метаданных: выбирайте значения настоящего контента.

i18n.routing.defaultLocalePrefix: адрес стандартной главной

  • Тип / стандарт: ‘always’ | ‘never’ / ‘always’.
  • Состояние и действие: действует только на канонический вход главной стандартного языка, не убирает префикс всех страниц. Пустота вне публичного типа, runtime-fallback always не следует использовать как настройку.
  • Ограничения: не создаёт /blog/, /about/ без языка. Нужны новая сборка/размещение, старые ссылки/редиректы хостинга не мигрируют автоматически.
  • Пример: i18n: { routing: { defaultLocalePrefix: ‘never’ } }.

При defaultLocale en:

Адрес always never
/ Статический HTML-переход /en/ Английская главная
/en/ Английская главная Статический HTML-переход /
/en/blog/ Английский список Английский список
/en/blog/my-post/ Английская статья Английская статья
/en/about/ Английский About, если включён Английский About, если включён
/zh/ Китайская главная, если включён Китайская главная, если включён

Статическая meta-refresh-страница между корнем/языковой главной имеет canonical/noindex. Это не выбор по местоположению и не серверный 301. Внутренние инструменты обычно строят /<locale>/.../, переход к корню зависит от конкретного входа.

Где переопределять site, messages и about?

Префикс i18n.locales.<locale>. Объекты рекурсивно объединяются, массивы заменяются, undefined игнорируется. Пустые строки, false и [] сохраняются с полевой семантикой.

Относительный путь Тип / стандарт Действие, ограничения и пример Полное описание
site { homeTitle?: string; hero?: string } / встроенная главная языка Только языковая главная, не верхняя идентичность site; site: { homeTitle: ‘Мой блог’ } Главная
site.homeTitle string, необязателен / отсутствует Текущий/прямые резервные непустые trim-значения, затем SITE_TITLE; ‘Мой блог’. Пустота продолжает откат Заголовок
site.hero string, необязателен / встроенное вступление, у нового отсутствует Первое определённое цепочки, пустота останавливает. Без значения есть messages.home.hero; ‘Проекты и повседневная жизнь.’ Вступление
messages DeepPartial / личные переопределения обычно отсутствуют, runtime добавляет встроенное Кнопки, статусы, метаописания; messages: { nav: { home: ‘Главная’ } }. Только текст, не функция/перевод контента Общий справочник
about DeepPartial / встроенный About языка Базовый About и рекурсивное слияние цепочки; about: { sections: { who: ‘Я разработчик.’ } }. Не чтение Markdown автоматически About

Точные встроенные site.hero ниже; homeTitle стандартно не задан:

Язык Стандарт site.hero
en Write a short introduction for your site and what readers can expect from your posts.
ja このサイトの紹介文と、読者がどんな記事を期待できるかを書いてください。
ko 사이트 소개와 방문자가 어떤 글을 기대할 수 있는지 간단히 작성하세요.
es Escribe una breve presentación del sitio y qué tipo de contenido encontrarán tus lectores.
zh 在这里写一段站点简介,并告诉读者你将发布什么类型的内容。
pt-br Apresente seu site e conte o que os leitores encontrarão nos seus artigos.
de Stelle deine Website kurz vor und beschreibe, was Leser in deinen Beiträgen erwartet.
ru Кратко представьте свой сайт и расскажите, какие статьи здесь найдут читатели.
zh-hant 簡短介紹你的網站,並告訴讀者這裡會有哪些內容。

Точный порядок отката

Если эффективный meta.fallback fr — [‘zh’, ‘en’], прямая цепь fr → zh → en используется для поиска или обратного слияния. Собственный fallback zh дальше не разворачивается: для ja включите его прямо в массив fr.

  1. Без fallback или с [] нестандартный всё равно получает стандартный. Стандартный может не иметь отката или явно указать другие зарегистрированные.
  2. Сам язык, повторы и неизвестные отфильтровываются. Проверяется регистрация, не включение: отключённый может участвовать.
  3. Отсутствующий стандартный добавляется в конец. Уже явно указанный сохраняет позицию, не переносится в конец.
  4. Обычные messages начинаются со встроенного английского. В обратном порядке эффективной цепи у каждого языка сначала встроенный пакет, затем личное. Поэтому встроенный текущий перевод может перекрыть личный резервного.

en.nav.home ‘Start’ не меняет встроенное китайское «首页» автоматически. Для китайского задайте zh.messages.nav.home. Новый язык без пакета получит резервный UI, не полный собственный перевод.

Алгоритмы различаются:

Контент Текущее поведение
Обычные messages Встроенный английский → пакеты/переопределения резервных → пакет/переопределения текущего
site.homeTitle Прямая цепь непустых trim-значений, затем общее название
site.hero Прямая цепь определённых, пустота останавливает
about DEFAULT_ABOUT_CONFIG, затем обратное слияние прямой цепочки
messages.home.transmission Исключение: личное текущего → личное английского → встроенный авторский английский Knock, knock.; не полная цепь
aiReadableContent Поля языка перекрывают верхние общие, без meta.fallback; ниже
Текст статей/заметок Без отката интерфейса, только собственный контент языка

Откат не дополняет китайский блог английскими статьями, не создаёт переводы, не ищет другие языки ради числа главной и не связывает разные slug.

Выбор языка и общие тексты

Необязательные string в i18n.locales.<locale>.messages с обычной цепью. Локализованный siteTitle сейчас не меняет стандартную идентичность; тип, стандарт и неиспользуемое состояние — в сайте.

Относительное поле Стандарт упрощённого китайского / английского Состояние, действие и ограничения Пример
langLabel 语言 / Language Действует: подсказка/доступность общего выбора, не имена опций; они из meta.label ‘Выбрать язык’
siteDescription 电影感网页界面与 AI 时代工程实践文章。 / Cinematic web interfaces and AI-era engineering essays. Условно: метаописание главной, не видимое вступление/все страницы; у остальных свои источники ‘Мои проекты и учебные заметки.’

Модульные сообщения — в соответствующих справочниках. Поле типа без потребителя не становится действующим. Язык iframe комментариев дополнительно зависит от theme.comments.lang, стандартно английский: комментарии.

aiReadableContent: особое наследование публичного дополнения

i18n.locales.<locale>.aiReadableContent перекрывает верхние notes/links по отдельности, не meta.fallback. Отсутствие наследует, пустой notes или [] очищает, {} сам по себе не очищает глобальное.

Типы, стандарты, проверки и примеры — в AI-дополнении. Это не перевод страницы/текст About, всё публично. Ссылки относительно корня публикации; начальный / пропускает base: разрешение ссылок.

Примеры для объединения

Добавьте в существующий defineThemeConfig({…}) src/site.config.ts без второго i18n. Объекты по-прежнему объединяются с девятью встроенными: запись только двух не отключает остальных.

Только китайские страницы

i18n: {
  defaultLocale: 'zh',
  routing: { defaultLocalePrefix: 'always' },
  locales: {
    zh: { meta: { enabled: true, label: '中文' } },
    en: { meta: { enabled: false } },
    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 } },
  },
},

Стандартный zh нельзя отключить; после отключения страниц en его зарегистрированные настройки участвуют в откате. Для корневой главной смените always на never, статьи останутся /zh/blog/…/.

Французский со своими текстами

i18n: {
  locales: {
    fr: {
      meta: {
        label: 'Français',
        hreflang: 'fr',
        ogLocale: 'fr_FR',
        enabled: true,
        fallback: ['zh', 'en'],
      },
      site: {
        homeTitle: 'Mon blog',
        hero: 'Mes projets et mes notes.',
      },
      messages: {
        langLabel: 'Langue',
        nav: { home: 'Accueil', blog: 'Articles', about: 'À propos' },
      },
    },
  },
},

Здесь лишь несколько строк, не полный французский пакет. Статьи размещайте в src/content/blog/fr/, заметки в src/content/fragments/fr/. Создатель по умолчанию делает заготовки включённых языков, не переводит.

Адреса, переключение и SEO: границы

  • Общее меню только включённых языков, обычно сохраняет подпуть страницы; конкретный маршрут может задать свои цели. Это не гарантированный поиск перевода любой страницы.
  • Статья ищет полный slug без языка. Есть перевод — статья, нет — Blog List языка. SEO только реальных одинаковых slug, не выдаёт список за перевод; без стандартного перевода не выдумывает его x-default.
  • Fragments ведёт на первую страницу языка, не ищет ID; общность обсуждения ID отдельна. Отключение не удаляет файлы или Discussions.
  • meta.label меняет надпись, ключ — адрес/каталог. Автомиграции ссылок и выбора по Accept-Language/браузеру/стране нет.
  • messages — тексты, не универсальный рендер HTML/Markdown. Поддержку переносов/массивов/формата определяет модуль; полная замена массива не добавляет меню/функции.
  • Нет languageOrder, autoDetect, автоматического перевода отсутствующего, всех маршрутов без префикса или плейлистов по языкам. localeHrefs/seoLocaleHrefs custom-страниц — параметры компонентов, не site.config.

После сохранения перечитайте dev-конфигурацию, production пересоберите/разместите. Отключение языка не очищает старый хостинг и не защищает приватное. Назад к общему справочнику.