News & Updates


Foundry Dev Blog #40 - Localization System

Hello! Hallo! ¡Hola! こんにちは! 안녕하세요!

Greetings, everyone! I'm Roman, also known as Zirus, and I've joined the FOUNDRY team back in April. Though I'm new to Foundry Fridays, I'm eager to share some exciting improvements we've been making to our Localization System.

Why the Upgrade to our Localization System?

Previously, our Localization was based on simple key-value pairs. But, as we and FOUNDRY's codebase have grown, we've seen the need for a more robust system - especially when a tiny typo could lead to a big headache:

Key: ValueWelcme to Foundry! Value: Willkommen in Foundry!

Noticed the typo in "Welcome"? Fixing it leads to a lost translation as it ends up being a new key: Key: ValueWelcome to Foundry! Value:

To address this, we have implemented improvements to the System using unique identifiers for each phrase, which ensures consistency of translations across all languages. We'll look into this more in depth a bit later, but let's take a look at the things that actually need Localization first.

The Three Pillars of Localization in FOUNDRY

Localization in Foundry stands on three pillars:

Static Localization

Upon starting the game, static elements like information messages and headers are set in your chosen language. This content remains constant throughout your experience.


Dynamic Localization

Your in-game actions prompt real-time Localization changes. For instance, the plumber tool adjusts its messages based on singular or plural contexts, ensuring an immersive and accurate gaming experience.



Templates are the backbone of FOUNDRY's content - every machine, crafting recipe or item has its own template. Such templates may have translate-able variables, for instance their display name.


Enhancing Consistency by Introducing Unique IDs

To bolster the integrity and consistency of our Localization System, we've introduced a unique identifier for each translatable phrase. Picture these identifiers as serial numbers assigned to each snippet of text, ensuring that every translation is anchored to a stable reference point. This means that even when the English source text is altered - whether to correct a typo or to update a phrase - the corresponding translations remain reliably linked. Here's a practical illustration of this system at work:

ID: WELCOME_MESSAGE English: Welcome to Foundry! Translation: Willkommen in Foundry!

With this structure, we can address any textual errors without disrupting the existing translations across different languages. This new approach provides a safeguard against the common issue of 'lost' translations that occurred under our previous system when making corrections or updates to the source text. Certain scenarios may still necessitate a reevaluation of the translation themselves though. For example, if the original English text is updated to the extent that it alters the context or meaning, the translations would need to be revisited to ensure they still convey the intended message accurately.

The Big Export: Optimizing the Translation Workflow

In our pursuit to optimize the translation process, we have developed a specialized parser. This tool is designed to automatically generate Localization files in a format called "portable object". This change streamlines our workflow, making it easier to update our project on CrowdIn.

Validation: Ensuring Precision in Localization

In the complex landscape of Localization, maintaining a clear overview of existing unique identifiers is crucial. To manage this, we've integrated a robust Validation System, designed to be a steadfast ally in the Localization process. This system automatically flags any discrepancies such as overlapping IDs or absent context comments. Here's a glimpse into the kinds of issues it helps us avoid:

Preventing Duplicate IDs from Causing Confusion

ID: MACHINE_EMPTY Value: Machine is empty ID: MACHINE_EMPTY Value: Machine is currently empty

Encountering duplicate IDs with different assigned values can create conflicts within the Localization System, as it relies on IDs to determine the correct text to display in-game. This scenario can lead to inconsistencies, which our Validation System is adept at identifying.

Avoiding Redundancy with Different IDs for Identical Values

ID: MACHINE_EMPTY Value: Machine is empty ID: SELECTED_MACHINE_EMPTY Value: Machine is currently empty

It's possible to inadvertently create different IDs for the same value. Our system detects such redundancies, alerting us to streamline our Localizations and prevent unnecessary complexity.

Context Comments for Clear Translation

Context is king in translation. To aid our translators, we embed comments within each Localization call, providing them with the necessary background to deliver accurate translations. These comments are essential, especially when viewed in tools such as CrowdIn, where they guide the translation process. This is why the Validation System informs us about calls where these context comments are missing.

Modding: Empowering Community Creativity

Our new Localization System is crafted with the modding community at heart, streamlining the way modders integrate translations into their creations. This modder-centric design allows for seamless utilization of the existing Localization framework during the development phase, ensuring that mods are as language-accessible as the core game itself. From the initial coding stages to the final touches, modders should be able to:

  • Employ the system to handle in-game text, providing a consistent experience for mod users.

  • Export their content into "portable object" files, which are standardized for easy translation management.

  • Utilize the Validation System to preemptively catch and correct any potential issues with duplicate IDs or missing context, which is crucial for maintaining the integrity of the mod's Localization.

  • Load these translations during the game's startup, making sure that no matter where a player is from, they can enjoy mods in their native tongue.

Our goal is a robust and accessible environment that empowers modders to share their work with a global audience, removing language barriers that could previously hinder the full enjoyment and reach their creative efforts.

In Closing,

We strive to make Localization intuitive for everyone involved - gamers, translators, and modders. Should you have any feedback or suggestions, please feel free to reach out to us on Discord. I hope you enjoyed this little sneak peek into how we handle Localization. Thanks for reading! Cheers, Zirus