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.

2. 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.

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

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

Mods using heavily customized UI or localization systems may require additional compatibility support.

If the owner of a text or prefab cannot be identified safely, UniversalModLocalizer avoids blindly assigning it to another mod.

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 automatycznie wykrywać zainstalowane mody BepInEx, zbierać możliwe do przetłumaczenia teksty i eksportować je do prostych plików JSON.

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

Każdy wykryty mod otrzymuje własny 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ć pliki w odpowiednim folderze import i przeładować je bezpośrednio w grze.

Najważniejsze funkcje

• Osobny folder tłumaczeń dla każdego wykrytego moda.
• Proste pliki JSON UTF-8.
• Automatyczne wykrywanie zainstalowanych pluginów BepInEx.
• Odczyt istniejących plików lokalizacyjnych JSON, YAML/YML, CSV, TSV i TXT.
• Standardowe skanowanie komendą uml scan.
• Dokładniejsze skanowanie widocznej 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.
• Obsługa prostych dynamicznych tekstów i placeholderów.
• Skanowanie prefabów przedmiotów, stworzeń, budowli, efektów i innych elementów.
• Synchronizacja tłumaczeń pomiędzy serwerem a klientami.
• Lokalny cache tłumaczeń pobranych z serwera.
• Ochrona oryginalnych tokenów lokalizacyjnych Valheima.
• Tolerancyjne wczytywanie plików JSON przy typowych błędach formatowania.
• Cache tłumaczeń runtime poprawiający wydajność.
• Brak ingerencji w DLL modów, zapisy gry, światy oraz oryginalne pliki lokalizacyjne.

Lepsza wydajność podczas gry

UniversalModLocalizer został zaprojektowany tak, aby podczas normalnej rozgrywki działać możliwie lekko.

Bardziej wymagające wykrywanie właściciela tekstów wykorzystywane jest przede wszystkim podczas ręcznego uruchamiania:

uml scan

lub:

uml deep

Podczas normalnej gry tłumaczenia interfejsu korzystają z szybszego systemu wyszukiwania i pamięci podręcznej.

Dzięki temu tłumaczenie tekstów UI ma znacznie mniejszy wpływ na FPS, szczególnie w dużych paczkach modów.

W rzadkich przypadkach, gdy kilka modów używa dokładnie tego samego tekstu UI, ale wymaga różnych tłumaczeń, można włączyć:

EnableScopedRuntimeComponentLookup

Opcja ta pozwala dokładniej dopasowywać tłumaczenie do konkretnego moda, ale jest domyślnie wyłączona ze względu na większy koszt wydajnościowy.

Ochrona tłumaczeń Valheima

Niektóre mody wykorzystują tokeny należące 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 widocznej zawartości modów, dodatkowych prefabów oraz załadowanych elementów interfejsu.

Pozwala znaleźć teksty, których zwykłe skanowanie może nie wykryć.

uml reload

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

uml status

Wyświetla aktualnie wybrany język, liczbę załadowanych tłumaczeń oraz lokalizację konfiguracji.

uml language Polish

Ustawia język tłumaczenia.

Można również użyć:

uml language Auto

aby UniversalModLocalizer korzystał z języka aktualnie wybranego w Valheim.

uml runtime on

Włącza zbieranie tekstów UI podczas korzystania z okien modów, HUD-u i innych elementów interfejsu.

Jak używać

1. Zainstaluj UniversalModLocalizer przez r2modman albo ręcznie umieść go w:

BepInEx/plugins

1. Uruchom Valheim i wejdź do świata.

2. 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.

Istniejące pliki eksportu są łączone zamiast zastępowane, dzięki czemu ponowne skanowanie może dodać nowe teksty bez usuwania wcześniejszej pracy.

Przykład

Wyeksportowany plik:

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

Polskie tłumaczenie:

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

Tłumacz tylko wartości znajdujące się po prawej stronie.

Klucze po lewej powinny pozostać bez zmian.

Dynamiczne teksty UI

UniversalModLocalizer obsługuje również proste teksty zawierające zmieniające się wartości.

Przykład:

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

Obsługiwane są między innymi popularne formaty placeholderów:

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

Mod może również ostrzec, jeżeli w tłumaczeniu zabraknie placeholdera występującego w oryginalnym tekście.

Multiplayer

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

Serwer wysyła paczkę tylko wtedy, gdy wersja znajdująca się w pamięci podręcznej klienta jest inna.

Dzięki temu gracze mogą automatycznie otrzymywać zestaw tłumaczeń używany na danym serwerze.

UniversalModLocalizer nadal musi być zainstalowany po stronie klienta, aby możliwe było tłumaczenie tekstów UI podczas działania gry.

Kompatybilność

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

Niektóre mody korzystające z całkowicie własnych systemów UI lub lokalizacji mogą wymagać dodatkowego wsparcia.

Jeżeli UniversalModLocalizer nie jest w stanie bezpiecznie określić, do którego moda należy dany tekst lub prefab, nie przypisuje go na siłę do przypadkowego moda.

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.