Compatibility en US

Compatibility Guide

This is the retained manual reference. Start with Export and Translate for the shorter workflow.

Home · 中文 · Key Reference

Reuse Existing Translations

Items, blocks, entities, attributes, potions, effects and enchantments use the registered objects' existing names or description components where available. A translated Create cogwheel does not need a second item dictionary.

Usually, only a namespace name needs adding:

{
  "command_translation.namespace.create": "Create"
}

Namespace lookup checks command_translation.namespace.<modid>, modmenu.nameTranslation.<modid>, then <modid>.ponder.mod_name. It falls back to the raw modid. Input, suggestions and tooltips share this name, for example Create:Large Cogwheel. Conflicting names within the same domain receive the original ID, as in Create:Large Cogwheel(create:large_cogwheel).

Language File Location

A resource pack adds keys in assets/command_translation/lang/<locale>.json. A mod can put the same keys in its own assets/<modid>/lang/<locale>.json; Minecraft merges the loaded language tables.

command-translation-compat/
  pack.mcmeta
  assets/
    command_translation/
      lang/
        en_us.json
        zh_cn.json

This pack.mcmeta example targets 26.2:

{
  "pack": {
    "description": "Command Translation compatibility",
    "min_format": [88, 0],
    "max_format": [88, 0]
  }
}

Use the matching resource-pack declaration for other targets. These values come from each game's vanilla version.json, not its data-pack format:

Minecraft	Resource-pack declaration
1.20.1	"pack_format": 15
1.21.1	"pack_format": 34
26.1.2	"min_format": [84, 0], "max_format": [84, 0]
26.2	"min_format": [88, 0], "max_format": [88, 0]

For older versions, put the listed pack_format beside description inside pack, replacing min_format and max_format. A ZIP must contain pack.mcmeta at its root. Enable the pack and reload client resources to update the language entries.

Keep English text and registry bindings in en_us.json, with translations in their respective locale files. Missing entries follow vanilla's English fallback. English and the current language coexist in suggestions and input.

Commands, Subcommands and Fixed Values

Use original node paths in alias keys. Separate alternatives with |. Alias entries contain no spaces; Command Translation adds the namespace prefix.

{
  "command_translation.command.give.alias": "give",
  "command_translation.literal.execute.if.alias": "if",
  "command_translation.value.creative.alias": "creative",
  "command_translation.help.command.give": "Give items to players.",
  "command_translation.help.argument.give.targets": "Players receiving the items.",
  "command_translation.help.argument.give.targets.item.count": "Number of items given to each player.",
  "command_translation.syntax.argument.give.targets": "Target players",
  "command_translation.syntax.argument.give.targets.item.count": "Count"
}

With suitable Chinese entries, /我的世界:给予 is the namespaced form of /give. Original English and existing unqualified aliases remain available. Complete, unambiguous names resolve to original tokens; fragments of descriptions are for searching, not for guessing which command to execute.

For an unqualified mod command such as /device status, declare its owner. The following uses the illustrative modid example:

{
  "command_translation.namespace.example": "Example Mod",
  "command_translation.command.device.namespace": "example",
  "command_translation.command.device.alias": "device",
  "command_translation.literal.device.status.alias": "status",
  "command_translation.help.command.device": "Inspect or change the device state."
}

If the original root is example:device, use command_translation.command.example:device.alias and the corresponding example:device.status subcommand path instead. No owner declaration is needed. Only the vanilla minecraft: root prefix is normalized to the unqualified vanilla documentation path.

Argument names are Brigadier node names, not necessarily the displayed placeholders. The full give-count path is give.targets.item.count. English syntax comes from the live command tree; translations supply the small annotations and parameter explanations.

Tags, Resources and Effects

Existing tag translations remain usable. Replace slashes in registry and resource paths with dots for tag language keys:

{
  "command_translation.tag.item.example.metal_parts": "Metal parts",
  "command_translation.tag.worldgen.biome.example.cold_places": "Cold biomes",
  "command_translation.registry.example:mode.example:quiet.name": "Quiet mode",
  "command_translation.help.registry.example:mode.example:quiet": "The device runs without its work sounds."
}

The custom mode above is an API example, not a built-in behavior. Document what your mod actually does. Item, block and biome tags with the same ID need separate registry-specific entries.

General resource-name overrides use command_translation.registry.<registry ID>.<resource ID>.name. Keep full IDs, including colons and slashes. The dot conversion above applies to tag keys.

Effect summaries use command_translation.help.registry.minecraft:mob_effect.<effect ID>; effect names still come from existing translations.

NBT, Components and Values

Language entries add names and help. They do not create components, commands or NBT completion schemas. Suggestions come from vanilla or bundled NBT Autocomplete; describe custom structures through the completion provider's own integration.

{
  "command_translation.help.component.example:device": "Device operating settings.",
  "command_translation.help.component.example:device.field.mode": "The device's operating mode.",
  "command_translation.help.component.example:device.field.mode.registry": "example:mode",
  "command_translation.help.component.example:device.field.rules.*.enabled": "Whether this rule is enabled.",
  "command_translation.help.component.example:device.field.rules.*.enabled.value_type": "device_enabled",
  "command_translation.help.value.type.device_enabled.true": "Enable this rule.",
  "command_translation.help.value.type.device_enabled.false": "Disable this rule.",
  "command_translation.help.component.example:device.field.mode.value.example:quiet": "Run this device in quiet mode."
}

Here, rules is a dictionary keyed by rule names. A * matches one member. Array indices are omitted from field paths. Lookup tries exact paths, single-member wildcards, then consecutive trailing wildcards; * is not an arbitrary-depth recursive match.

An exact field-value entry overrides the shared .value_type entry. Use .registry for registry values and .key_registry when dictionary keys themselves are IDs, such as enchantments. Binding values are raw code IDs and must not be translated. A component's direct value uses component.<ID>.registry, without .field.

Legacy item NBT uses the nbt.item family; entities use nbt.entity, and block entities use nbt.block_entity:

{
  "command_translation.help.nbt.item.field.Unbreakable": "Whether the item avoids durability loss.",
  "command_translation.help.nbt.item.field.Unbreakable.value.1b": "The item does not lose durability.",
  "command_translation.help.nbt.item.field.Unbreakable.value.0b": "The item loses durability normally."
}

Selectors, block states, text components and particles use selector, block_state, text and particle.<particle ID>. See the Key Reference for the full key shapes.

Developer Integration

• Keep the original Brigadier tree, redirects, permissions and suggestion callbacks. Do not register another set of translated server commands.
• Supply normal registry-object names and synchronized argument metadata. Custom suggestions should retain correct replacement ranges, tooltips and original values.
• When an argument has no native registry metadata, command_translation.help.argument.<full path>.registry can bind a registry for documentation lookup. It does not implement an argument parser or replace the suggestion provider.
• Item details reuse native tooltips and item callbacks. Entity information reads registered defaults without spawning entities. Keep those existing integration points.
• Ship language resources with your mod or resource pack. There is no need to link against internal Command Translation Java classes.

Before Distributing

Check resource-pack order, locale filenames, and English fallback entries. Check both suggestions and entered text. English forms, localized forms, tags and specific values should identify the same original token. Preserve full-ID disambiguation suffixes instead of assigning the same alias to different objects.

See Configuration. Vanilla meanings come from Minecraft Wiki and loader tags use official sources; keep the required attribution and licenses when reusing that material. Describe custom content from its actual implementation.