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. UniversalModLocalizer scans installed BepInEx plugins, collects translatable text 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 easier to manage.

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

Features

• Separate translation folders for every detected mod.
• Simple UTF-8 JSON translation files.
• Automatic detection of installed BepInEx plugins.
• Standard scan with uml scan.
• Deeper content scan with uml deep.
• Reload translations without restarting the game using uml reload.
• Runtime translation support for UI text.
• Support for TMP_Text and Unity UI Text.
• Server-to-client translation synchronization.
• More tolerant JSON loading for common formatting mistakes.
• Protection for original Valheim localization tokens.
• Does not modify mod DLLs, save files, worlds or original localization files.

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 the game can continue using the original Valheim translation instead of replacing it with an incorrect mod translation.

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. This mode can find additional 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.

How to use

1. Install UniversalModLocalizer using r2modman or manually place it inside BepInEx/plugins.
2. Start Valheim and enter a world.
3. 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.

2. Place the completed translation files under:

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

1. Run:

uml reload

or restart Valheim.

Example

Exported JSON:

{
  "$example_sword": "Ancient Sword",
  "$example_sword_description": "An old sword from a forgotten age."
}

Polish translation:

{
  "$example_sword": "Starożytny Miecz",
  "$example_sword_description": "Stary miecz pochodzący z zapomnianych czasów."
}

Only translate the values. Keep the keys unchanged.

Multiplayer

UniversalModLocalizer can synchronize translation packages from the server to connected clients.

This makes it easier to use one shared translation setup across a modded multiplayer server.

Compatibility

UniversalModLocalizer works best with mods using standard Valheim localization tokens, Jotunn, prefabs or normal Unity/TMP interface elements.

Because every mod can implement its interface differently, some highly customized UI systems may require additional compatibility support.

Dependencies

• BepInExPack Valheim
• Jotunn

AI Disclosure

UniversalModLocalizer was developed with assistance from OpenAI Codex.

The generated code was tested and adjusted locally in a Valheim/BepInEx environment.

Polski

Tłumacz mody do Valheim bez edytowania ich plików. Eksportuj teksty, tłumacz je i importuj z powrotem, zachowując osobne pliki dla każdego moda.

UniversalModLocalizer to narzędzie stworzone z myślą o tłumaczeniu modowanego Valheima.

Pozwala zbierać teksty z zainstalowanych modów BepInEx i eksportować je do prostych plików JSON, które można później przetłumaczyć w dowolnym edytorze tekstu lub za pomocą zewnętrznych narzędzi tłumaczeniowych.

Nie trzeba przy tym edytować DLL ani oryginalnych plików modów.

Każdy wykryty mod otrzymuje osobny folder oparty na jego GUID BepInEx, dzięki czemu tłumaczenia różnych modów nie mieszają się ze sobą i można nimi łatwo zarządzać.

Po przygotowaniu tłumaczenia wystarczy umieścić plik w odpowiednim folderze import i przeładować tłumaczenia bezpośrednio w grze.

Najważniejsze funkcje

• Osobny folder tłumaczeń dla każdego moda.
• Proste pliki JSON UTF-8.
• Automatyczne wykrywanie zainstalowanych pluginów BepInEx.
• Standardowe skanowanie komendą uml scan.
• Dokładniejsze skanowanie zawartości za pomocą uml deep.
• Przeładowanie tłumaczeń bez restartowania gry dzięki uml reload.
• Obsługa tekstów UI tworzonych podczas działania gry.
• Obsługa TMP_Text oraz Unity UI Text.
• Synchronizacja tłumaczeń pomiędzy serwerem a klientami.
• Tolerancyjne wczytywanie plików JSON przy typowych błędach formatowania.
• Ochrona oryginalnych tokenów lokalizacyjnych Valheima.
• Brak ingerencji w DLL modów, zapisy gry, światy oraz oryginalne pliki lokalizacyjne.

Ochrona tłumaczeń Valheima

Niektóre mody wykorzystują tokeny, które należą już do podstawowej wersji Valheima, na przykład:

$item_hammer $item_club $piece_fire

UniversalModLocalizer chroni takie tokeny, dzięki czemu Valheim może nadal korzystać ze swojego oryginalnego tłumaczenia zamiast zastępować je niepoprawnym wpisem pochodzącym z tłumaczenia moda.

Lista chronionych tokenów znajduje się tutaj:

BepInEx/config/UniversalModLocalizer/vanilla_tokens.txt

W razie potrzeby można ją również ręcznie rozszerzyć.

Komendy

uml scan

Uruchamia standardowe skanowanie i eksportuje wykryte teksty.

uml deep

Wykonuje dokładniejsze skanowanie widocznych treści modów. Pozwala znaleźć dodatkowe teksty, których standardowe skanowanie może nie wykryć.

uml reload

Ponownie wczytuje tłumaczenia z folderu import bez konieczności restartowania gry.

Jak używać

1. Zainstaluj UniversalModLocalizer przez r2modman albo ręcznie w folderze BepInEx/plugins.

2. Uruchom Valheim i wejdź do świata.

3. Otwórz konsolę i wpisz:

uml scan

lub:

uml deep

1. Wyeksportowane pliki znajdziesz w:

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

1. Przetłumacz wartości znajdujące się w plikach JSON.

2. Gotowe pliki umieść w:

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

1. Wpisz:

uml reload

lub uruchom Valheim ponownie.

Przykład

Wyeksportowany plik:

{
  "$example_sword": "Ancient Sword",
  "$example_sword_description": "An old sword from a forgotten age."
}

Polskie tłumaczenie:

{
  "$example_sword": "Starożytny Miecz",
  "$example_sword_description": "Stary miecz pochodzący z zapomnianych czasów."
}

Tłumacz tylko wartości. Klucze powinny pozostać bez zmian.

Multiplayer

UniversalModLocalizer może synchronizować paczki tłumaczeń z serwera do podłączonych klientów.

Pozwala to korzystać z jednego zestawu tłumaczeń na całym modowanym serwerze.

Kompatybilność

UniversalModLocalizer najlepiej współpracuje z modami korzystającymi ze standardowych tokenów lokalizacyjnych Valheima, Jotunn, prefabów oraz standardowych elementów interfejsu Unity i TMP.

Niektóre mody posiadają jednak całkowicie własne systemy UI, dlatego w pojedynczych przypadkach może być potrzebne dodatkowe wsparcie kompatybilności.

Zależności

• BepInExPack Valheim
• Jotunn

Informacja o wykorzystaniu AI

UniversalModLocalizer został stworzony przy wsparciu OpenAI Codex.

Wygenerowany kod został następnie przetestowany i dostosowany lokalnie w środowisku Valheim/BepInEx.

Changelog

0.1.13

• Fixed a performance issue where AggressiveExportMode also affected normal gameplay runtime UI text patches.
• Runtime UI translation now tries fast global/unique matches before doing any component-owner lookup.
• Added a bounded runtime translation cache to avoid repeating expensive misses or repeated UI text translations.
• Added EnableScopedRuntimeComponentLookup = false by default for smoother gameplay. Enable it only if duplicate hardcoded UI strings require owner-specific runtime matching.
• Deep export still uses aggressive component-owner lookup, so export coverage is preserved while normal gameplay stays lighter.

0.1.12

• Refreshed the Thunderstore package metadata for r2modman visibility checks.
• Updated the BepInExPack Valheim dependency from denikson-BepInExPack_Valheim-5.4.2350 to the newer denikson-BepInExPack_Valheim-5.4.2351.
• Rebuilt the package with the corrected 0.1.12 manifest and matching plugin version.

0.1.11

• Added vanilla token preservation through BepInEx/config/UniversalModLocalizer/vanilla_tokens.txt.
• Vanilla Valheim tokens such as $item_hammer, $item_club, $piece_fire, and common captions are no longer imported, exported, or globally overridden by mod translation files.
• This keeps original Valheim localization in control when mods reuse base-game items, pieces, creatures, captions, or UI tokens.

0.1.10

• Removed BepInEx config text from export scans; new exports no longer create _config.json files.
• Skips token passthrough entries such as "$item_hammer": "$item_hammer" during export and import so native Valheim/mod localization can handle them.
• Cleaned the active Polish import/export files by archiving generated config exports and removing self-token overrides.

0.1.9

• Fixed import JSON files failing to load when edited text contained common invalid escapes such as \_, \<, or \~.
• Added tolerant import parsing for over-escaped quotes and simple missing commas between key/value entries.
• Repaired the current Polish import set so all 119 JSON files validate before game launch.

0.1.8

• Export files are now merged instead of overwritten.
• Existing key/value pairs are preserved when running uml deep and uml scan one after another.
• New export runs only add missing keys; empty existing values may be filled from the latest detected source text.
• If an existing export file cannot be parsed, a timestamped .bak-* copy is created before regenerating it.

0.1.7

• Reworked uml deep into a faster PrefabLocalizer-style visible-content export path.
• Deep export now focuses on mod localization files, ObjectDB items, status effects, ZNetScene prefabs, hammer/PieceTable build pieces, creatures, and targeted loaded UI text.
• Regular uml scan still includes BepInEx config metadata; uml deep skips config metadata to avoid huge slow exports dominated by settings text.
• Added ObjectDB PieceTable scanning so hammer build-menu pieces are exported from the same practical source the game uses.
• Replaced broad loaded GameObject field scanning with targeted TMP_Text and Unity UI Text scanning.
• Unresolved prefab owners remain in diagnostics, but are not exported as translation files unless ExportUnresolvedPrefabs is explicitly enabled.
• Added start/end scan log messages with duration.

0.1.6

• Added a tolerant fallback parser for malformed .json localization files that are actually loose "key": "value" dictionaries without valid JSON commas.
• Fixed OdinArchitect-style translation files being skipped with After parsing a value an unexpected character was encountered.
• Such files are imported as loose-json records instead of causing a warning and being ignored.

0.1.5

• Added AggressiveExportMode, enabled by default, for stronger manual export scans.
• Added uml deep, an aggressive export command that also writes unresolved prefab strings under _unresolved_prefabs.
• Added uml runtime on/off to enable or disable hardcoded UI string collection from the in-game console.
• Expanded prefab export scanning to include item shared data, status effect fields, and deeper generic string fields.
• Extended uml deep to inspect loaded Unity objects and TMP/Unity UI text components when they can be attributed to an installed mod.
• Improved runtime/UI owner detection by checking related parent components, useful when visible text is owned by Unity/TMP but the window controller belongs to a mod.
• Added owner recovery for previously unresolved strings by matching localization keys and source values back to installed mods.
• Enabled component ownership fallback in the recommended config for better mod attribution during manual scans.

0.1.4

• Enabled imported translations to override native/mod-registered localization by default. This is required for many mods that register English text as their native localization.
• Added generic prefab component string scanning to catch more prefab, build-piece, HUD, and UI text candidates during manual exports.
• Added safe token source resolution from Valheim's currently loaded localization dictionary, avoiding repeated noisy TranslateSingleId calls.
• Scans localization files inside Assets/Translations folders and matches localization keys with or without a leading $.
• Made uml reload reload the config file before reloading translation imports.
• Added ExportGenericPrefabStrings and ResolveTokenSourcesFromCurrentLocalization config options.

0.1.3

• Made Jotunn a required BepInEx and Thunderstore dependency.
• Disabled unresolved-prefab export by default to avoid very large scans.
• Disabled slow component-assembly prefab ownership fallback by default.
• Disabled native target-language probing by default to avoid repeated Valheim localization lookups during export.
• Reused detected English mod localization files as prefab export values when available.

0.1.2

• Added AutoScanOnWorldLoad, disabled by default, so a full export scan only runs automatically when explicitly enabled.
• Fixed ExportMissingTranslations being reused as an automatic scan trigger.
• Recommended disabling runtime string collection during normal gameplay and using manual uml scan for controlled exports.

0.1.1

• Fixed plugin discovery incorrectly marking every plugin as a technical library when installed under BepInEx/plugins.
• Changed export files to simple JSON dictionaries: "key": "value".
• Changed exported file names to include the mod name and category, such as ExampleMod_prefabs.json and ExampleMod_ui.json.
• Added _unresolved_prefabs export coverage for prefab strings whose owning mod cannot be identified reliably.
• Improved prefab token keys so description/tooltips use their real Valheim token when available.
• Kept backward compatibility for the previous entries JSON import format.

0.1.0

• Initial release.
• Added plugin discovery and per-ModGUID translation isolation.
• Added import/export folder structure.
• Added JSON import/export schema.
• Added localization file scanner for JSON, YAML/YML, CSV, TSV, and TXT.
• Added prefab scanner for items, pieces, creatures, and status effects.
• Added BepInEx config text scanner.
• Added token, exact-string, and simple template runtime translation.
• Added TMP_Text and UnityEngine.UI.Text runtime patches.
• Added runtime UI string collection.
• Added hot reload for import JSON files.
• Added server-to-client translation sync with compression, chunking, SHA-256 checks, and cache.
• Added uml console commands.