PyMcTranslate

1.2.43 verified Fri May 01 auth: no python

PyMcTranslate is a Python library for translating Minecraft data files (e.g., block state mappings, item IDs) between different Minecraft versions. It automates the conversion of data structures used by tools and mods, supporting versioned translation maps. Current version 1.2.43, release cadence is irregular.

pip install pymctranslate

Common errors

error ModuleNotFoundError: No module named 'pymctranslate' ↓

cause Installed in a Python environment lower than 3.10 or pip not found.

fix

Ensure Python >=3.10 and install via pip: pip install pymctranslate

error ValueError: Cannot find translation for 'minecraft:stone' from 1.12.2 to 1.16.5 ↓

cause Translation maps not downloaded or outdated; or the identifier does not exist in source version.

fix

Run manager.update() to download latest maps. Verify the identifier is correct for the source version (e.g., 'minecraft:stone' exists in 1.12.2).

error AttributeError: 'TranslationManager' object has no attribute 'translate_slot' ↓

cause Using deprecated method name that was removed in recent version.

fix

Use manager.translate(identifier, source, target, slot='...') instead.

Warnings

breaking Translation maps are stored in local cache. If cache is outdated or missing, translation may fail or return original identifier. Always call manager.update() to refresh maps before first use. ↓

fix Call manager.update() after initialization to ensure latest maps.

gotcha The library uses semantic versioning for Minecraft versions (e.g., '1.12.2'). Do not include 'minecraft:' prefix in the version string; only the numeric version. ↓

fix Use string like '1.12.2', not '1.12' or 'minecraft 1.12.2'.

deprecated The method 'translate_slot' has been deprecated since v1.2.0, use 'translate' with appropriate slot parameter instead. ↓

fix Replace manager.translate_slot(...) with manager.translate(..., slot=...).

Imports

TranslationManager

wrong

from pymctranslate import Translator

correct

from pymctranslate import TranslationManager

The main class is TranslationManager, not Translator.

Quickstart

Initialize a TranslationManager and use .translate() to convert identifiers between versions.

from pymctranslate import TranslationManager

manager = TranslationManager()
# Translate block 'minecraft:stone' from version 1.12.2 to 1.16.5
translated = manager.translate('minecraft:stone', source='1.12.2', target='1.16.5')
print(translated)
# Output: 'minecraft:stone' (or block state data)