Skip to content

Localization (Locales) in UI

  • Hardcoded user-facing strings in XAML or C# are strictly prohibited.
  • The UI and Command Registry MUST request text from the Locale engine using Intents rather than raw keys.
  • The Locale engine is responsible for mapping the requested Intent (e.g., exit_to_library) to the correct localized string based on the active language configuration.

Code Example: Intent Binding

In XAML, a custom Markup Extension (e.g., i18n:Localize) is used to query the Locale engine using the Intent. 

<!-- WRONG: Hardcoded string -->
<Button Content="Exit to Library" Command="{Binding ExitCommand}" />

<!-- CORRECT: Binds to the Intent -->
<Button Content="{i18n:Localize intent.exit_to_library}" 
        Command="{Binding ExitCommand}" />

Under the hood, the C# Locale Engine intercepts intent.exit_to_library and returns the correct string instantly based on the active language configuration:

public string GetString(string intent) 
{
    // The engine queries the currently loaded language dictionary (e.g., fr.json or resx)
    if (_activeTranslationDictionary.TryGetValue(intent, out string translatedText))
    {
        return translatedText;
    }

    // Fallback for missing translations
    return $"[{intent}]";
}