UniversalModLocalizer

UniversalModLocalizer

Translate Valheim mods without editing their files. Export texts, translate them, import them back and keep every mod neatly separated.

---

English

UniversalModLocalizer is a translation tool for modded Valheim.

It was created to make translating mods easier without having to manually edit DLL files or modify the original files of each mod.

The mod scans installed BepInEx plugins, finds translatable content and exports it into simple JSON files that can be edited with any text editor or translation tool.

Each detected mod gets its own folder based on its BepInEx plugin GUID, so translations from different mods stay separated and are much easier to manage.

Once your translation is ready, place it in the corresponding import folder and reload it directly in-game.

Features

• Separate translation folders for every detected mod.
• Simple UTF-8 JSON translation files.
• Automatic detection of installed BepInEx plugins.
• Reads existing JSON, YAML/YML, CSV, TSV and TXT localization files.
• Standard scan with uml scan.
• Deeper visible-content scan with uml deep.
• Reload translations without restarting the game using uml reload.
• Runtime translation support for hardcoded UI text.
• Support for TMP_Text and Unity UI Text.
• Support for simple dynamic text templates and placeholders.
• Prefab scanning for items, creatures, building pieces, effects and other visible content.
• Server-to-client translation synchronization.
• Local cache for synchronized server translations.
• Protection for original Valheim localization tokens.
• More tolerant JSON loading for common formatting mistakes.
• Runtime translation caching for better performance.
• Does not modify mod DLLs, save files, worlds or original localization files.

Improved Runtime Performance

UniversalModLocalizer is designed to stay lightweight during normal gameplay.

More expensive ownership detection is mainly used when manually running uml scan or uml deep, while normal runtime UI translation uses a faster cached lookup system.

This significantly reduces the performance impact of runtime text translation, especially in heavily modded setups with many UI elements.

For unusual cases where multiple mods use the same hardcoded UI text with different translations, the optional:

EnableScopedRuntimeComponentLookup

setting can enable more precise owner-based matching.

It is disabled by default because the faster lookup method is recommended for normal gameplay.

Vanilla Translation Protection

Some mods reuse localization tokens that already belong to Valheim, for example:

$item_hammer $item_club $piece_fire

UniversalModLocalizer protects these tokens so Valheim can continue using its original localization instead of replacing it with an incorrect translation from a mod package.

Protected tokens are stored in:

BepInEx/config/UniversalModLocalizer/vanilla_tokens.txt

The list can also be edited manually if additional tokens need to be protected.

Commands

uml scan

Runs the standard translation scan and exports detected strings.

uml deep

Performs a deeper scan of visible modded content, including loaded UI elements and additional prefab data.

This mode can find strings that may not be detected during a normal scan.

uml reload

Reloads translation files from the import folders without requiring a full game restart.

uml status

Shows the currently selected language, loaded translations and configuration location.

uml language Polish

Changes the target translation language.

You can also use:

uml language Auto

to automatically use the language currently selected in Valheim.

uml runtime on

Enables collection of hardcoded runtime UI strings while browsing mod menus, HUD elements and other interfaces.

How to use

1. Install UniversalModLocalizer using r2modman or manually place it inside:

BepInEx/plugins

1. Start Valheim and enter a world.

1. Open the console and run:

uml scan

or:

uml deep

1. Exported files can be found under:

BepInEx/config/UniversalModLocalizer/export/<Language>/<ModGUID>/

1. Translate the values inside the JSON files.

1. Place the completed translation files under:

BepInEx/config/UniversalModLocalizer/import/<Language>/<ModGUID>/

1. Run:

uml reload

or restart Valheim.

Existing export files are merged instead of overwritten, so running another scan will add newly detected strings without deleting your previous work.

Example

Exported JSON:

{
  "$item_fire_sword": "Flaming Sword",
  "$item_fire_sword_description": "A sword engulfed in flame",
  "Ability is not ready": "Ability is not ready"
}

Polish translation:

{
  "$item_fire_sword": "Płonący Miecz",
  "$item_fire_sword_description": "Miecz spowity płomieniami",
  "Ability is not ready": "Umiejętność nie jest gotowa"
}

Translate only the values on the right side.

Keep the keys on the left unchanged.

Dynamic UI Text

UniversalModLocalizer can also handle simple text templates containing changing values.

For example:

{
  "source": "You have {{$count}} skill points",
  "translation": "Masz {{$count}} punktów umiejętności",
  "category": "ui"
}

Common placeholder formats such as:

{{count}} {{$count}} {0} %s %d

are supported.

The mod can also warn when a translation is missing a placeholder that exists in the original text.

Multiplayer

UniversalModLocalizer can synchronize completed translation packages from a dedicated server to connected clients.

The server sends translations only when the client's cached version is different, reducing unnecessary transfers.

Clients can therefore automatically receive the translation package used by the server.

The UniversalModLocalizer plugin still needs to be installed on the client for runtime UI translations.

Compatibility