feat: Implement Marten multi-tenancy for localized projections by generating tenant-specific projection documents and removing the old localization helper.

Author: aalmada

docs/localization-guide.md

@@ -4,159 +4,137 @@ This guide explains how to configure and use localization in the BookStore API.
 
 ## Overview
 
-The BookStore API supports multiple languages for localized content (category names, book descriptions, author biographies). The API automatically detects the client's preferred language from the `Accept-Language` HTTP header and returns localized content accordingly.
+The BookStore API supports multiple languages for localized content (category names, book descriptions, author biographies).
+
+**Architecture Strategy:**
+The localization strategy uses **Write-Time Localization** via **Marten's Conjoined Tenancy**.
+- **Events** contain all translations.
+- **Projections** are multi-tenanted, with one document stored per supported language (tenant).
+- **APIs** simply query the tenant corresponding to the user's preferred language.
+
+This approach ensures high performance by eliminating complex runtime fallback logic during data retrieval.
 
 ## Configuration
 
-### Two-Letter Language Codes
+### Supported Languages
 
-The API uses **two-letter ISO 639-1 language codes** for universal variant support:
+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-BR`).
 
+**Standard Configuration (Generic)**:
+Suitable for applications where a single translation per language works for all regions.
 ```json
 {
   "Localization": {
     "DefaultCulture": "en",
-    "SupportedCultures": ["pt", "en", "fr", "de", "es"]
+    "SupportedCultures": ["en", "pt", "fr", "de", "es"]
+  }
+}
+```
+
+**Regional Configuration (Specific)**:
+Suitable when you need different content for specific regions (e.g., "Color" vs "Colour").
+```json
+{
+  "Localization": {
+    "DefaultCulture": "en-US",
+    "SupportedCultures": ["en-US", "en-GB", "pt-PT", "pt-BR"]
   }
 }
 ```
 
-**Why two-letter codes?**
-- ✅ Any regional variant automatically maps to the base language (pt-BR, pt-PT, pt-AO → pt)
-- ✅ Simpler configuration - no need to list every regional variant
-- ✅ Easier maintenance - new regional variants work immediately
+### Marten Configuration
+
+Projections are configured as multi-tenanted to support separate documents for each culture. This is defined in `MartenConfigurationExtensions.cs`.
+
+```csharp
+options.Schema.For<BookSearchProjection>().MultiTenanted();
+options.Schema.For<AuthorProjection>().MultiTenanted();
+options.Schema.For<CategoryProjection>().MultiTenanted();
+```
+
+The system iterates through all configured `SupportedCultures` to generate a projection document for each one.
 
 ### Cache Configuration
 
-**Critical**: All localized endpoints must vary cache by `Accept-Language`:
+**Critical**: All localized endpoints must verify the cache by the `Accept-Language` header to ensure users receive the correct language version.
 
 ```csharp
 .CacheOutput(policy => policy
     .Expire(TimeSpan.FromMinutes(5))
     .SetVaryByHeader("Accept-Language"))
 ```
 
-Without this, cached responses ignore the language header.
-
 ## Translation Storage
 
-Translations can be **culture-specific** or **culture-invariant**:
+Translations are captured at the source in Domain Events using a dictionary.
 
-**Culture-Invariant** (recommended):
+**Mixed Storage Example**:
+You can store both generic and specific keys.
 ```json
 {
   "pt": "Programação",
-  "en": "Programming"
-}
-```
-
-**Hybrid** (specific + invariant):
-```json
-{
   "pt-BR": "Programação (Brasil)",
-  "pt": "Programação",
   "en": "Programming"
 }
 ```
 
-## Fallback Strategy
+## Fallback Strategy (Write-Time)
+
+The API applies fallback logic **during projection generation** to ensure every supported culture has content.
 
-The API uses a 6-step fallback to find the best translation:
+**Logic sequence for a target culture (e.g., `pt-BR`):**
 
-1. Exact preferred culture (e.g., `"pt-PT"`)
-2. Two-letter preferred code (e.g., `"pt"`)
-3. Exact default culture (e.g., `"en"`)
-4. Two-letter default code (e.g., `"en"`)
-5. First available translation
-6. Default value (empty string)
+1. **Exact Match**: Look for a translation with key `"pt-BR"`.
+2. **Parent Culture**: Look for a translation with key `"pt"`.
+3. **Default Culture**: Look for a translation with the key of the `DefaultCulture`.
+4. **Any**: Use the first available translation.
+5. **Empty**: Fallback to an empty string.
 
-**Example**: Request with `Accept-Language: pt-BR`
-- Tries `"pt-BR"` → `"pt"` → `"en"` → first available → default
-- With hybrid translations above, returns `"Programação (Brasil)"`
+This robust fallback ensures that even if a specific translation is missing, the system provides the most relevant available content.
 
 ## Usage
 
 ### Making Requests
 
-Include the `Accept-Language` header in your HTTP requests:
+Clients request a specific language using the `Accept-Language` header.
 
 ```http
 GET /api/books HTTP/1.1
 Accept-Language: pt-BR
 ```
 
-The API returns localized content based on the header value.
+If the requested culture is not supported (e.g., `ja-JP`), the API will automatically fall back to the configured `DefaultCulture`.
 
-### Testing Different Languages
+### Endpoint Implementation
 
-**Using curl**:
-```bash
-curl -H "Accept-Language: pt" https://localhost:7001/api/categories
-curl -H "Accept-Language: en" https://localhost:7001/api/categories
-```
-
-**Using Postman/Insomnia**:
-1. Add header: `Accept-Language: pt`
-2. Send request
-3. Observe localized response
+Endpoints are simplified to purely read operations. They resolve the current culture (handled by ASP.NET Core middleware) and query the corresponding database tenant.
 
-## Localized Endpoints
-
-All public-facing endpoints return localized content:
+```csharp
+// 1. Resolve culture (e.g., "pt-BR")
+var culture = CultureInfo.CurrentCulture.Name;
 
-- **Categories** (`/api/categories`): Category names
-- **Books** (`/api/books`): Descriptions, category names, author biographies, language display names
-- **Authors** (`/api/authors`): Author biographies
+// 2. Open a session specific to that culture
+await using var session = store.QuerySession(culture);
 
-## Implementation Details
+// 3. Query normally - Marten automatically filters by the tenant
+var books = await session.Query<BookSearchProjection>().ToListAsync();
+```
 
-The localization system uses:
-- **ASP.NET Core Middleware**: `RequestLocalizationMiddleware` determines culture from `Accept-Language` header
-- **LocalizationHelper**: Centralized helper with reusable methods:
-  - `GetLocalizedValue<T>()`: Generic method for translating any `Dictionary<string, T>`
-  - `LocalizeLanguageName()`: Gets localized display names for language codes
-  - `GetPreferredCulture()`: Retrieves user's preferred culture from middleware
-- **Generic Translation Support**: Works with any translation type via selector functions
-- **Null Safety**: Uses `[NotNullWhen(true)]` attribute for compile-time null safety
+### Projection Implementation
 
-### Usage Example
+Projections are responsible for "fanning out" changes to all supported cultures. When an event (like `BookAdded`) occurs, the projection updates the documents for **all** configured tenants.
 
 ```csharp
-// Localize category name
-var localizedName = LocalizationHelper.GetLocalizedValue(
-    context,
-    options,
-    category.Translations,
-    translation => translation.Name,
-    defaultValue: "Unknown");
-
-// Get localized language name
-var languageName = LocalizationHelper.LocalizeLanguageName(
-    "en",
-    context,
-    options); // Returns "English" or "Inglês" depending on user's language
+foreach (var culture in _localization.SupportedCultures)
+{
+    using var tenantSession = session.ForTenant(culture);
+    
+    var projection = new BookSearchProjection
+    {
+        // ... map fields ...
+        Description = GetLocalizedDescription(@event.Data.Translations, culture)
+    };
+    
+    tenantSession.Store(projection);
+}
 ```
-
-## Best Practices
-
-1. **Use two-letter codes**: Configure `SupportedCultures` with two-letter codes for universal variant support
-2. **Use culture-invariant translations**: Store translations with two-letter keys unless region-specific content is needed
-3. **Always vary cache by Accept-Language**: Ensure cached responses are language-specific
-4. **Provide fallbacks**: Always include default culture translations
-5. **Validate culture codes**: Use `CultureCache.IsValidCultureCode()` to validate codes before use
-
-## Troubleshooting
-
-### Translations not working
-- ✅ Check `Accept-Language` header is being sent
-- ✅ Verify culture code is in `SupportedCultures`
-- ✅ Ensure cache varies by `Accept-Language`
-- ✅ Check translation dictionary has the expected keys
-
-### Always returning same language
-- ✅ Verify cache configuration includes `.SetVaryByHeader("Accept-Language")`
-- ✅ Clear cache and retry
-
-### Regional variant not working
-- ✅ Ensure `SupportedCultures` uses two-letter codes
-- ✅ Check translation dictionary has two-letter key (e.g., `"pt"` not `"pt-PT"`)

src/ApiService/BookStore.ApiService/Endpoints/AuthorEndpoints.cs

@@ -6,6 +6,7 @@
 using Microsoft.AspNetCore.Http.HttpResults;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Options;
+using System.Globalization;
 
 namespace BookStore.ApiService.Endpoints;
 
@@ -31,24 +32,23 @@ public static RouteGroupBuilder MapAuthorEndpoints(this RouteGroupBuilder group)
     }
 
     static async Task<Ok<PagedListDto<AuthorDto>>> GetAuthors(
-        [FromServices] IQuerySession session,
+        [FromServices] IDocumentStore store,
         [FromServices] IOptions<PaginationOptions> paginationOptions,
-        [FromServices] IOptions<LocalizationOptions> localizationOptions,
         [AsParameters] PagedRequest request,
         HttpContext context)
     {
+        var culture = CultureInfo.CurrentCulture.Name;
+        await using var session = store.QuerySession(culture);
         var paging = request.Normalize(paginationOptions.Value);
 
-        // Use Marten's native pagination for optimal performance
         var pagedList = await session.Query<AuthorProjection>()
             .OrderBy(a => a.Name)
             .ToPagedListAsync(paging.Page!.Value, paging.PageSize!.Value);
 
-        // Map to DTOs with localized biographies
         var authorDtos = pagedList.Select(author => new AuthorDto(
             author.Id,
             author.Name,
-            LocalizeBiography(author, context, localizationOptions.Value)
+            author.Biography
         )).ToList();
 
         return TypedResults.Ok(new PagedListDto<AuthorDto>(
@@ -58,12 +58,14 @@ static async Task<Ok<PagedListDto<AuthorDto>>> GetAuthors(
             pagedList.TotalItemCount));
     }
 
-    static async Task<Microsoft.AspNetCore.Http.HttpResults.Results<Ok<AuthorDto>, NotFound>> GetAuthor(
+    static async Task<Results<Ok<AuthorDto>, NotFound>> GetAuthor(
         Guid id,
-        [FromServices] IQuerySession session,
-        [FromServices] IOptions<LocalizationOptions> localizationOptions,
+        [FromServices] IDocumentStore store,
         HttpContext context)
     {
+        var culture = CultureInfo.CurrentCulture.Name;
+        await using var session = store.QuerySession(culture);
+        
         var author = await session.LoadAsync<AuthorProjection>(id);
         if (author == null)
         {
@@ -73,27 +75,8 @@ static async Task<Ok<PagedListDto<AuthorDto>>> GetAuthors(
         var authorDto = new AuthorDto(
             author.Id,
             author.Name,
-            LocalizeBiography(author, context, localizationOptions.Value));
+            author.Biography);
 
         return TypedResults.Ok(authorDto);
     }
-
-    // Helper method for author biography localization
-    static string? LocalizeBiography(
-        AuthorProjection author,
-        HttpContext context,
-        LocalizationOptions options)
-    {
-        if (author.Translations.Count == 0)
-        {
-            return null;
-        }
-
-        return LocalizationHelper.GetLocalizedValue(
-            context,
-            options,
-            author.Translations,
-            translation => translation.Biography,
-            defaultValue: string.Empty);
-    }
 }