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.