docs/localization: audit and update localization-guide.md

Author: aalmada

docs/guides/localization-guide.md

@@ -23,46 +23,51 @@ This approach ensures:
 
 ### Supported Languages
 
-The API is configured using **ISO 639-1 language codes**. You can configure either generic codes (e.g., `en`, `pt`) or specific regional cultures (e.g., `en-US`, `pt-PT`).
+The API is configured using **ISO 639-1 language codes**. You can configure either generic codes (e.g., `en`, `pt`) or specific regional cultures (e.g., `pt-PT`).
 
-**Standard Configuration (Generic)**:
+**Standard Configuration** (`appsettings.json`, section `"Localization"`):
 ```json
 {
   "Localization": {
     "DefaultCulture": "en",
-    "SupportedCultures": ["en", "pt", "fr", "de", "es"]
+    "SupportedCultures": ["en", "pt", "pt-PT", "es", "fr", "de"]
   }
 }
 ```
 
-**Regional Configuration (Specific)**:
-```json
-{
-  "Localization": {
-    "DefaultCulture": "en-US",
-    "SupportedCultures": ["en-US", "en-GB", "pt-PT", "pt-BR"]
-  }
-}
+The `LocalizationOptions` class (`src/BookStore.ApiService/Infrastructure/LocalizationOptions.cs`) binds this section. The default/fallback list used when no configuration is present is `["en", "pt", "pt-PT", "es", "fr", "de"]` with `"en"` as the default culture.
+
+The supported cultures are exposed at runtime via:
+
+```
+GET /api/config/localization
 ```
 
+This returns a `LocalizationConfigDto` containing `DefaultCulture` and `SupportedCultures[]`. The Web frontend calls this endpoint at startup to configure its own `RequestLocalizationOptions` (with `"en"` as the fallback if the backend is unavailable).
+
 ### Cache Configuration
 
-**Critical**: Localized content is cached using `HybridCache` with the `GetOrCreateLocalizedAsync` extension method, which automatically varies the cache by culture.
+**Critical**: Localized content is cached using `HybridCache` with the `GetOrCreateLocalizedAsync` extension method (`src/BookStore.ApiService/Infrastructure/Extensions/HybridCacheExtensions.cs`), which automatically appends `|{CultureInfo.CurrentUICulture.Name}` to the cache key.
+
+In practice, endpoints also include the culture explicitly in the base key alongside tenant and query parameters:
 
 ```csharp
+var culture = CultureInfo.CurrentUICulture.Name;
+var cacheKey = $"categories:tenant={tenantContext.TenantId}:culture={culture}:search={request.Search}:page={paging.Page}:size={paging.PageSize}:sort={normalizedSortBy}:{normalizedSortOrder}";
+
 var response = await cache.GetOrCreateLocalizedAsync(
-    $"category:{id}",
+    cacheKey,           // GetOrCreateLocalizedAsync appends "|{culture}" to this
     async cancel => { /* load from database */ },
     options: new HybridCacheEntryOptions
     {
         Expiration = TimeSpan.FromMinutes(5),
         LocalCacheExpiration = TimeSpan.FromMinutes(2)
     },
-    tags: [$"category:{id}"],
+    tags: [CacheTags.CategoryList],
     token: cancellationToken);
 ```
 
-The cache key automatically becomes `category:{id}|{culture}` (e.g., `category:123|en-US`, `category:123|pt-PT`).
+The final stored key is `categories:tenant=...:culture=en:...|en`. The culture appears twice (once in the explicit key for transparency, once appended by `GetOrCreateLocalizedAsync`), ensuring correct variation by tenant, culture, and query parameters.
 
 ## Translation Storage
 
@@ -173,7 +178,7 @@ static async Task<Ok<PagedListDto<CategoryDto>>> GetCategories(
     [FromServices] IOptions<LocalizationOptions> localizationOptions,
     HttpContext context)
 {
-    var culture = CultureInfo.CurrentCulture.Name;
+    var culture = CultureInfo.CurrentUICulture.Name;
     var defaultCulture = localizationOptions.Value.DefaultCulture;
     await using var session = store.QuerySession();
 
@@ -218,6 +223,74 @@ public class CategoryProjection
 }
 ```
 
+## Web Frontend Localization
+
+### How Culture Flows from Web to API
+
+The `BookStoreHeaderHandler` (`src/BookStore.Client/Infrastructure/BookStoreHeaderHandler.cs`) is a `DelegatingHandler` applied to all Refit clients. It automatically adds the `Accept-Language` header when absent:
+
+```csharp
+if (!request.Headers.Contains("Accept-Language"))
+{
+    var culture = CultureInfo.CurrentUICulture.Name;
+    if (!string.IsNullOrEmpty(culture))
+    {
+        request.Headers.AcceptLanguage.Add(new StringWithQualityHeaderValue(culture));
+    }
+}
+```
+
+This means the Blazor circuit's current UI culture is propagated transparently to every API call.
+
+### `RequestLocalizationOptions` in the Web
+
+At startup, `BookStore.Web/Program.cs` calls `GET /api/config/localization` to fetch the supported cultures from the API and configures its own `RequestLocalizationOptions` accordingly:
+
+```csharp
+var localizationConfig = await configClient.GetLocalizationConfigAsync();
+supportedCultures = [.. localizationConfig.SupportedCultures];
+defaultCulture = localizationConfig.DefaultCulture;
+
+var localizationOptions = new RequestLocalizationOptions()
+    .SetDefaultCulture(defaultCulture)
+    .AddSupportedCultures(supportedCultures)
+    .AddSupportedUICultures(supportedCultures);
+
+app.UseRequestLocalization(localizationOptions);
+```
+
+If the backend is unreachable at startup, the Web falls back to `["en"]` with default culture `"en"`.
+
+### `LanguageService`
+
+`src/BookStore.Web/Services/LanguageService.cs` wraps the configuration endpoint with an in-memory cache:
+
+- `GetSupportedLanguagesAsync()` — returns the supported culture codes (cached after first call, with fallback to `["en", "pt", "pt-PT", "es", "fr", "de"]` on error).
+- `GetLanguagesWithDisplayNamesAsync()` — returns a `Dictionary<string, string>` mapping code → display name in the current UI language.
+- `GetDefaultCultureAsync()` — returns the configured default culture (fallback: `"en"`).
+- `GetDisplayName(string cultureCode)` — static helper converting a culture code to its .NET display name.
+- `GetAllLanguages()` — enumerates all .NET cultures (used for selecting a book's primary written language, not the UI language).
+
+### Language Selector Components
+
+Two Blazor components provide language selection in the UI:
+
+| Component | File | Purpose |
+|---|---|---|
+| `<LanguageSelector>` | `Components/Shared/LanguageSelector.razor` | Selects a UI/content language from the **supported** cultures returned by the API. Shows "(Default)" next to the configured default. |
+| `<AllLanguageSelector>` | `Components/Shared/AllLanguageSelector.razor` | Selects from **all** .NET cultures. Used in admin dialogs to set a book's primary written language. |
+
+### Error Message Localization (`IStringLocalizer`)
+
+The Web project uses standard ASP.NET Core resource-based localization for UI error messages:
+
+- `AddLocalization(options => options.ResourcesPath = "Resources")` is registered in `Program.cs`.
+- `src/BookStore.Web/Services/ErrorLocalizationService.cs` injects `IStringLocalizer<ErrorLocalizationService>` and looks up error codes from resource files.
+- Default (English) strings live in `src/BookStore.Web/Resources/Services/ErrorLocalizationService.resx`.
+- To add a translated version, add `ErrorLocalizationService.{culture}.resx` (e.g., `ErrorLocalizationService.pt.resx`) in the same folder.
+
+This is distinct from the dictionary-based content localization used by the API — `.resx` files only cover UI error messages in the Web project.
+
 ## Testing
 
 ### Test Different Languages