Localization

Localization

Localization is a runtime translation helper for Valheim mods. It intercepts text right before it is displayed and replaces it with values from JSON rule files.

This mod is meant to help translate hardcoded mod UI text. It does not generate translations by itself; you provide the translation rules.

What this mod does

• Intercepts final UI text assignments for TMPro.TMP_Text.text, TMPro.TMP_Text.SetText(string, bool), and UnityEngine.UI.Text.text.
• Applies exact rules for full-string matches and templates rules for placeholder-based matches.
• Re-runs rewritten text through the rule engine so an English baseline alias can normalize non-English hardcoded text before the active language translation is applied.
• Strips supported rich-text tags from intercepted input before matching and compares exact rules with OrdinalIgnoreCase.
• Loads rule files from BepInEx/config/com.paxton0505.localization//*.json.
• Uses English/*.json as an optional shared baseline.
• Reloads rules when the active game language changes.
• Supports a top-level translation_enabled runtime toggle in the local config.yaml.
• Includes an in-game devtools overlay for live trace, browser, performance, and playground workflows on clients, enabled by default with Ctrl + F1.
• Supports session-only ServerSync overlays when both server and client run the mod.
• Keeps server-synced rules in memory only and does not write them into the client's local JSON files.

What this mod does not do

• It does not machine-translate text for you.
• It does not modify the source files of other mods.
• It does not save server overlays to disk after the session ends.
• On a dedicated server it does not run local UI translation patches, because there is no local UI to patch.

Before / After

Install

• Install the mod. The declared dependencies are installed automatically: BepInExPack_Valheim, Jotunn, and JsonDotNET.
• If you install manually, place Localization.dll in BepInEx/plugins.
• Launch the game once so config.yaml, the plugin-localization files, and the language folders are created.
• Create one or more rule files under BepInEx/config/com.paxton0505.localization//.
• If you want server-provided overlays, install the mod on both server and clients.

Localization.dll already bundles the ServerSync implementation used by this mod. You do not need to add a separate ServerSync DLL for this plugin.

Folder layout

Example structure:

BepInEx/

config/

com.paxton0505.localization/

config.yaml

Localization-English.json

Localization-Chinese_Trad.json

English/

Common.json

Chinese_Trad/

MyMod.json

• English is optional and can be used as a shared baseline.
• The active language folder should match the game's language name, for example Chinese_Trad.
• Files inside each language folder are loaded in alphabetical order by file name.
• Localization-*.json files are for the plugin's own overlay, status text, and fallback log strings.

Optional runtime settings

The plugin creates BepInEx/config/com.paxton0505.localization/config.yaml on startup if it is missing.

translation_enabled: true

debug: false

whole_string_longest_match_mode: per_word

whole_string_longest_match_min_length: 5

trace_feed_max_entries: 1024

devtools_enabled: true

devtools_toggle_shortcut: LeftControl + F1

Set translation_enabled: false to bypass the entire translation pipeline. While it is false, intercepted UI text is left unchanged and the runtime skips rule reloads until translation is enabled again.

Set debug: true to enable runtime debug mode.

whole_string_longest_match_mode controls whole-string longest-match exact replacement:

• per_word: only replace spans that start and end on word boundaries.
• min_length: only replace spans whose visible letter/digit count is at least whole_string_longest_match_min_length.
• off: keeps the legacy unrestricted greedy behavior.

When enabled, the log includes intercepted UI strings before translation, cache hits and miss-cache hi