Локализация (i18n)

Локализация (часто сокращается до i18n) означает отображение текста вашей темы на разных языках. Хорошая новость: движок Pano уже поставляется с полными переводами, поэтому вы записываете только те части, которые действительно меняете.

Как это работает

Движок поставляется с полными переводами для языков, которые он поддерживает сегодня, — en-US (английский), tr (турецкий) и ru (русский). Вы не копируете и не поддерживаете эти большие файлы.

Вместо этого ваша тема несёт только различия в папке lang-overrides/, по одному файлу на язык:

lang-overrides/
├─ en-US.json
├─ tr.json
└─ ru.json

Когда вы запускаете bun run sync, Pano сливает ваши переопределения поверх переводов движка. Слияние только добавляющее: вы можете добавить совершенно новый текст или заменить существующий, но никогда не можете потерять ключ движка. Всё, что вы не упомянули, сохраняет значение движка по умолчанию.

Так что ваша работа невелика: пишите только те ключи, которые хотите изменить или добавить.

Пример 1 — Изменить существующий текст

Допустим, вы хотите, чтобы подвал (footer) на турецком говорил что-то другое. Вам не нужно трогать файлы движка — вы просто переопределяете этот один ключ.

Создайте (или откройте, если вы уже его сделали) lang-overrides/tr.json и добавьте ключ, который хотите изменить:

{
  "footer": {
    "copyright": "Benim harika sunucum tarafından yapıldı"
  }
}

После bun run sync турецкие посетители видят там ваш текст, а все остальные ключи подвала по-прежнему приходят из движка нетронутыми. Чтобы изменить ту же надпись на английском, добавьте её также в en-US.json; чтобы изменить на русском — в ru.json.

Пример 2 — Добавить совершенно новый ключ

Если вы добавили собственную разметку — скажем, слоган-герой (hero slogan) в переопределённом представлении — вы можете добавить для него новый ключ перевода.

1. Используйте ключ в представлении. В вашем файле .svelte функция $_ ищет ключ внутри пространства имён (namespace) вашей темы:

<h1>{$_("my-theme.hero-slogan")}</h1>

2. Добавьте ключ для каждого языка в lang-overrides/:

// lang-overrides/en-US.json
{
  "my-theme": {
    "hero-slogan": "Your adventure starts here"
  }
}

// lang-overrides/tr.json
{
  "my-theme": {
    "hero-slogan": "Maceran burada başlıyor"
  }
}

// lang-overrides/ru.json
{
  "my-theme": {
    "hero-slogan": "Твоё приключение начинается здесь"
  }
}

Теперь слоган автоматически показывается на языке посетителя. Запустите bun run sync после добавления ключей, чтобы слияние их подхватило.

Добавление совершенно нового языка

Вы не ограничены тремя встроенными языками. Чтобы добавить новый — например, немецкий — создайте новый файл в lang-overrides/:

lang-overrides/
└─ de.json

Имя файла — это код локали. de.json означает код локали de, en-US.json — en-US: часть до .json и есть код, в том же формате, что и en-US, tr, de (код языка строчными буквами, за которым может следовать дефис и код региона заглавными). Запишите переводы внутри, используя ту же структуру ключей, что и в остальных файлах.

После bun run sync ваш новый язык строится поверх английских переводов движка — любой ещё не переведённый ключ откатывается к английскому, а не показывает сырой ключ.

Какие языки существуют — решает панель

Сам по себе файл не добавляет язык на сайт. Список доступных языков приходит из самого Pano: сначала администратор должен определить в панели локаль с тем же кодом (например, de). Как только такая локаль существует на стороне панели, посетители могут её выбрать, и используются ваши переводы из de.json. Если совпадающая локаль в панели не определена, файл просто игнорируется.

Пропущен перевод?

Если у ключа нет перевода, на экране вместо реального текста показывается сырое имя ключа (например, my-theme.hero-slogan) — простой способ заметить проблему. bun run check также предупреждает вас о ключах, которые используют ваши представления, но которые не переведены, так что вы поймаете их до выпуска. См. Упаковка.

Что дальше

• Сборка и упаковка — соберите, проверьте и упакуйте тему.
• Публикация и Premium — поделитесь темой с другими.