Refactor docs and naming in LocalizationManager for clarity

- Rewrite and expand XML documentation for InvalidationKey and LocalizationManager, including detailed parameter and method descriptions.
- Rename constructor parameter from db to dbContext and update all references for consistency.
- Improve method summaries and remarks to clarify async behavior, cache invalidation, and distributed scenarios.
- Enhance BuildCacheKey documentation for formatting and culture handling.
- No functional changes; improves code readability and maintainability.

Author: AngeloDotNet

src/TinyLocalization/Services/InvalidationPayloads.cs

@@ -1,10 +1,8 @@
 namespace TinyLocalization.Services;
 
 /// <summary>
-/// Payload element used for resource-level invalidation: a pair containing a translation <see cref="Key"/>
-/// and the target <see cref="Culture"/>. Instances of this record are typically included in resource-level
-/// invalidation messages to indicate which specific keys and cultures should be evicted or refreshed by subscribers.
+/// Represents a unique key for invalidation, consisting of a key string and a culture identifier.
 /// </summary>
-/// <param name="Key">The translation key within the resource to be invalidated.</param>
-/// <param name="Culture">The culture name (for example "en" or "en-US") whose cached entry should be invalidated.</param>
+/// <param name="Key">The unique identifier used for invalidation purposes.</param>
+/// <param name="Culture">The culture associated with the key, which may influence localization or regional settings.</param>
 public record InvalidationKey(string Key, string Culture);

src/TinyLocalization/Services/LocalizationManager.cs

@@ -8,58 +8,68 @@
 namespace TinyLocalization.Services;
 
 /// <summary>
-/// Manager that modifies the translations database and invalidates associated FusionCache keys.
+/// Provides methods for managing localization resources, including adding, updating, removing, and invalidating
+/// translations across different cultures. Ensures consistency between the underlying database and the cache for
+/// localized content.
 /// </summary>
-/// <param name="db">The <see cref="LocalizationDbContext"/> used to access translations in the database.</param>
-/// <param name="fusionCache">The <see cref="IFusionCache"/> used for local caching of translations.</param>
-/// <param name="options">Options controlling localization behavior, including cache key prefix.</param>
-/// <param name="publisher">Optional publisher used to broadcast cache invalidations to other instances.</param>
-public class LocalizationManager(LocalizationDbContext db, IFusionCache fusionCache, DbLocalizationOptions options,
+/// <remarks>This class is designed for scenarios where localization data may be updated at runtime and must be
+/// kept consistent across multiple application instances. It provides asynchronous operations to ensure that changes to
+/// translations are reflected in both the database and the cache, and supports distributed cache invalidation when a
+/// publisher is supplied.</remarks>
+/// <param name="dbContext">The database context used to access and persist localization data.</param>
+/// <param name="fusionCache">The cache instance used to store and retrieve localization resources for improved performance.</param>
+/// <param name="options">The options that configure the behavior of the localization manager, such as cache key prefix settings.</param>
+/// <param name="publisher">An optional publisher used to broadcast cache invalidation messages to other application instances. If not provided,
+/// cache invalidation is performed only locally.</param>
+public class LocalizationManager(LocalizationDbContext dbContext, IFusionCache fusionCache, DbLocalizationOptions options,
     ICacheInvalidationPublisher? publisher = null) : ILocalizationManager
 {
     /// <summary>
-    /// Builds the cache key used to store a translation in the cache.
+    /// Generates a unique cache key that combines the specified resource identifier, key, and culture information.
     /// </summary>
-    /// <param name="resource">The resource name the translation belongs to.</param>
-    /// <param name="key">The translation key.</param>
-    /// <param name="culture">
-    /// The culture identifier for the translation. If <see cref="string.IsNullOrEmpty(string)"/> is true,
-    /// an underscore ("_") segment is used to represent the empty culture in the key.
-    /// </param>
-    /// <returns>A string representing the full cache key for the given resource/key/culture combination.</returns>
+    /// <remarks>Use this method to ensure that cache keys are consistently formatted and unique across
+    /// different resources and cultures. This is particularly useful in localization scenarios where cache entries must
+    /// be separated by culture.</remarks>
+    /// <param name="resource">The resource identifier used to distinguish the cache entry. Cannot be null.</param>
+    /// <param name="key">The unique key associated with the resource for cache retrieval. Cannot be null.</param>
+    /// <param name="culture">The culture name used to differentiate cache entries for localization. If null or empty, a default segment is
+    /// used.</param>
+    /// <returns>A formatted string representing the complete cache key, including the cache key prefix, resource, key, and
+    /// culture segment.</returns>
     private string BuildCacheKey(string resource, string key, string culture)
     {
         var cultureSegment = string.IsNullOrEmpty(culture) ? "_" : culture;
         return $"{options.CacheKeyPrefix}:{resource}:{key}:{cultureSegment}";
     }
 
     /// <summary>
-    /// Adds a new translation or updates an existing one in the database, then invalidates the corresponding cache entry.
+    /// Adds a new translation or updates an existing translation asynchronously in the database for the specified
+    /// resource, key, and culture.
     /// </summary>
-    /// <param name="translation">The <see cref="Translation"/> entity to add or update.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
-    /// <returns>A task that represents the asynchronous operation.</returns>
-    /// <remarks>
-    /// If a translation with the same resource, key and culture already exists it will be updated; otherwise a new entry
-    /// will be added. After persisting changes it removes the matching FusionCache key locally and, when a publisher is
-    /// provided, publishes a single-item invalidation to other instances.
-    /// </remarks>
+    /// <remarks>If a translation with the same resource, key, and culture already exists, its value is
+    /// updated; otherwise, a new translation is added. After the operation, the local cache for the affected
+    /// translation is invalidated, and an invalidation message is published to other instances if a publisher is
+    /// available.</remarks>
+    /// <param name="translation">The translation to add or update. The resource, key, and culture identify the translation entry; the value is
+    /// stored or updated.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+    /// <returns>A task that represents the asynchronous add or update operation.</returns>
     public async Task AddOrUpdateAsync(Translation translation, CancellationToken cancellationToken = default)
     {
-        var existing = await db.Translations.FirstOrDefaultAsync(t
+        var existing = await dbContext.Translations.FirstOrDefaultAsync(t
             => t.Resource == translation.Resource && t.Key == translation.Key && t.Culture == translation.Culture, cancellationToken);
 
         if (existing == null)
         {
-            db.Translations.Add(translation);
+            dbContext.Translations.Add(translation);
         }
         else
         {
             existing.Value = translation.Value;
-            db.Translations.Update(existing);
+            dbContext.Translations.Update(existing);
         }
 
-        await db.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesAsync(cancellationToken);
 
         // Invalidate cache for that exact resource/key/culture locally
         var cacheKey = BuildCacheKey(translation.Resource, translation.Key, translation.Culture);
@@ -73,32 +83,29 @@ public async Task AddOrUpdateAsync(Translation translation, CancellationToken ca
     }
 
     /// <summary>
-    /// Removes a translation for the specified resource/key/culture from the database and invalidates the cache.
+    /// Removes a translation entry for the specified resource, key, and culture from the database asynchronously.
     /// </summary>
-    /// <param name="resource">The resource name the translation belongs to.</param>
-    /// <param name="key">The translation key to remove.</param>
-    /// <param name="culture">The culture identifier of the translation to remove.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
-    /// <returns>
-    /// A task that returns <c>true</c> if the translation was found and removed; otherwise <c>false</c> when no matching
-    /// translation exists.
-    /// </returns>
-    /// <remarks>
-    /// After removing the translation and saving changes the method removes the corresponding FusionCache entry locally
-    /// and, if a publisher is configured, publishes a single-item invalidation to other instances.
-    /// </remarks>
+    /// <remarks>This method also invalidates the local cache for the removed translation and publishes an
+    /// invalidation notification if a publisher is available. If no matching translation entry is found, no changes are
+    /// made.</remarks>
+    /// <param name="resource">The name of the resource associated with the translation entry to remove. Cannot be null.</param>
+    /// <param name="key">The key that identifies the specific translation entry to remove. Cannot be null.</param>
+    /// <param name="culture">The culture code that specifies which translation to remove. Cannot be null.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if the translation
+    /// entry was found and removed; otherwise, <see langword="false"/>.</returns>
     public async Task<bool> RemoveAsync(string resource, string key, string culture, CancellationToken cancellationToken = default)
     {
-        var existing = await db.Translations.FirstOrDefaultAsync(t
+        var existing = await dbContext.Translations.FirstOrDefaultAsync(t
             => t.Resource == resource && t.Key == key && t.Culture == culture, cancellationToken);
 
         if (existing == null)
         {
             return false;
         }
 
-        db.Translations.Remove(existing);
-        await db.SaveChangesAsync(cancellationToken);
+        dbContext.Translations.Remove(existing);
+        await dbContext.SaveChangesAsync(cancellationToken);
 
         // invalidate cache locally
         var cacheKey = BuildCacheKey(resource, key, culture);
@@ -114,20 +121,20 @@ public async Task<bool> RemoveAsync(string resource, string key, string culture,
     }
 
     /// <summary>
-    /// Invalidates all cached entries for a given resource across known cultures and keys.
+    /// Asynchronously invalidates all cached entries for the specified resource across all known cultures.
     /// </summary>
-    /// <param name="resource">The resource name whose cache entries should be invalidated.</param>
-    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
-    /// <returns>A task that represents the asynchronous operation.</returns>
-    /// <remarks>
-    /// The method enumerates the distinct cultures and keys for the resource in the database, removes the corresponding
-    /// FusionCache entries locally, and collects <see cref="InvalidationKey"/> instances to publish a resource-level
-    /// invalidation to other instances when a publisher is configured.
-    /// </remarks>
+    /// <remarks>This method removes all cache entries associated with the specified resource for each culture
+    /// present in the data store. If a publisher is available, a resource-level invalidation notification is published
+    /// after the cache entries are removed. Use this method to ensure that changes to a resource are reflected across
+    /// all cultures and that outdated translations are not served from the cache.</remarks>
+    /// <param name="resource">The name of the resource to invalidate. This parameter cannot be null or empty.</param>
+    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation. The default value is <see
+    /// cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation of invalidating the resource.</returns>
     public async Task InvalidateResourceAsync(string resource, CancellationToken cancellationToken = default)
     {
         // enumerate known cultures for this resource and remove corresponding keys
-        var cultures = await db.Translations
+        var cultures = await dbContext.Translations
             .Where(t => t.Resource == resource)
             .Select(t => t.Culture)
             .Distinct()
@@ -138,7 +145,7 @@ public async Task InvalidateResourceAsync(string resource, CancellationToken can
         foreach (var culture in cultures)
         {
             // for each key too
-            var keys = await db.Translations
+            var keys = await dbContext.Translations
                 .Where(t => t.Resource == resource && t.Culture == culture)
                 .Select(t => t.Key)
                 .Distinct()