Свой язык и языковой пакет: перевод, файлы, упаковка

Языка нет в каталоге? Его можно добавить самому, и программировать для этого не нужно: язык — это только переводы, ни одной строки кода. Есть два пути. Первый — прямо в панели: скачали образец, перевели, загрузили. Второй — готовый пакет (файл .zip), который можно поставить на любой сайт на Nex1on, свой или чужой.

Путь первый: через панель

Языки и тексты → Языки → Добавить язык. Заполните форму:

Язык создаётся черновиком: на сайте его пока не видно. Дальше три шага на странице самого языка.

1. Скачать образец. Кнопка «Скачать все ключи» отдаёт файл JSON, где есть все строки движка и модулей с английским текстом. Позже, когда часть уже переведена, «Скачать только недостающее» отдаёт только то, чего ещё нет.
2. Перевести и загрузить. Файл устроен так: наверху _meta (служебное, не меняйте), ниже strings — «ключ»: «английский текст». Меняйте только значения справа. Загрузите файл кнопкой «Загрузить и проверить» (до 3 МБ). Загрузка дополняет прежнюю, поэтому переводить можно по частям.
3. Включить. Когда перевод готов, нажмите «Включить»: язык появится в выборе языка на сайте и в языке панели. Полный перевод (100 %) включается сразу, от 90 % — по галочке: недостающее показывается по-английски.

{
    "_meta": { "format": 1, "language": "fr", "base": "en", "keys": 15628 },
    "strings": {
        "ai.bar.label": "Assistant IA",
        "ai.bar.run": "Lancer"
    }
}

Что проверяется при загрузке. Файл разбирается строка за строкой. Неизвестные ключи игнорируются. Строка отклоняется, и в списке под формой написана причина, если в ней:

• потерялась подстановка в фигурных скобках ({count}, {name}): в переводе они должны остаться такими же, как в английском тексте;
• добавилась HTML-подобная разметка или опасная ссылка;
• неверное число форм у строки с числом: формы пишут через «|», по числу форм правила языка;
• значение не строка или длиннее 4000 знаков.

Удаление. Язык сначала выключают, затем «Удалить язык» с вводом его кода. Файлы переводов переносятся рядом в _trash, а не стираются; записи сайта на этом языке сохраняют свой текст.

Путь второй: языковой пакет

Пакет нужен, чтобы отдать язык другим или поставить его на несколько своих сайтов: это один файл .zip. Внутри только описание языка и переводы:

language.json
locales/de.json
modules/news/locales/de.json
modules/forum/locales/de.json

• language.json — описание языка, лежит в корне архива.
• locales/de.json — переводы движка.
• modules/news/locales/de.json — переводы модуля «news»: по файлу на модуль, по желанию.

Других файлов в пакете быть не может: любой лишний файл — отказ всему архиву. Папка с названием пакета не нужна, файлы лежат прямо в корне архива.

{
    "code": "de",
    "name": "German",
    "native": "Deutsch",
    "direction": "ltr",
    "plural": "en",
    "version": "1.0.0",
    "engine_min": "0.9.9"
}

Файл переводов — обычный объект JSON «ключ»: «текст», тот же формат, что у locales/en.json движка: ключи берите оттуда. Для модуля — modules/<имя модуля>/locales/<код>.json, ключи из его en.json. Модулей, которых нет на сайте, пакет не касается.

Правила для значений такие же, как при загрузке в панели: только строки, до 4000 знаков, подстановки {…} как в английском, формы числа через «|». Дополнительно для пакета: ключи только из латинских букв, цифр, точки, подчёркивания и дефиса, вложенность не глубже восьми уровней, не больше 40 000 строк в файле, без HTML-подобной разметки и без ссылок вида javascript:. Обязателен файл переводов ядра locales/<код>.json.

Если язык лежит в исходниках движка (у вас есть locales/<код>.json и modules/*/locales/<код>.json), пакет собирает команда:

php nex1on language:pack pl --version=1.0.0

Она собирает nex1on-language-pl-1.0.0.zip, перед упаковкой проверяет каждый файл так же, как установщик, и печатает путь (по умолчанию nex1on-moduli на два уровня выше папки сайта; изменить — --out=<папка> или app.release_directory в config/local.php). Английский пакетом не выпускается: он есть в поставке.

Как поставить пакет

Дополнения → Модули → Установить из архива, выбрать «Языковой пакет», загрузить файл, посмотреть отчёт и установить. Подробно — в статье «Как поставить своё дополнение». После установки язык остаётся выключенным: включите его на странице «Языки». Английский и основной язык сайта пакетом заменить нельзя. Язык из поставки заменяется только пакетом с подписью Nex1on и версией не ниже установленной.

Ошибки