WTEM

WTEM (World Translation Extractor Mod)

English | 中文 WTEM — это клиентский мод для Fabric, который превращает захардкоженный текст в мирах Minecraft, датапаках мира и структурах, сгенерированных миром, в ключи перевода и записывает соответствующие записи i18n. Поддерживает несколько версий Minecraft. Часть этого мода создана с помощью ИИ. Использованные ИИ-инструменты: gpt-5.6-sol и claude-opus-5.

Поддерживаемые версии

Использование

1. Поместите файл мода для вашей версии Minecraft в директорию mods клиента.
2. Запустите игру, выберите нужный мир в списке миров одиночной игры и откройте страницу «Редактировать».
3. Нажмите кнопку «Extract».
4. Создайте резервную копию на странице подтверждения резервного копирования. Всегда делать резервную копию настоятельно рекомендуется; извлечение изменяет данные мира на месте.
5. Дождитесь завершения извлечения. На экране отображается прогресс по чанкам и количество предупреждений; подробности — в логе игры. Извлечение можно отменить после начала. Чанки, SavedData и структуры, уже записанные до отмены или до ошибки, не откатываются, поэтому сначала сделайте резервную копию.

Что извлекается

Данные сохранения:

• Текст блок-энтити в чанках, например названия контейнеров, таблички и вывод командных блоков.
• Текст в сущностях и их вложенных данных: пассажиры, снаряжение, инвентари, сделки жителей.
• Отображаемые имена команд, целей и очков таблицы счёта.
• Имена пользовательских босс-баров.
• NBT-структуры, фактически присутствующие в `generated//structure(s)` мира.
• Каждый неванильный сжатый файл SavedData *.dat ниже директории data/ мира, включая вложенные пользовательские файлы, с консервативным определением полей и фильтрацией по файлу/пути. Каждая NBT-строка в выбранной области записывает предупреждение saved_data_string; извлекаются только строки, определённые как текстовые компоненты. Распознаваемые имена полей настраиваются через saved_data_text_fields (по умолчанию включает back_text). Датапаки:
• Известные текстовые поля в достижениях, зачарованиях, песнях музыкальных блоков, шаблонах брони, картинах, инструментах, диалогах и типах измерений (например, attributes.minecraft:gameplay/bed_rule.error_message).
• Переводимые текстовые компоненты в модификаторах предметов, таблицах добычи и предикатах.
• Текст сущностей, блок-энтити и предметов в NBT-структурах.
• Аргументы текстовых компонентов в функциях, текст сущностей в аргументе nbt команды summon, а также аргументы, которые парсятся как предмет или блок-энтити, например компоненты предмета в give и NBT блок-энтити в setblock и fill.

Вывод

Завершённое извлечение может создать:

• `/en_us.json`: сопоставление ключей перевода с исходным текстом.
• `/en_us.csv`: отчёт об извлечении, фиксирующий, где был найден каждый фрагмент текста. См. следующий раздел.
• `/datapacks/__wtem/`: переопределяющий датапак, парный к оригинальному датапаку мира.
• Стандартный клиентский ресурспак resources.zip в `/до 26.1 и в/resourcepacks/` в 26.1 и новее.
• Изменённые блок-энтити, сущности, таблицу счёта, bossbar и структуры, где захардкоженные текстовые компоненты заменены на компоненты translate. WTEM не изменяет оригинальный датапак мира. Сгенерированный новый датапак сохранит только фактически изменённые ресурсы и pack.mcmeta. Перед повторным входом в мир убедитесь в настройках датапаков, что оверлейный пак включён и находится выше оригинального пака.

Отчёт об извлечении

Извлечение также экспортирует отчёт, названный по имени языкового файла с суффиксом .csv. Его столбцы:

Ключ, встречающийся в нескольких местах, имеет одну запись в языковом файле, но одну строку отчёта на каждое вхождение, поэтому в отчёте обычно больше строк, чем записей в языковом файле. Если извлечение отменено или прервано на середине, уже записанная часть экспортируется вместе с языковым файлом.

Типы предупреждений

Предупреждения — это несмертельные диагностические сообщения. Каждое предупреждение включает свой тип и исходный файл, resource ID, команду или NBT-путь, вызвавший его. Приведённые ниже предупреждения обозначают случаи, требующие проверки или которые не удалось безопасно переписать.

Конфигурация

При первом запуске создаётся конфиг по умолчанию в config/wtem.json, где каждая опция прописана со значением по умолчанию, чтобы её можно было редактировать напрямую. Каждая опция необязательна: если удалить её или не указывать, сохранится поведение по умолчанию. Также можно открыть интерфейс конфигурации YACL, нажав кнопку Configuration на экране извлечения. Кнопка Select sources на экране извлечения открывает экран YACL для датапаков, файлов SavedData и типов сущностей/блоков-сущностей. Кнопка Configuration зарезервирована для остальных настроек извлечения. Внешнее редактирование wtem.json автоматически подхватывается на лету. Запущенное извлечение сохраняет свой снимок состояния на момент запуска, поэтому изменения применяются к следующему запуску.

{
  "stages": {
    "region": true,
    "entities": true,
    "scoreboard": true,
    "boss_bar": true,
    "datapacks": true,
    "generated_structures": true,
    "storage": true
  },
  "resources": {
    "advancement": true,
    "enchantment": true,
    "jukebox_song": true,
    "trim_material": true,
    "trim_pattern": true,
    "painting_variant": true,
    "instrument": true,
    "dialog": true,
    "dimension_type": true,
    "item_modifier": true,
    "loot_table": true,
    "predicate": true,
    "function": true,
    "structure": true
  },
  "key_reuse": {
    "default": true,
    "overrides": {}
  },
  "key_naming": {
    "scheme": "structured",
    "random_length": 8
  },
  "nbt_max_depth": 32,
  "rebuild_nested_keys": false,
  "skipped": {
    "command_block_output": true,
    "filtered_text": true
  },
  "skipped_paths": [
    "animated_java:function"
  ],
  "builtin_entries": {
    "wtem.blank": "",
    "wtem.space": " ",
    "wtem.0": "0",
    "wtem.1": "1",
    "wtem.2": "2",
    "wtem.3": "3",
    "wtem.4": "4",
    "wtem.5": "5",
    "wtem.6": "6",
    "wtem.7": "7",
    "wtem.8": "8",
    "wtem.9": "9"
  },
  "language_file": "en_us.json",
  "saved_data_text_fields": [
    "name",
    "custom_name",
    "customname",
    "title",
    "subtitle",
    "description",
    "text",
    "message",
    "label",
    "display_name",
    "displayname",
    "lore",
    "messages",
    "pages",
    "lines",
    "raw",
    "front_text",
    "back_text",
    "prompt",
    "tooltip",
    "error_message"
  ],
  "filters": {
    "region": [],
    "datapack": [],
    "storage": [],
    "entity": [],
    "block_entity": [],
    "selection": {
      "datapacks": [],
      "entities": [],
      "block_entities": [],
      "storage_files": []
    }
  },
  "outputs": {
    "export_region_snbt": false,
    "export_schema": false,
    "region_snbt_directory": "wtem/regions",
    "schema_file": "wtem-schema.json"
  },
  "ai_translation": {
    "enabled": false,
    "endpoint": "https://api.deepseek.com",
    "api_key": "",
    "model": "deepseek-v4-flash",
    "target_language": "zh-CN",
    "output_file": "zh_cn.json",
    "timeout_seconds": 60,
    "protocol": "responses",
    "translation_prompt": "Translate the values of the supplied JSON object into {target_language}. Return only one JSON object with exactly the same keys. Preserve Minecraft formatting codes, placeholders such as %s and %1$s, escape sequences, whitespace, and intentional line breaks. Do not translate JSON keys, commands, identifiers, or formatting tokens.",
    "key_naming_prompt": "Create one concise semantic Minecraft translation key for the supplied text and suggested_path. Return only a JSON object in the form {\"key\":\"...\"}. Use lowercase ASCII letters, digits, underscores, and dots only. Prefer the source category (item, entity, block, sign, book, or datapack) as the first segment and preserve the semantic role such as .name, .title, or .description as the last segment. Translate the meaning into concise English key words even when the visible text is in another language. Describe the visible text rather than the material id: for example, The Best Sword on a wooden sword should be item.the_best_sword.name. Never include numeric occurrence indexes."
  },
  "resource_pack": {
    "enabled": true,
    "format": "zip",
    "name": "resources.zip",
    "description": "WTEM translations",
    "pack_format": 0
  }
}

• stages: переключатели для каждого этапа извлечения. region — это блок-энтити в чанках, entities — чанки с сущностями, storage рекурсивно читает все *.dat ниже data/, а остальные — это таблица очков, боссбары, датапаки мира и сгенерированные миром структуры.
• resources: переключатели для каждого типа ресурсов датапака, с ключом по имени директории реестра. Сгенерированный файл перечисляет все типы, которые реально поддерживает текущая версия; тип, которого в списке нет, считается включённым.
• key_reuse: переиспользует ли одинаковый текст существующий ключ перевода. default — это глобальная политика, а overrides переопределяет её по префиксу ключа, причём побеждает самое длинное совпадение. Чтобы переводить один и тот же текст отдельно в разных местах, поставь соответствующий префикс в false, например {"datapack.": false}.
• key_naming: как именуются ключи перевода. См. ниже.
• nbt_max_depth: предел рекурсии для извлечения NBT, который не даёт взаимно вложенным предметам и подобному переполнить стек. Каждый вложенный предмет, сущность или блок-энтити стоит один уровень, а данные за пределом остаются как есть. Значение меньше 1 считается значением по умолчанию.
• rebuild_nested_keys: именует ли block_entity_data на предмете себя с нуля. По умолчанию false, поэтому, не считая переиспользования, деревянный меч внутри шалкера получает ключ вроде item.shulker_box.1.container.wooden_sword.1.name. При true вложенные предметы начинают свой ключ заново и дают ключ вроде item.wooden_sword.1.name.
• skipped: текст, который можно перевести, но обычно не нужно. См. ниже.
• skipped_paths: пропускает ресурсы ниже выбранных директорий под data/; пропущенные ресурсы не записываются в сопутствующий пак. Форма расположения ресурса такая: `:: animated_java:functionсовпадает сdata/animated_java/function/*. :function/generatedсовпадает с этой директорией во всех неймспейсах, а путь ресурса*` пропускает целый неймспейс.

• builtin_entries: записи, заранее добавленные в языковой файл. Извлечённый текст, совпадающий с одной из них, переиспользует её ключ вместо того, чтобы получать свой собственный. Значения по умолчанию добавляют пустую строку, пробел и 0~9: текст без значения перевода, который тем не менее постоянно появляется (пустые строки на табличке, числа на таблице очков), после добавления занимает по одной строке. Пустой объект {} ничего не добавляет; удаление всей опции сохраняет значения по умолчанию.

• language_file: имя языкового файла, записываемого в каталог мира. Принимается только простое имя файла; имя, содержащее разделитель пути или не заканчивающееся на .json, игнорируется.
• saved_data_text_fields: имена полей, используемые для определения вероятных текстовых компонентов при сканировании SavedData. Список по умолчанию включает back_text; все остальные строки в выбранной области SavedData сохраняются и сообщаются как saved_data_string, а не угадываются как текст.
• filters: унифицированные фильтры источников. Обычное правило включает местоположение, ! исключает его, а */? — подстановочные знаки; исключения всегда побеждают. Местоположения регионов — dimension/chunk/x_z, местоположения наборов данных — pack/namespace:path, местоположения SavedData — `.dat/`, а фильтры сущностей сопоставляются с полными именами типов с пространством имён.
• filters.selection: точные варианты, сохранённые экраном извлечения. Наборы данных и файлы SavedData обнаруживаются из текущего мира. Варианты сущностей и блочных сущностей берутся из реестров текущей версии. Пустой список означает все текущие. Снятие галочки со всех пунктов сохраняет внутренний маркер ["!none"], что явно означает «ничего».
• outputs: включает пофайловые SNBT-файлы для каждого чанка в region_snbt_directory относительно мира и файл схемы JSON.
• ai_translation: при включении отправляет полный каталог одним запросом на совместимую с OpenAI конечную точку Responses или chat-completions. Вы можете ввести либо BaseURL, либо полный URL /responses или /chat/completions; protocol выбирает протокол, когда используется BaseURL. translation_prompt поддерживает плейсхолдер {target_language}, а key_naming_prompt управляет необязательным семантическим именованием ключей с помощью ИИ.
• resource_pack: при включении записывает папку, ZIP или и то и другое, используя только настроенное name набора. Набор содержит pack.mcmeta и каталоги assets/wtem/lang/.

Пропускаемый текст

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

• command_block_output: кэшированный результат последнего выполнения командного блока или вагонетки с командным блоком (LastOutput).
• filtered_text: отфильтрованная чатом копия строк табличек и страниц написанных книг (filtered_messages / filtered).

Схемы именования ключей

• scheme:

  • structured (по умолчанию): читаемые ключи, производные от места извлечения, например entity.zombie.1.name. Поскольку извлечение неупорядочено, повторное извлечение не гарантирует согласованность.
  • hashed: ключи, производные от hash места извлечения, вида `wtem.`. Повторное извлечение из того же сохранения даёт те же ключи.
  • random: случайные буквы, вида `wtem.`. Ключ не связан с местом извлечения, и повторное извлечение не гарантирует согласованность.
  • ai: отправляет оригинальный текст и предложенный исходный путь на настроенную совместимую с OpenAI конечную точку. Например, деревянный меч с именем The Best Sword может стать item.the_best_sword.name. Ответы должны быть допустимыми ключами с точками.
• random_length: сколько случайных букв использует схема random. По умолчанию 8.

Разработка и сборка

Активный проект репозитория по умолчанию — 26.2.x. До и после редактирования общих исходников используйте задачи переключения Stonecutter, чтобы сгенерировать исходники для нужной версии. Пример для PowerShell:

.\gradlew.bat "Set active project to 1.21.11"
.\gradlew.bat :1.21.11:compileJava :1.21.11:compileTestJava :1.21.11:test :1.21.11:validateAccessWidener

Сборка и сбор релизного JAR для одной версии (26.2.x):

.\gradlew.bat "Set active project to 26.2.x"
.\gradlew.bat :26.2.x:buildAndCollect

Результат попадает в `build/libs//`. Перед коммитом выполните:

.\gradlew.bat "Reset active project"

что восстанавливает общие исходники до состояния 26.2.x, под которое настроен репозиторий. Чтобы собрать все версии сразу:

.\gradlew.bat buildAll

Лицензия и благодарности

Этот проект использует CC BY 4.0. Вы можете копировать, изменять и распространять его, в том числе коммерчески, при условии сохранения атрибуции. Атрибуция означает указание автора, ссылку на этот проект, указание лицензии (CC BY 4.0, с её текстом или ссылкой) и упоминание, изменили ли вы что-либо. При распространении мода или изменённой версии прикладывайте LICENSE и NOTICE. Распространение результатов работы инструмента также требует атрибуции. Когда вы публикуете языковой файл, отчёт об извлечении или сгенерированные наборы данных — отдельно или внутри мира — укажите, что эти файлы созданы WTEM, и приведите атрибуцию выше. Это касается только сгенерированных файлов, а не мира, из которого извлекали, переводов или чего-либо ещё, что вы распространяете вместе с ними. Вдохновлено WorldTranslationExtractor.