Localization
Localization is a BepInEx plugin for Valheim that translates hardcoded mod text at the final UI display layer.
Current behavior
- The plugin patches final text assignment for
TMPro.TMP_Text and UnityEngine.UI.Text.
- Every displayed string is checked against an in-memory rule set before it is rendered.
- Rules are loaded from
BepInEx/config/com.paxton0505.localization/<Language>/*.json.
- All
English/*.json files are merged into the fallback baseline.
- When the active game language changes, the plugin reloads the matching language folder such as
Chinese_Trad/*.json and overlays it on top of the English baseline.
- Duplicate rules inside the same language merge are rejected: the plugin logs an error and ignores the later definition.
Config layout
config/
com.paxton0505.localization/
English/
core.json
ui.json
Chinese_Trad/
core.json
ui.json
If the game language is Chinese_Trad, the runtime merges:
config/com.paxton0505.localization/English/*.jsonconfig/com.paxton0505.localization/Chinese_Trad/*.json
The active language rules override English rules with the same match key.
Installation
- Build the plugin:
dotnet build -c Release
- Copy
bin/Release/net48/Localization.dll into your Valheim BepInEx plugins folder.
Example:
BepInEx/
plugins/
Localization.dll
- Create the config root if it does not exist yet:
BepInEx/
config/
com.paxton0505.localization/
English/
Chinese_Trad/
- Add one or more JSON files under
English and under the language folders you want to support.
Usage
1. Create English baseline rules
Create a file such as BepInEx/config/com.paxton0505.localization/English/core.json:
{
"exact": [
{
"match": "PackHorse",
"replace": "PackHorse"
}
],
"templates": [
{
"match": "Player {{$playername}} joined server",
"replace": "Player {{$playername}} joined server"
}
]
}
English is the fallback baseline. It should contain the source strings you want the runtime to recognize.
2. Add translated rules for the target language
If the game language is Traditional Chinese, create a file such as BepInEx/config/com.paxton0505.localization/Chinese_Trad/core.json:
{
"exact": [
{
"match": "PackHorse",
"replace": "負重"
}
],
"templates": [
{
"match": "Player {{$playername}} joined server",
"replace": "{{$playername}} 進入了伺服器"
}
]
}
If you want a captured template parameter to be resolved through the game's own localization system, use {{localize($name)}} in the replacement string instead of {{$name}}.
Example:
{
"templates": [
{
"match": "Found {{$amount}} items matching '{{$item}}' in nearby containers.",
"replace": "已在附近的容器中找到 {{$amount}} 個 {{localize($item)}}"
}
]
}
When the game language is Chinese_Trad, the runtime loads all files from English/*.json, then all files from Chinese_Trad/*.json, and overlays the second set on top of the first.
3. Split rules across multiple files
You can split rules by topic.
Example:
config/
com.paxton0505.localization/
English/
items.json
chat.json
Chinese_Trad/
items.json
chat.json
All *.json files in the same language folder are merged automatically.
4. Duplicate behavior
If two files in the same language folder define the same exact match text or the same template match text, the plugin logs an error and ignores the later file entry.
This means file ordering is deterministic, but duplicates are not used as an override mechanism inside the same language folder.
5. Language switching
The plugin reloads rules when the game writes a new language value into PlayerPrefs.
- If the language stays the same, it keeps using the cached compiled rules.
- If the language changes, it reloads the matching language folder and clears translation caches.
6. What gets translated
This plugin only changes strings that reach the final UI text layer through TMPro.TMP_Text or UnityEngine.UI.Text.
That is why it can catch many hardcoded mod strings, but it also means:
- it does not know the source mod reliably
- it does not translate non-text UI assets
- it only sees the final displayed string, not the original semantic meaning
Rule file format
Each JSON file can contain exact-match rules and template rules.
{
"exact": [
{
"match": "PackHorse",
"replace": "負重"
}
],
"templates": [
{
"match": "Player {{$playername}} joined server",
"replace": "{{$playername}} 進入了伺服器"
}
]
}
Exact rules
match must be a full exact string match.replace is the translated result.
Template rules
- Use
{{$name}} tokens for captured parameters.
- Use
{{localize($name)}} tokens when the captured parameter should be resolved through the game's own localization or item-name lookup.
- Placeholder names may contain letters, digits, and
_, and must start with a letter or _.
- Adjacent placeholders are rejected to keep matching deterministic and fast.
- Function tokens are only supported in the replacement template, not in the match template.
- Supported modes are explicit now: parameter tokens
{{$name}} and function tokens {{localize($name)}}.
localize(...) currently supports exactly one placeholder argument.- Raw regex is intentionally not supported in the first version.
Avoiding token conflicts
{{...}} is reserved syntax inside template rules. If the source text itself literally contains {{$item}} or another token-shaped fragment, do not model it as a template rule.
Use an exact rule instead.
Example: a mod literally shows Use {{$item}} to continue on screen, and you only want to translate the sentence, not treat {{$item}} as a captured parameter.
{
"exact": [
{
"match": "Use {{$item}} to continue",
"replace": "使用 {{$item}} 繼續"
}
]
}
That avoids a syntax collision because exact rules do not parse token syntax.
If the text is actually dynamic, keep the variable part only where it is really needed.
Good:
{
"templates": [
{
"match": "Found {{$amount}} items matching '{{$item}}' in nearby containers.",
"replace": "已在附近的容器中找到 {{$amount}} 個 {{localize($item)}}"
}
]
}
This keeps {{amount}} and {{item}} as explicit parameters, while the surrounding sentence stays fixed and unambiguous.
Performance model
- Exact rules use dictionary lookup.
- Template rules are compiled once at load time.
- Successful translations are cached.
- Repeated misses are cached separately so noisy dynamic text does not flood the main translation cache.
- Language changes are handled by the game's
PlayerPrefs("language") update path instead of per-frame or timed polling.
Why Harmony
This plugin uses Harmony because hardcoded mod text usually bypasses normal localization systems.
If a mod directly does one of these:
tmpText.text = "PackHorse"tmpText.SetText("Player Bob joined server")uiText.text = "Some hardcoded text"
there is no clean configuration hook or official API callback to intercept that text before display.
Harmony solves that by patching the final text assignment methods at runtime.
Why harmony.PatchAll();
harmony.PatchAll(); scans this plugin assembly for classes marked with HarmonyPatch and applies all of them during startup.
In this project that is important for two reasons:
- The interception logic lives in dedicated patch classes such as
TextInterceptionPatches, not inside PluginMain.
- As the plugin grows, you can add more patch classes without writing manual patch registration code for each method.
In practice, PatchAll() gives you one startup line that says: load every patch declared in this plugin assembly.
That is simpler and safer than manually calling Harmony patch methods one by one.
Why not avoid Harmony entirely
For hardcoded mod text, avoiding Harmony usually means you miss the real interception point.
The whole point of this plugin is to catch text at the bottom layer right before it is shown. For that, runtime method patching is the practical tool:
- no game DLL modification
- no need to edit third-party mods
- one shared interception layer for many mods
- works even when the mod never uses Jotunn or Valheim localization APIs
Limits
- This plugin targets final UI text, so it does not reliably know which source mod originally produced the string.
- The first version does not perform context-sensitive translation by UI hierarchy.
- Rich-text canonicalization is not implemented yet.
- Grammar-aware inflection is out of scope for the current template system.
Source layout
src/PluginMain.cs: plugin bootstrap and Harmony initialization.src/TranslationRuntime.cs: active language tracking, caches, and translation entry point.src/TranslationRuleLoader.cs: folder-based JSON loading and merge logic.src/TextInterceptionPatches.cs: final UI text interception hooks.src/CompiledTemplateRule.cs: safe placeholder-template matcher.
Build
Requirements:
- .NET SDK with .NET Framework build support
- Valheim managed assemblies available at the paths configured in
Localization.csproj
- BepInEx core assemblies available at the paths configured in
Localization.csproj
Build command:
dotnet build -c Release
The resulting plugin assembly is written to bin/Release/net48/Localization.dll.
