Interface ILocalizationService

Interface for localization services handling game and voice language settings.

Namespace: Serenity.Localization.Application.Interfaces

Assembly: Serenity.Localization.Application.dll

Syntax

public interface ILocalizationService : IService, IFoundationSettings

Methods

GetGameLanguage()

Gets the current game language.

Declaration

string GetGameLanguage()

Returns

Type	Description
string

GetStringTableReference()

Gets the string table reference used for localization.

Declaration

string GetStringTableReference()

Returns

Type	Description
string	The string table reference.

GetVoiceLanguage()

Gets the current voice language.

Declaration

string GetVoiceLanguage()

Returns

Type	Description
string	The current voice language.

SetGameLanguage(LocalizationSetGameLanguageInput)

Sets the game language based on the provided input data transfer object.

Declaration

void SetGameLanguage(LocalizationSetGameLanguageInput input)

Parameters

Type	Name	Description
LocalizationSetGameLanguageInput	input	The input data transfer object containing the new game language.

SetVoiceLanguage(LocalizationSetVoiceLanguageInput)

Sets the voice language based on the provided input data transfer object.

Declaration

void SetVoiceLanguage(LocalizationSetVoiceLanguageInput input)

Parameters

Type	Name	Description
LocalizationSetVoiceLanguageInput	input	The input data transfer object containing the new voice language.

TryTranslate(string, out string)

Attempts to translate a localization key directly through the service, without going through Unity Localization's LocalizeStringEvent / Addressables path.

This is the translation entry point used in ResourcesOnly mode (WebGL builds that have no Addressables catalog and therefore cannot run Unity Localization's table registry). The Addressables-backed UnityLocalizationService implementation returns false from this method — its consumers rely on LocalizeStringEvent.RefreshString via the existing GetStringTableReference() path. The SerenityFallbackLocalizationService implementation looks the key up in translation data that the WebGL Resources exporter emitted into the consumer project's Resources folder.

Implementations MUST NOT throw on a missing key / missing language / missing service state — return false with value = null and let the caller fall back gracefully (typically by keeping whatever text was already on screen, which for the TMP updater is the raw key itself).

Declaration

bool TryTranslate(string key, out string value)

Parameters

Type	Name	Description
string	key	Localization key (e.g. "menu.start", "MAIN_MENU_TITLE"). May be null or empty — the implementation must return false in that case.
string	value	Translated string in the current game language when the lookup succeeds; null otherwise. Never an empty string masquerading as a result — implementations must treat empty translations as misses.

Returns

Type	Description
bool	true when a translation was found, false otherwise.

Events

GameLanguageChanged

Raised after SetGameLanguage(LocalizationSetGameLanguageInput) successfully changes the active game language. Consumers that cache translated strings (e.g. the TMP localization updater) subscribe to this to re-translate visible UI when the player switches language at runtime without a scene reload.

Contract:

• Implementations MUST only invoke the event when the language actually changed — repeating the same value is a no-op so consumers don't re-translate on every settings dispatch.
• Implementations MUST invoke the event AFTER updating their internal language state, so handlers querying GetGameLanguage() during the callback observe the new value.
• Invocation thread is the caller's thread (typically the Unity main thread, since SetGameLanguage(LocalizationSetGameLanguageInput) is driven by game-settings changes). Implementations need not marshal.
• Implementations that route translation through another mechanism (e.g. UnityLocalizationService delegates to Unity Localization's own locale-change subscription chain via LocalizeStringEvent) MAY leave this event un-invoked. Subscribers must not assume the event will fire.

Declaration

event Action GameLanguageChanged

Event Type

Type	Description
Action