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/<LanguageCode>/*.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

1. Install the mod from Thunderstore. The declared dependencies are installed automatically: BepInExPack_Valheim, Jotunn, and JsonDotNET.
2. If you install manually, place Localization.dll in BepInEx/plugins.
3. Launch the game once so config.yaml, the plugin-localization files, and the language folders are created.
4. Create one or more rule files under BepInEx/config/com.paxton0505.localization/<LanguageCode>/.
5. 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 hits, the winning match stage, placeholder-resolution details, and per-file rule-load diagnostics.

trace_feed_max_entries controls how many unique entries the Trace page keeps before it evicts the oldest ones.

devtools_enabled turns the in-game overlay on or off.

devtools_toggle_shortcut controls the overlay hotkey. The config file uses raw key names such as LeftControl + F1, while the in-game UI shows the same shortcut as Ctrl + F1.

translation_enabled, debug, whole_string_longest_match_*, trace_feed_max_entries, and devtools_* all come from the local config.yaml. ServerSync does not override runtime settings.

Built-in devtools overlay

On client builds, Localization includes an in-game devtools overlay that is enabled by default and opens with Ctrl + F1 in the UI (LeftControl + F1 in config.yaml).

• Plugin exposes live toggles for translation, debug mode, whole-string longest-match settings, trace-feed capacity, and the overlay shortcut.
• Performance shows loaded-rule counts, cache sizes, hit rates, timings, and lets you reset metrics.
• Trace captures unique intercepted strings, lets you pause/search the feed, and shows per-stage translation analysis for the selected entry.
• Browser groups loaded local and server rules by source, language, and file name.
• Playground lets you draft exact/template rules, preview them against saved and loaded rules, and copy bare JSON.