LocaleService

The localization service shared by the Studio and running games: holds one StringTable per locale, resolves a key through a locale → language → default fallback chain, and raises LocaleChanged when the active locale changes.

Remarks

Registered as a plain singleton rather than through InternalServiceAttribute, because a table-less instance is useless: each host loads the project's tables into it (or a fresh play scope) before anything reads a key. Localization is the static facade game code and UI documents use. Locale switching is live: Generation increments and LocaleChanged fires, and immediate-mode UI re-resolves its text every frame, so nothing needs reloading.

Properties

DefaultLocale

(string) : The locale unresolved keys fall back to.

ActiveLocale

(string) { get; set }: The locale currently in force.

Generation

(uint) { get; set }: Increments on every locale change, so a retained text mesh knows to rebuild.

AvailableLocales

(IReadOnlyCollection): Every locale a table has been added for.

HasTables

(bool): Whether any table has been added.

Public Methods

AddTable

public void AddTable(StringTable table)

Adds or replaces the table for its locale.

Parameters:

  • table (StringTable): The table to add.

ClearTables

public void ClearTables()

Forgets every table, so a project switch starts clean.

SetLocale

public bool SetLocale(string locale)

Switches the active locale. A locale with no table is allowed and simply falls through the fallback chain — the caller may add the table later without re-selecting.

Parameters:

  • locale (string): The BCP-47 locale to switch to.

Returns: bool

  • true when the active locale actually changed.

Translate

public string Translate(string key, string? fallback = null, decimal? count = null)

Resolves a key through the fallback chain and formats any plural block.

Parameters:

  • key (string): The localization key.
  • fallback (string?): Text to return when no table holds the key; defaults to a bracketed key. (Default: null)
  • count (decimal?): The count a plural message selects its variant from, or null. (Default: null)

Returns: string

  • The localized, formatted string.

TranslateSource

public string TranslateSource(string source, decimal? count = null)

Resolves authored source text through the fallback chain, falling back to the text itself. This is what makes every displayed string localizable without changing how it is authored: a table with the source as its key translates it, and a project with no table renders unchanged.

Parameters:

  • source (string): The authored text, also used as the lookup key.
  • count (decimal?): The count a plural message selects its variant from, or null. (Default: null)

Returns: string

  • The localized string, or source.