Localization System Refactor & Overhaul for Tabletop Simulator 2.0 UI/UX#2800

With the announcement of the Tabletop Simulator 2.0 Overhaul Roadmap and the upcoming full UI/UX rewrite using the modern UI Toolkit, this is the critical moment to completely refactor the current localization system. The existing implementation is obsolete, context-blind, and structurally flawed. It actively prevents high-quality translations, limits community contributions, and produces a broken experience for non-English players. If the UI is being rebuilt from the ground up, the localization backend must be modernized alongside it; otherwise, the 2.0 overhaul will remain fundamentally inaccessible and unpolished for international users. This report consolidates multiple long-standing issues to explain exactly what is broken and how it should be fixed.

Transition from String-Based Keys to Context-Aware IDs
The current system uses the English source string as the lookup key, which is a critical design flaw because it creates conflicts where identical words require different translations depending on the context. For example, the word “Draw” appears in card mechanics and drawing tools, yet in languages like Spanish, these require completely different verbs. “Flip” is used as a verb for actions and a noun for states, and “Custom” varies by gender and number. The solution is to move to a proper key-value system using unique identifiers—such as ui.menu.draw_card versus ui.tool.draw_line—instead of raw text. This allows for context-aware translations and is the standard practice in modern i18n systems.
References: #819, #2238

Elimination of Hardcoded Strings, Formatting and Forced Capitalization
A recurring problem is that many UI strings are currently hardcoded, only partially exposed, or have styling forced by the code. Elements such as the Tutorial text, specific context menu items like the “Options” ellipsis, miscellaneous settings tooltips, and internal labels like “Root Folder” remain in English even when translated in the file. Furthermore, the game code forces capitalization on certain UI elements, which corrupts the grammar of languages where capitalizing non-proper nouns is incorrect. The new system must expose every text element to the localization provider and delegate styling decisions (like capitalization) to the translator via the ID value, rather than forcing .ToUpper() in the source code.
References: #300, #322, #323, #371, #384, #728, #1765

Advanced String Composition, Variable Interpolation and Pluralization
The current system fails when combining dynamic variables with localized text, forcing developers to use brittle Lua workarounds to concatenate strings which often leads to bugs, such as the Rotation Value failing to display the Object Name if the target language word order differs from English. The new system needs to support inline variable interpolation directly within the translation string (e.g., “Hello {player_name}”) and allow for self-referencing other translation IDs to build complex sentences contextually. Furthermore, it is essential to implement a robust pluralization engine capable of handling distinct grammatical variants beyond simple singular/plural toggles; this includes defining specific strings for zero elements (e.g., “No items”), singular cases (“1 item”), standard plurals (“{n} items”), and crucial overflow fallbacks for when a number exceeds UI limits, allowing the system to gracefully substitute the count with expressions like “99+” or “Too many items” to prevent text clipping and layout breakage.
References: #1029, #1515

Runtime Localization and Save File Independence
Currently, localization is often “baked” into objects when saving a game, which causes persistent issues. If a save file is created in English, loading it later with the client set to Spanish often results in objects, decks, and tooltips remaining in English. Furthermore, changing the language in the settings often requires a restart or fails to update all UI elements dynamically. The refactored system must resolve localization at runtime basd on the client’s current language setting rather than reading static strings saved in the file, allowing for immediate and dynamic language refreshing without consistency errors.
References: #241, #291, #368, #1619

Prioritization of Community Translations over Machine Learning
The current system frequently forces Google Translate strings over community contributions or provides low-quality machine translations that break immersion and clarity. High-quality community translations from the Workshop must always take strict precedence over auto-generated text. Ideally, machine translation should be an opt-in feature or fully removable, ensuring that the fallback for missing strings is the original English text rather than unintelligible machine-generated gibberish.
References: #51, #122, #251

Consolidated Issue Report
This proposal unifies and supersedes the following existing feedback reports regarding the localization system, sorted chronologically:
#51, #122, #241, #251, #291, #300, #322, #323, #368, #371, #384, #728, #819, #1029, #1515, #1619, #1765, #2238.

Thanks this is definitely part of the roadmap we just didn’t specify it on the post. This is super detailed and very useful!