Unity Localization System

What the system is for

Localization in Unity is one of those tasks that always looks straightforward and ends up touching every system. Menus pull labels from somewhere, modals need translations, audio clips have voice variants per language and gameplay strings appear in screens that were not built with localization in mind. Switching language at runtime means pushing updates into views that may not have been listening.

Serenity wraps Unity Localization tables behind a small service with explicit use cases. It exposes a clean contract for getting and setting the active game language and the active voice language, and it lets the rest of the foundation pull localized strings without depending on Unity Localization directly.

The Unity problem

Most Unity projects do one of two things with localization. Either they hard-code English text in prefabs and try to retrofit translations later, or they wire Unity Localization tables piece by piece on every TextMeshPro component. Both options age badly. The first leaves the project untranslatable. The second couples the UI to Unity Localization in a way that is hard to test, replace or extend with custom logic.

Voice languages add another layer. The player might prefer English text with Japanese voice, or Spanish text with English voice. Hand-rolled localization rarely models that distinction, so audio falls back to whatever the project ships with.

How Serenity approaches it

Serenity exposes localization through ILocalizationService, with use cases LocalizationGetGameLanguage, LocalizationSetGameLanguage, LocalizationGetVoiceLanguage and LocalizationSetVoiceLanguage. Localization tables are described through ILocalizationTable and ILocalizationSettings on the Domain side. The Unity implementation, UnityLocalizationService, bridges the service to the official Unity Localization package using UnityLocalizationStringTable and UnityLocalizationAssetTable.

Game language and voice language are independent tracks. You can change one without touching the other, and gameplay code observes both through the same service. The Menu System and Modal System resolve labels through this service, so switching language updates UI text without scene reloads.

How it fits into Serenity

The Localization System belongs to the Serenity.Localization namespace and follows the same layered split as the rest of the foundation. Domain entities describe localization tables and settings. The Application layer exposes use cases and the ILocalizationService contract. The Infrastructure layer provides UnityLocalizationService and the asset-backed tables. A UnityLocalizationInstaller registers the service so other systems can resolve it through interfaces.

Localization is consumed by most of the foundation. The Menu System and the Modal System look up labels through the service. UI Themes can carry localized sound or visual data when needed. Game Settings can persist the selected languages so the player keeps their choice across sessions. Treating localization as a service rather than as scattered components means each system stays loosely coupled to Unity Localization.

Practical workflow

1. Configure your Unity Localization tables and locales as usual in the Unity project.
2. Map them to UnityLocalizationStringTable and UnityLocalizationAssetTable definitions so Serenity can read them.
3. Let the Unity Localization installer register the service through the initialization pipeline.
4. Read the active language from ILocalizationService inside views or presenters when they need a label.
5. Call LocalizationSetGameLanguage or LocalizationSetVoiceLanguage to switch language at runtime.
6. Persist the player choice through Game Settings so the same language is restored on the next session.

What you get

• ILocalizationService with explicit use cases for game and voice language
• Independent game language and voice language tracks
• Domain interfaces ILocalizationTable and ILocalizationSettings
• Unity implementation backed by Unity Localization tables and assets
• UnityLocalizationStringTable and UnityLocalizationAssetTable wrappers
• Runtime language switching that propagates through the service
• Integration with menus, modals and other Serenity systems
• Installer that registers the localization service once for the project

When to use this

• Projects that ship in more than one language or expect to in the future.
• Games that distinguish between display language and voice language.
• Teams that want to keep gameplay code decoupled from Unity Localization while still using its tables.
• Codebases that need to switch language at runtime without scene reloads.

Related systems

• Unity Menu System Declarative menus, shared UI themes and predictable navigation, configured as assets instead of hand-wired GameObjects.
• Unity Modal System Reusable confirmation, alert and prompt modals driven by typed signals and shared parameters.
• Unity Game Settings Typed get and set use cases for bool, int, float and string settings, with persistence and update signals built in.
• Unity UI Themes ScriptableObject-based UI themes that share visuals and sound feedback across menus, modals and screens.