Translate

Языки для каждого игрока, файлы переводов, переведённые таблички и необязательный ИИ-перевод чата.

Приватныеv0.2.0Утилиты

ТребуетсяTypeWriter0.9.0-beta-177 (BTC build)GUIнеобязательноMySQLнеобязательноMiniPlaceholdersнеобязательно

Создано для сети BornToCraft. Это расширение описано для справки и не распространяется.

Обзор

Translate позволяет каждому игроку выбрать язык и читать содержимое вашего сервера на нём. Вы объявляете языки в одной записи конфигурации, пишете тексты в файлах JSON (формат совместим с плагином Triton, поэтому существующие файлы можно использовать повторно) и отображаете их везде, где принимаются плейсхолдеры MiniMessage, с помощью <translate_key:your.key>. Каждый игрок видит текст на своём языке, с переходом на другой язык, когда текста нет.

Сверху надстроены три необязательные возможности: переводимые таблички (табличка показывает свой текст на языке того, кто на неё смотрит), меню языка и меню настроек, построенные как обычные страницы GUI, и ИИ-перевод чата, при котором сообщения чата переводятся для зрителей, говорящих на другом языке, через ИИ-провайдера или движок перевода.

Выбор игроков хранится в артефактах. Язык сохраняется для каждого игрока, так же как и согласие на перевод табличек и чата.

Возможности

Список языков — у каждого языка есть код, флаг-баннер, отображаемое название, клиентские локали, запасные языки и действия, выполняемые при выборе.
Файлы JSON в стиле Triton — переводы текстов и табличек с аргументами %1, %2, загружаются из папки и перезагружаются без перезапуска.
Цепочка запасных языков — запрошенный язык, затем его fallbackLanguages, затем основной язык.
Автоопределение — при желании переключайтесь на язык, соответствующий локали клиента.
Переводимые таблички — размещайте текст по координатам табличек; игроки могут отказаться в меню настроек.
Меню, объявленные на страницах — стройте меню языка и настроек как страницы GUI с типами кнопок Translate.
ИИ-перевод чата — OpenRouter, OpenAI, DeepSeek, Groq, Mistral, Ollama, Anthropic, Gemini, LibreTranslate, DeepL или любой OpenAI-совместимый сервер, с кэшем.
События и факты языка — запускайте записи, когда игрок меняет язык, и проверяйте текущий язык в критериях.

Установка

Установите расширение GUI, чтобы использовать меню языка и настроек (необязательно, если вы используете только команду).
По желанию установите расширение MySQL: тогда кэш ИИ-перевода сохраняется в базе данных, иначе он живёт только в памяти.
Поместите JAR-файл Translate в plugins/Typewriter/extensions/ и перезапустите сервер.
Создайте папку plugins/Typewriter/Translate/ (она создаётся автоматически при первой загрузке) и поместите в неё ваши файлы переводов .json.
Установите MiniPlaceholders, если хотите отображать переводы через плейсхолдеры.

Начало работы

В веб-панели TypeWriter откройте страницу static и добавьте артефакт Player Language: без него выбранный язык не сохраняется.
Добавьте запись Translation Config. В languages добавьте en_GB и fr_FR: для каждого задайте name, flag (код баннера), displayName (например, &3Francais), minecraftCodes (fr_FR, fr_CA) и при необходимости fallbackLanguages. Задайте mainLanguage равным en_GB.
Создайте plugins/Typewriter/Translate/messages.json с таким содержимым, затем опубликуйте или выполните /translate reload:

[
  {
    "type": "text",
    "key": "welcome.message",
    "languages": {
      "en_GB": "&6Welcome to the server, %1!",
      "fr_FR": "&6Bienvenue sur le serveur, %1 !"
    }
  }
]

Используйте <translate_key:welcome.message> в любом тексте MiniMessage с плейсхолдерами (диалог, голограмма, скорборд). Игрок, выполнивший /translate fr_FR, теперь видит французский текст.
Чтобы игроки могли выбирать из меню, постройте страницу меню с помощью расширения GUI, разместите на ней предметы translate_button:LANGUAGE#0, LANGUAGE#1..., укажите её в languageMenu конфигурации и запустите Open Language Selector.

примечание

Аргументы текста %1, %2 заполняются только кодом, вызывающим API перевода с аргументами. Плейсхолдер <translate_key:...> принимает только ключ, поэтому %1 остаётся там как написано.

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

Язык игрока определяется в таком порядке: сохранённый выбор, затем язык, соответствующий локали клиента (minecraftCodes), затем mainLanguage.

Файлы переводов

Файлы — это файлы .json непосредственно в папке переводов (translationsFolder, по умолчанию Translate, внутри plugins/Typewriter/). Каждый файл — это массив элементов; файл также может быть объектом, содержащим такой массив под ключом translations, items, languages, data или entries. Элементы без допустимых type и key пропускаются, а файл, который не удаётся разобрать, записывается в лог и игнорируется.

Элемент text содержит key и объект languages. Цветовые коды & преобразуются. Поиск ключа терпим: точный ключ, затем ключ с префиксами lang_, lang. или default., затем без учёта регистра, затем совпадение по части после последнего _ или ..

Элемент sign содержит locations (world, x, y, z) и lines для каждого языка. Читается до 8 строк, но показываются только первые 4 (лицевая сторона).

{
  "type": "sign",
  "key": "shop.sign",
  "locations": [{"world": "world", "x": 100, "y": 64, "z": 200}],
  "lines": {
    "en_GB": ["&b[Shop]", "&fClick to open", "", ""],
    "fr_FR": ["&b[Boutique]", "&fCliquez pour ouvrir", "", ""]
  }
}

Табличка переводится, когда игрок ставит или редактирует её в перечисленном месте или кликает по ней правой кнопкой; игрок видит на табличке свой язык через обновление на стороне клиента. Игроки, отключившие перевод табличек в меню настроек, видят оригинал.

Меню языка и настроек — это обычные записи open_gui расширения GUI. Translate предоставляет типы кнопок, которые размещаются на их предметах (поле типа кнопки у предмета GUI):

Тип кнопки	Поведение
`translate_button:LANGUAGE#<n>`	n-й язык из конфигурации (с 0). Показывает код и отметку на активном; левый клик выбирает его. Пусто после последнего языка.
`translate_button:TOGGLE_CHAT`	Показывает и переключает ИИ-перевод чата игрока (по умолчанию включён).
`translate_button:TOGGLE_SIGN`	Показывает и переключает перевод табличек игрока (по умолчанию включён).

Укажите страницы в Translation Config: languageMenu (и languageMenuViewId для конкретного представления) для выбора языка, settingsMenu (и settingsMenuViewId) для настроек. Открывайте их через Open Language Selector или Open Translation Settings. /translate menu открывает меню языка. Если задан openSelectorCommandOverride, вместо этого консоль выполняет эту команду ({player} заменяется именем игрока).

Выбор языка из меню требует артефакта Player Language: без него игроку сообщается, что выбор не будет сохранён. Переключателям также нужны артефакты Player AI Preference и Player Sign Preference.

ИИ-перевод чата

Настройте aiTranslation в Translation Config. Задайте enabled, выберите provider и укажите apiKey. Базовый URL и модель по умолчанию берутся у провайдера, если не заданы apiBaseUrl или model; OPENAI_COMPATIBLE требует apiBaseUrl. Предпочитайте env:VAR_NAME в качестве apiKey, чтобы читать ключ из переменной окружения, а не хранить его на странице.

Когда игрок пишет в чат, сообщение переводится на язык каждого зрителя, чей язык отличается от языка отправителя и у кого включён перевод чата. Переведённый текст заменяет сообщение в чате зрителя, а при наведении показывается оригинал. Чат ждёт переводы не дольше chatTranslationTimeoutMs (по умолчанию 800 мс), затем показывает непереведённое сообщение зрителям, которые всё ещё ждут. Сообщения, соответствующие noTranslateRegex (по умолчанию команды и чистые числа), не отправляются, текст, соответствующий censorRegex, заменяется на *** перед отправкой, а enabledSections должен содержать CHAT.

После трёх неудачных запросов подряд ИИ-перевод отключается до следующей перезагрузки переводов. Результаты кэшируются по сообщению и языку: в базе данных, если присутствует расширение MySQL, и в памяти в остальных случаях.

Команды

Команда — /translate, с псевдонимами /lang и /language. Её могут выполнять только игроки.

Команда	Описание
`/translate`	Показывает справку.
`/translate <language>`	Устанавливает ваш язык по его настроенному названию (например, `fr_FR`).
`/translate list`	Перечисляет настроенные языки и отмечает ваш.
`/translate menu`	Открывает выбор языка.
`/translate toggle_ai`	Переключает для вас ИИ-перевод чата.
`/translate sign set <key>`	Помечает табличку, на которую вы смотрите (в пределах 5 блоков), как переводимую с этим ключом. Требуется `typewriter.translate.admin`.
`/translate sign remove`	Снимает отметку с таблички. Требуется `typewriter.translate.admin`.
`/translate sign info`	Показывает ключ, местоположение и перевод таблички. Требуется `typewriter.translate.admin`.
`/translate reload`	Перезагружает файлы переводов. Требуется `typewriter.translate.admin`.

/translate sign set записывает на табличку только маркер и ключ. Сам текст берётся из элемента sign в файле JSON с местоположением таблички.

Права

Право	Что даёт
`typewriter.translate.admin`	`/translate reload` и `/translate sign ...`.

Плейсхолдеры

Расширение MiniPlaceholders translate, используется как теги MiniMessage. Переведённый текст может содержать разметку MiniMessage и вложенные плейсхолдеры.

Плейсхолдер	Возвращает
`<translate_key:some.key>`	Текст для этого ключа на языке зрителя. Если его нет, красным `[Translation not found: key]`.
`<translate_lang>`	Код языка зрителя, например `fr_FR`.
`<translate_lang_display>`	Отображаемое название языка.
`<translate_lang_flag>`	Код флага-баннера языка.
`<translate_count>`	Число загруженных переводов (тексты плюс таблички).
`<translate_languages>`	Число настроенных языков.

Записи

Записей: 10, сгенерированы из исходного кода расширения.

Действия4

Open Language Selector ActionOpen the language selection menu
Open Translation Settings ActionOpen the translation settings menu
Reload Translations ActionReload translation files from disk
Set Language ActionSet a player's translation language

События1

Player Language Change EventTriggered when a player changes their language

Факты1

Player Language FactReturns the player's current language as a numeric value

Артефакты3

Player Ai Preference ArtifactStores player AI translation preferences
Player Language ArtifactStores player language preferences
Player Sign Preference ArtifactStores player sign translation preferences

Манифесты1

Translation ConfigConfigure the multi-language translation system

Устранение неполадок

Появляется [Translation not found: key]. Ключа нет ни в одном загруженном файле либо файл не удалось загрузить. Проверьте в логе сервера Failed to load translation file, проверьте валидность JSON и выполните /translate reload. Убедитесь, что файл лежит непосредственно в plugins/Typewriter/Translate/ (вложенные папки не читаются) и имеет расширение .json.

Язык сбрасывается при каждом входе. Не опубликован артефакт Player Language, поэтому выбор не сохраняется. Добавьте его.

Меню ничего не делает. В логе написано No 'languageMenu' configured или No 'settingsMenu' configured: задайте страницу меню в Translation Config. Для меню языка openSelectorCommandOverride имеет приоритет, когда он не пуст.

Язык не следует за языком клиента. Без сохранённого выбора локаль клиента используется автоматически, если она присутствует в minecraftCodes какого-либо языка. forceClientLocaleOnJoin дополнительно переключает игрока и перезаписывает его сохранённый выбор всякий раз, когда клиент сообщает об изменении локали, совпадающей с другим языком.

ИИ-перевод перестал работать. Ищите в логе AUTOMATICALLY DISABLED: три последовательных сбоя API отключают его. Исправьте ключ, URL или модель, затем выполните /translate reload. apiKey references env var ... not set означает, что переменная окружения отсутствует.

Табличка не переводится. Табличка должна находиться ровно в координатах, перечисленных в элементе sign файла JSON, в мире с правильным названием. У игрока не должен быть отключён перевод табличек, а табличка переводится при установке или правом клике.

Связанные расширения

TinyEssentials — его формат чата сохраняется, когда ИИ-перевод оборачивает отрисовщик чата.
MySQL — постоянный кэш ИИ-перевода.

Обзор​

Возможности​

Установка​

Начало работы​

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

Файлы переводов​

Меню​

ИИ-перевод чата​

Команды​

Права​

Плейсхолдеры​

Записи​

Устранение неполадок​

Связанные расширения​