Перейти к содержанию

Добавление пользовательского языка

XC_VM использует файловую систему перевода. Каждый язык представляет собой отдельный файл .ini в каталоге src/Core/Localization/lang/. Добавление нового языка не требует изменения кода — просто создайте файл, и он автоматически появится в панели администратора.

быстрый старт

  1. Сгенерируйте машинно переведенную начальную точку из en.ini:
make lang-translate LANG_TRANSLATE=xx

Замените xx кодом языка ISO 639-1 (например, it для итальянского, pl для польского, ja для японского). Файл еще не обязательно должен существовать — он создается с каждым ключом из en.ini. Смотрите Синхронизация переводов.

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

cp src/Core/Localization/lang/en.ini src/Core/Localization/lang/xx.ini
  1. Откройте xx.ini и просмотрите или переведите значения (справа от =).:
[Language]
a_to_z = "A to Z"          ; ← translate this
access_code = "Access Code" ; ← translate this
actions = "Actions"         ; ← translate this
  1. Перейдите к Настройки → Интерфейс → Язык интерфейса и выберите новый код языка.

Вот и все. Перезагрузка не требуется.

Формат файла

Каждый файл .ini имеет следующую структуру:

[Language]
key = "Translated text"
another_key = "Another translated text"

Rules:

  • Заголовок раздела [Language] равен требуемый в первой строке.
  • Ключами являются идентификаторы snake_case — не меняйте их.
  • Значения должны быть заключены в двойные кавычки; буквальная кавычка внутри значения записывается как \".
  • Сохраняйте заполнители, такие как {bin}, {count} и %s, и любые HTML-теги, точно такими, как они указаны в en.ini.
  • Ключи следуют за разделами порядка и ; комментариев в en.ini.
  • Кодировка файла должна быть UTF-8 (без спецификации).

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

Шаг Что происходит
Панель загрузки Translator::init() проверяет src/Core/Localization/lang/ на наличие *.ini файлов
Список языков Translator::available() возвращает все найденные языковые коды
Выбор пользователя Язык сохраняется в файле cookie lang (для каждого браузера) и в столбце базы данных settings.language (по умолчанию).
Отсутствующий ключ If a translation key is used in code but missing from your .ini file, the system automatically appends it with the English value from en.ini (or the key name if en.ini lacks it too)

Доступные языки

Код Файл
ar ar.ini — Арабский
bg bg.ini — Болгарский
de de.ini — Немецкий
en en.ini — Английский (справочный)
es es.ini — Испанский
fr fr.ini — Французский
pt pt.ini — Португальский
ru ru.ini — Русский

Синхронизация переводов

en.ini является источником истины. Разработчики добавляют новые строки пользовательского интерфейса в en.ini только; другие языки обновляются с учетом:

make lang-translate                      # every <lang>.ini except en
make lang-translate LANG_TRANSLATE=ru    # a single language

При этом выполняется tools/i18n/translate.py --ini, который перестраивает каждый языковой файл в порядке en.ini:

Случай Результат
Ключ уже переведен Сохранено как есть
Ключ отсутствует в файле Машинный перевод с en.ini
Значение по-прежнему идентично тексту на английском языке (например, автоматически добавляется во время выполнения) Машинный перевод
Ключа больше нет в en.ini Удаленный (указан в выходных данных)
  • Заполнители ({bin}, %s), HTML-теги, сущности (&mdash;) и экранированные кавычки никогда не отправляются в механизм перевода, поэтому они возвращаются без изменений.
  • Движок выбирается с помощью DOCS_TRANSLATE_PROVIDER, так же, как и для документов: translators (по умолчанию, бесплатные веб-движки, без ключа API), anthropic (требуется ANTHROPIC_API_KEY) или noop (копирует английский; быстрый способ добавить недостающие ключи и удалить устаревшие без перевод).
  • Переводы кэшируются в build/docs-cache/ini-<lang>.json: при повторном запуске не выполняются сетевые вызовы, а прерванный запуск (Ctrl+C) возобновляется с того места, где он был остановлен. Если движок не справляется с поиском ключа, значение на английском сохраняется и повторяется при следующем запуске.
  • Машинный перевод - это отправная точка. Перед выполнением перевода просмотрите языковые файлы git diff и исправьте формулировки, отредактировав переведенное значение — значение, отличное от английского, никогда не будет перезаписано.

Чаевые

  • Всегда используйте en.ini в качестве источника истины — содержит все ключи. В других файлах могут отсутствовать ключи, которые автоматически заполняются во время выполнения.
  • Автоматическое создание недостающих ключей: если в вашем файле отсутствует ключ, Translator добавляет к нему значение на английском языке. make lang-translate затем переводит эти записи.
  • Проверьте свой файл — убедитесь, что parse_ini_file() может это прочитать:
php -r "var_dump(parse_ini_file('src/Core/Localization/lang/xx.ini', false, INI_SCANNER_RAW));" | head -20

Дополнительные переводы

Внести свой вклад в перевод проекта:

  1. Разветвите репозиторий.
  2. Создайте свой языковой файл, как описано выше.
  3. Отправьте запрос на извлечение с новым файлом .ini.

Пожалуйста, убедитесь, что все ключи из en.ini присутствуют и переведены.

Связанные файлы

Файл Роль
src/Core/Localization/Translator.php Поиск перевода
src/Core/Localization/lang/ Языковые файлы
tools/i18n/translate.py Синхронизация языковых файлов (--ini) и перевод документов