Localization

Localization is a BepInEx plugin for Valheim that translates hardcoded mod text at the final UI layer.

What it does

• Patches final text assignment for TMPro.TMP_Text and UnityEngine.UI.Text.
• Matches displayed strings against compiled exact and template rules.
• Loads rules from BepInEx/config/com.paxton0505.localization/<LanguageCode>/*.json.
• Uses English/*.json as an optional shared baseline.
• Reloads when the active game language changes.

Before / After

Install

1. Install BepInExPack_Valheim and JsonDotNET.
2. Install the plugin.
3. Launch the game once so the config folders are created.
4. Add JSON rule files under a language folder such as Chinese_Trad/.

Example rules

{
  "exact": [
    {
      "match": "Item is favorited and won't be stored",
      "replace": "物品已被收藏，不會被存放"
    },
    {
      "match": "Slot is favorited and won't be stored",
      "replace": "格位已被收藏，不會被存放"
    }
  ],
  "templates": [
    {
      "match": "Found {{$count}} items matching '{{$query}}' in nearby containers.",
      "replace": "在附近容器中找到 {{$count}} 個符合「{{localize($query)}}」的物品。"
    },
    {
      "match": "<color=red>No items matching '{{$query}}' found in nearby containers.</color>",
      "replace": "<color=red>在附近容器中找不到符合「{{localize($query)}}」的物品。</color>"
    },
    {
      "match": "Stored {{$total}} items from your inventory into nearby containers",
      "replace": "已將 {{$total}} 個物品從你的背包存放到附近容器中"
    },
    {
      "match": "<color=red>{{$itemName}} [{{$prefabName}}] is not in nearby containers</color>",
      "replace": "<color=red>附近容器中沒有 {{localize($itemName)}} [{{$prefabName}}]</color>"
    },
    {
      "match": "<color=red>{{$itemName}} [{{$prefabName}}] cannot be stored based on configuration settings</color>",
      "replace": "<color=red>根據設定，無法存放 {{localize($itemName)}} [{{$prefabName}}]</color>"
    },
    {
      "match": "AzuAutoStore Installed: {{$localVersion}}\n Needed: {{$remoteVersion}}",
      "replace": "已安裝 AzuAutoStore：{{$localVersion}}\n需要版本：{{$remoteVersion}}"
    }
  ]
}

Notes

• English/ is optional and acts as a shared baseline.
• {{localize($name)}} resolves through the plugin's exact rules first and then the game's own localization.
• Unmatched text is left unchanged.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[v2.0.1] - 2026-05-16

Fixed

• Fixed the devtools Playground rebuild flow so rebuilding the page clears stale UI references instead of reusing dead controls, and clicking a scrollable input field now re-activates the underlying InputField so text entry keeps working after scrolling.

[v2.0.0] - 2026-05-16

Added

• Added the built-in in-game Localization devtools overlay with Plugin, Performance, Trace, Browser, and Playground pages for live inspection and rule drafting.
• Added root-level plugin localization catalogs (Localization-English.json and Localization-Chinese_Trad.json) with hot reload so overlay labels, plugin-owned UI strings, and fallback log text can be localized separately from mod translation rules.
• Added runtime performance metrics, translation-analysis views, and rule-browser snapshots for loaded local and ServerSync rule files.
• Added trace_feed_max_entries, devtools_enabled, and devtools_toggle_shortcut to BepInEx/config/com.paxton0505.localization/config.yaml, with Ctrl + F1 as the default devtools toggle in the UI.

Changed

• config.yaml hot reload now also updates trace-feed capacity and the devtools overlay enable/shortcut state without restarting the game.
• Root-level plugin localization files are now auto-generated and hot-reloaded alongside the language rule folders.
• Updated the repository README and Thunderstore README to document the built-in devtools overlay, plugin-owned localization files, live runtime settings, and current Thunderstore packaging output.

Removed

• Removed the unused DevToolsSectionedPage scaffold left over from earlier devtools layout experiments.

[v1.3.0] - 2026-05-14

Added

• Added translation_enabled: true as the top-most runtime setting in BepInEx/config/com.paxton0505.localization/config.yaml.
• Added deterministic validate-artifact workflow support for the translation agent, plus restored Python/runtime checks around sanitizer and artifact validation behavior.
• Added an optional runtime settings file at BepInEx/config/com.paxton0505.localization/config.yaml with debug: false by default.
• Added configurable whole-string longest-match exact replacement restrictions through whole_string_longest_match_mode and whole_string_longest_match_min_length in config.yaml.
• Added constrained template placeholders for word, words(...), int(...), float(...), and oneof(...), including numeric where= predicates such as >0 && <10.

Changed

• When translation_enabled: false, the runtime now bypasses UI translation and skips rule reloads until translation is enabled again.
• Clarified that translation_enabled, debug, and other runtime knobs remain local client-side settings even when translation rules are synced through ServerSync.
• Restored rich-text tag stripping for exact, template, and whole-string longest-match exact replacement while keeping OrdinalIgnoreCase behavior.
• Normalized exact and template matches now re-apply only the outer tags immediately wrapping the matched visible span. Whole-string longest-match exact replacement keeps only the full string's outermost tags; internal word-level tag positions are not remapped.
• Whole-string longest-match exact replacement now defaults to per_word mode, and runtime changes to its restriction settings immediately clear translation caches.
• Updated the repository README and Thunderstore README to document tag-stripped matching with outer-tag reapplication.
• Refreshed the repository README and Thunderstore README to document the current project layout, validation commands, runtime toggle behavior, and ServerSync hot reload semantics.
• Signed int and float constrained placeholders now accept optional leading + or - by default, with further numeric filtering available through where= predicates.
• When debug: true is enabled, the plugin now logs intercepted UI strings before translation, rule-file load details, cache hits and miss-cache hits, winning match stages, placeholder resolution, and loop or duplicate diagnostics.

[v1.2.3] - 2026-05-13

Added

• Added normalized exact-rule matching for all translation hops by stripping rich-text tags from match input and comparing exact rules with OrdinalIgnoreCase.
• Added normalized template matching so template literals also compare against tag-stripped input case-insensitively.

Changed

• Matched output now always comes from the rule replace value, so intercepted source tags are not re-applied after translation.
• Active-language translation hops now participate in the same relaxed normalized matching instead of limiting ignore-case behavior to the English bridge layer.
• Updated the repository README and Thunderstore README to document normalized matching, tag stripping, and replace-first rendering behavior.

[v1.2.1] - 2026-05-13

Added

• Added an English-only OrdinalIgnoreCase exact-rule fallback so English baseline normalization can still bridge casing variants such as PACKHORSE -> PackHorse -> 馱馬.

Changed

• Kept active-language exact rules and all template matching case-sensitive, limiting ignore-case behavior to the English exact normalization layer.
• Updated the repository README and Thunderstore README to document the new English-only ignore-case fallback and its scope.

[v1.2.0] - 2026-05-13

Added

• Added chained runtime translation passes so one intercepted string can flow through multiple rule matches, such as German hardcoded text -> English baseline alias -> Chinese_Trad active translation.
• Added chained exact-rule resolution for {{localize(...)}} template placeholders so placeholder values can also normalize through English aliases before landing on the final target language.

Changed

• Updated the repository README and Thunderstore README to document chained translation behavior, English normalization patterns, and the new placeholder resolution flow.

[v1.1.1] - 2026-05-13

Changed

• Lowered duplicate exact-rule and template-rule diagnostics from error level to debug level. Later duplicate definitions are still ignored, but they no longer surface as load errors.
• Expanded the Thunderstore README into a fuller usage guide covering installation, config layout, rule format, load precedence, server/client behavior, and hot-reload details.
• Reformatted this changelog to the Keep a Changelog structure.

[v1.1.0] - 2026-05-13

Added

• Server-side hot reload logs so dedicated server config updates now show when a debounced snapshot is republished.
• Debounced config file watcher reloads so rapid JSON saves only publish one local snapshot.
• ServerSync-based session overlays so clients can receive the server's localization JSON tree without rewriting local files.
• Remote/local layered rule merging so synced rules can override the local English and active-language files in a predictable order.

Changed

• Dedicated servers now run in sync-only mode and skip the local translation runtime plus UI Harmony patches.
• Bundled ServerSync into the plugin build and updated the release/docs for the new sync flow.

[v1.0.4] - 2026-05-13

Fixed

• Fixed the release zip output and cleaned up the Thunderstore packaging flow.

Changed

• Polished release metadata and trimmed package assets/docs for distribution.

[v1.0.3] - 2026-05-13

Changed

• Optimized template rule dispatch and loading performance.

Added

• GitHub Copilot-assisted translation workflow, prompts, agents, and Python tooling.
• Recorded mod version metadata in the translation workflow and reorganized Thunderstore release files.

[v1.0.2] - 2026-05-10

Added

• Thunderstore packaging basics including manifest and icon assets.

Changed

• Refined the project/build setup and refreshed the README for initial release packaging.

[v1.0.1] - 2026-05-10

Added

• Split the initial implementation into focused runtime, loader, template, and interception components.
• Added exact/template rule loading, placeholder handling, and final UI text interception.

[v1.0.0] - 2026-05-10

Added

• Initial project scaffolding, BepInEx plugin entry point, build file, and README.
• First working prototype of the runtime localization plugin.