Agency8.MyLocalizer 0.0.1

Agency8.MyLocalizer

Agency8.MyLocalizer is a .NET 9 class library for database-driven string localization, designed for ASP.NET Core applications. It provides a flexible, culture-aware localization system with support for custom cultures, caching, and integration with Entity Framework Core.

Features

• Database-backed localization: Store translations and cultures in a relational database.
• Culture management: Add, enable/disable, and set default cultures.
• Caching: In-memory cache for fast lookup of translations.
• Dependency Injection: Easily integrate with ASP.NET Core DI.
• Culture switching: Controller for runtime culture changes via cookies.
• Fallbacks: Automatic fallback to default or parent cultures.
• Extensible: Interfaces for custom repositories and cache implementations.

Installation

Add the NuGet package to your project:

dotnet add package Agency8.MyLocalizer

Getting Started

1. Configure Services

Register MyLocalizer in your Startup.cs or Program.cs:

services.AddMyLocalizer("YourConnectionString");

2. Configure Database

The library uses Entity Framework Core. Supported providers include SQL Server and SQLite.

• MyLocalizerDbContext manages two tables:
  • MyTranslations: Stores key/value pairs per culture.
  • MyCultures: Stores available cultures.

Tables are created automatically if they do not exist.

3. Use Middleware

Set the default culture at application startup:

await app.UseMyLocalizer("en-US");

4. Inject and Use Localizer

Inject IMyStringLocalizer into your controllers or services:

public class HomeController : Controller
{
    private readonly IMyStringLocalizer _localizer;

    public HomeController(IMyStringLocalizer localizer)
    {
        _localizer = localizer;
    }

    public IActionResult Index()
    {
        var greeting = _localizer["Hello"];
        return View(model: greeting);
    }
}

5. Change Culture at Runtime

Use the built-in controller to change the UI culture:

GET /MyCulture/Set?culture=fr-FR&redirectUri=/

API Overview

Entities

• MyTranslation: Represents a localized string for a specific culture.
• MyCulture: Represents a supported culture.

Services

• IMyStringLocalizer: Main interface for retrieving localized strings.
• LocalizationProvider: Handles lookup and fallback logic.
• ILocalizationCache: Interface for caching translations.

Extension Methods

• AddMyLocalizer(IServiceCollection, string): Registers all required services.
• UseMyLocalizer(IApplicationBuilder, string): Ensures tables exist and sets the default culture.

Example Database Schema

MyTranslations | Id (Guid) | Key (string) | Value (string) | Culture (string) | CultureId (Guid) |

MyCultures | Id (Guid) | CultureCode (string) | DisplayName (string) | IsEnabled (bool) | IsDefault (bool) |

Advanced Usage

• Custom Cache: Implement ILocalizationCache for distributed caching.
• Custom Repositories: Implement IMyCultureRepository or IMyTranslationRepository for advanced data access.
• Culture Change Notification: Use CultureChangeNotifier to react to culture changes.

License

See LICENSE.txt for details.

Contributing

Pull requests and issues are welcome! Please open an issue to discuss your ideas.

Support

For questions or support, open an issue on GitHub.