Localization

Part of the 7DTD Modding Knowledgebase. Covers adding translated text strings to a mod.

---

File Location

• 3.0.0+: Config/Localization.csv — the game renamed the file; Localization.txt is silently ignored (decompiled Localization.LoadPatchDictionaries hardcodes _folder + "/Localization.csv"; ModManager.LoadLocalizations passes mod.Path + "/Config"). Symptom: raw keys like vehicleFooPlaceable shown in tooltips, no error anywhere. Ship both names if a mod must work on 2.x and 3.0 (found 2026-07-15 — the Supra mod's .txt is also dead on 3.0.0 for this reason).
• Pre-3.0: Config/Localization.txt.

Gotcha: Put mod localization under Config/, not at the mod root. A root-level file may be copied by deployment but will not be picked up by the game. Check Player.log for [MODS] Loading localization from mod: YourMod; if that line is missing, the game did not load the mod's localization file.

Patch CSVs are merged by header column name (case-insensitive), so a mod file without the newer vanilla columns (e.g. KeepLoaded, added in 3.0.0) still maps english correctly.

---

Format

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,spanish,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese
myKey,blocks,Block,,,My English Text,,Mein Text,...
myWindowTitle,windows,XUi,,,My Window Title
myButtonLabel,windows,XUi,,,Click Me

Column	Notes
Key	Unique identifier — used in XML as {myKey} or text_key="myKey"
File	Category: blocks, windows, items, etc.
Type	Block, Item, XUi, etc.
UsedInMainMenu	Usually blank
NoTranslate	Usually blank
english	The English string
Context / Alternate Text	Optional — notes for translators, not shown in-game
german, spanish, etc.	Optional translated strings; game falls back to english if blank

---

Using Keys in XML

In window/UI XML, reference a key as a binding:

<label text="{myWindowTitle}" />
<button text="{myButtonLabel}" />

Or via text_key attribute:

<label text_key="myWindowTitle" />

In block definitions:

<!-- Block display name automatically uses block name as key -->
<block name="MyBlock">
    <!-- Localization key = "MyBlock" for display name -->
    <!-- Localization key = "MyBlock_desc" for description, if defined -->
</block>

Player-facing title keys

• An item or block title key is the definition's exact internal name; DescriptionKey supplies only the longer description and cannot replace the title row.
• Add or verify the exact title row whenever a definition is created or renamed. A missing title row displays the raw identifier (for example, elevatorAutoDoorDouble).
• Use short, natural English rather than mechanically copying camelCase/PascalCase. Usable block titles can be inserted into interaction prompts such as (E) Use …, so an action-oriented title like Open Elevator Door may read better than a technical label.
• ModForge's block editor exposes this as General → In-game name. It writes Localization.csv for 3.0 and mirrors an existing Localization.txt for pre-3.0 compatibility while preserving the other CSV columns (added 2026-07-25).

---

Inline Item Links

In localization string values, wrap an item name in <<| |>> to generate a clickable in-game link to the item's info:

xuiCraftingTip,windows,XUi,,,Use <<|resourceWood|>> to build this item.

The game renders this as a styled hyperlink to the resourceWood item page.

---

Tips

• Keys are case-sensitive
• If a key is missing, the raw key string is displayed (useful for debugging)
• The CSV must use commas; don't use quotes around values unless the value contains a comma
• The Context / Alternate Text column is for translator notes — it is not shown in-game
• Prefer the full vanilla CSV header and row width, especially for UI/radial keys. Shortened localization files can appear to work for some keys but fail for others.

Radial Menu Block Commands

Block radial-menu entries created with BlockActivationCommand are localized by key:

blockcommand_{commandName}

For example, new BlockActivationCommand("my_action", "tool", true) needs:

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,spanish,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese
blockcommand_my_action,UI,Radial blockcommand,,,My Action,,My Action,My Action,My Action,My Action,My Action,My Action,My Action,My Action,My Action,My Action,My Action,My Action

If the key is missing or not loaded, the radial menu displays the raw key, such as blockcommand_my_action. If a blockcommand_ entry causes localization/XUi errors, check the CSV header and number of columns first; the known failure mode was caused by an incomplete localization row shape, not by blockcommand_ keys themselves.