Document UI And Localization

Localization/LocalizationManager.cs

@@ -9,29 +9,49 @@ namespace ADOFAIRenderer.Localization;
 
 /// <summary>
 /// Provides access to localized strings and handles language synchronization with the game.
+/// <para>
+/// Locale files are flat JSON objects (<c>"key": "text"</c>) under <c>Localization/Locale/</c>, embedded in the mod
+/// assembly as resources; the file name without extension is the locale code (<c>en.json</c> -> "en").
+/// The active locale follows the game language: <c>LanguageSyncPatch</c> calls <see cref="SetLanguage"/> after the game's
+/// <c>RDString.Setup</c> and <c>RDString.ChangeLanguage</c>. Only Korean maps to its own locale ("ko"); every other
+/// language uses English ("en").
+/// </para>
+/// <para>
+/// Lookup order in <see cref="Get(string)"/>: active locale, then English, then the key itself.
+/// Intended for the Unity main thread; the dictionaries are filled once during initialization and only read afterwards.
+/// </para>
 /// </summary>
 internal static class LocalizationManager
 {
+    /// <summary>Loaded locales: locale code (case-insensitive) -> key -> text. Keys are case-sensitive.</summary>
     private static readonly Dictionary<string, Dictionary<string, string>> Locales = new(StringComparer.OrdinalIgnoreCase);
+    /// <summary>Locale used when the language has no locale file and for keys missing in the active locale.</summary>
     private static readonly string FallbackLocaleCode = "en";
 
     /// <summary>
     /// Event triggered when the active language changes.
+    /// Raised by <see cref="SetLanguage"/> with <c>notify: true</c> when the language or the resolved locale differs from
+    /// the current one; the argument is the new game language. Exceptions from handlers are caught and logged
+    /// (an exception stops the remaining handlers of that invocation).
     /// </summary>
     public static event Action<SystemLanguage>? OnLanguageChanged;
 
     /// <summary>
-    /// Currently active SystemLanguage.
+    /// Currently active SystemLanguage: the game language as passed to <see cref="SetLanguage"/>, also when it has no
+    /// locale file of its own (e.g. Japanese, which displays English text).
     /// </summary>
     public static SystemLanguage CurrentLanguage { get; private set; } = SystemLanguage.English;
 
     /// <summary>
-    /// Currently active locale code (e.g. "en", "ko").
+    /// Currently active locale code (e.g. "en", "ko"): the locale whose strings <see cref="Get(string)"/> returns first.
+    /// Always a loaded locale or the fallback "en".
     /// </summary>
     public static string CurrentLocaleCode { get; private set; } = "en";
 
+    /// <summary>Set by the first <see cref="Initialize"/> call; later calls return immediately.</summary>
     private static bool _initialized;
 
+    /// <summary>Initializes on first access to any member, so lookups work before <c>RenderMod</c> calls <see cref="Initialize"/>.</summary>
     static LocalizationManager()
     {
         Initialize();
@@ -39,6 +59,8 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Initializes the localization system and loads embedded language dictionaries.
+    /// Runs once; further calls do nothing. Selects the initial language without raising
+    /// <see cref="OnLanguageChanged"/>.
     /// </summary>
     public static void Initialize()
     {
@@ -47,19 +69,26 @@ internal static class LocalizationManager
 
         LoadEmbeddedLocales();
 
-        // Detect initial language from game settings
+        // Detect initial language from game settings.
+        // At mod initialization RDString.Setup has usually not run yet, so this reads the field's initial value
+        // (English); LanguageSyncPatch applies the real language when the game calls RDString.Setup.
         var initialLang = DetectGameLanguage();
         SetLanguage(initialLang, notify: false);
 
         LogMsg($"[Localization] Initialized. Active language: {CurrentLanguage} ({CurrentLocaleCode})");
     }
 
+    /// <summary>
+    /// Logs through the MelonLoader logger of the mod, or to the console when that logger is not available
+    /// (e.g. when this class is used outside the running mod).
+    /// </summary>
     private static void LogMsg(string msg)
     {
         try { Melon<RenderMod>.Logger.Msg(msg); }
         catch { Console.WriteLine(msg); }
     }
 
+    /// <summary>Error counterpart of <see cref="LogMsg"/>; falls back to standard error.</summary>
     private static void LogError(string msg)
     {
         try { Melon<RenderMod>.Logger.Error(msg); }
@@ -68,6 +97,9 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Loads all *.json locale files embedded in this assembly.
+    /// A resource is used when its name ends with ".json" and contains "Localization.Locale" (the manifest name built
+    /// from the folder path, see the EmbeddedResource item in the .csproj). A file that fails to read or parse is
+    /// logged and skipped; a later resource with the same locale code replaces an earlier one.
     /// </summary>
     private static void LoadEmbeddedLocales()
     {
@@ -109,7 +141,13 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Sets the active language and notifies subscribers if changed.
+    /// The locale is chosen by <see cref="LanguageToLocaleCode"/>; when that locale is not loaded, "en" is used.
     /// </summary>
+    /// <param name="language">Game language (as used by <c>RDString.language</c>).</param>
+    /// <param name="notify">
+    /// Whether to raise <see cref="OnLanguageChanged"/> when the language or locale changes; <c>false</c> is used for
+    /// the initial selection.
+    /// </param>
     public static void SetLanguage(SystemLanguage language, bool notify = true)
     {
         var localeCode = LanguageToLocaleCode(language);
@@ -140,7 +178,10 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Retrieves a localized string for the specified key.
+    /// Order: active locale, then English, then the key itself (so a missing key is visible in the UI).
     /// </summary>
+    /// <param name="key">Localization key, e.g. <c>"ui.render_config.window_title"</c>; case-sensitive.</param>
+    /// <returns>The localized text, the key when no locale has it, or an empty string for a null/empty key.</returns>
     public static string Get(string key)
     {
         if (string.IsNullOrEmpty(key)) return string.Empty;
@@ -166,7 +207,12 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Retrieves a formatted localized string.
+    /// The text from <see cref="Get(string)"/> is used as a <see cref="string.Format(string, object[])"/> template
+    /// (<c>{0}</c>, <c>{1}</c>, ...), formatted with the current culture. When the template does not match the
+    /// arguments (<see cref="FormatException"/>), the unformatted template is returned.
     /// </summary>
+    /// <param name="key">Localization key.</param>
+    /// <param name="args">Format arguments; with none, the template is returned as is.</param>
     public static string Get(string key, params object[] args)
     {
         var template = Get(key);
@@ -184,6 +230,7 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Maps Unity's SystemLanguage enum to an internal locale code.
+    /// Korean -> "ko"; every other language -> "en". A new locale file also needs an entry here.
     /// </summary>
     private static string LanguageToLocaleCode(SystemLanguage language)
     {
@@ -196,19 +243,22 @@ internal static class LocalizationManager
 
     /// <summary>
     /// Attempts to read the game's current language from RDString or Persistence.
+    /// Falls back to English when both reads throw.
     /// </summary>
     private static SystemLanguage DetectGameLanguage()
     {
         try
         {
-            // First attempt: RDString.language
+            // First attempt: RDString.language, a public static field of the game (initial value English,
+            // assigned from Persistence.language in RDString.Setup)
             return RDString.language;
         }
         catch
         {
             try
             {
-                // Fallback attempt: Persistence.language
+                // Fallback attempt: Persistence.language, the saved "language" preference (defaults to
+                // Application.systemLanguage)
                 return Persistence.language;
             }
             catch
@@ -221,6 +271,7 @@ internal static class LocalizationManager
 
 /// <summary>
 /// Convenient shorthand alias for <see cref="LocalizationManager"/>.
+/// Every member forwards to the member of the same name in <see cref="LocalizationManager"/>.
 /// </summary>
 // ReSharper disable once InconsistentNaming
 internal static class I18n