Services

This page is about using localization-related types in your code once Localization and Application are filled in appsettings (see Configuration). The DevKit binds those sections to injectable objects so Razor, Blazor, use cases, and APIs can all read the same picture of languages and branding.

ApplicationSettings

• Namespace: CodeBlock.DevKit.Contracts.Models
• What you use it for: read ApplicationSettings.Localized anywhere you need the current culture’s app name, description, URLs, support email, or logo path—already merged with Default so you do not hand-merge JSON yourself.

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

namespace CodeBlock.DevKit.Contracts.Models;

/// <summary>
/// Configuration model for application-wide settings including localization support.
/// Provides centralized application configuration with culture-specific overrides.
/// </summary>
public class ApplicationSettings
{
    /// <summary>
    /// Initializes a new instance with an empty localizations dictionary.
    /// </summary>
    public ApplicationSettings()
    {
        Localizations = new Dictionary<string, LocalizedApplicationSettings>();
    }

    /// <summary>
    /// Default application settings used as fallback when localized settings are not available
    /// </summary>
    public LocalizedApplicationSettings Default { get; set; }

    /// <summary>
    /// Dictionary of culture-specific application settings keyed by culture code
    /// </summary>
    public IDictionary<string, LocalizedApplicationSettings> Localizations { get; set; }

    /// <summary>
    /// Gets the localized application settings for the current culture.
    /// Falls back to default settings if localization is not available.
    /// </summary>
    public LocalizedApplicationSettings Localized => ResolveSettings();

    /// <summary>
    /// Resolves the appropriate application settings based on the current culture.
    /// Attempts to find culture-specific settings, falls back to default if not found.
    /// </summary>
    /// <returns>Localized application settings for the current culture</returns>
    private LocalizedApplicationSettings ResolveSettings()
    {
        var currentCultureCode = Thread.CurrentThread.CurrentCulture.Name;

        if (Localizations.TryGetValue(currentCultureCode, out var localizedSettings))
        {
            var resolvedUrl = localizedSettings.Url ?? Default.Url;
            return new LocalizedApplicationSettings
            {
                Name = localizedSettings.Name ?? Default.Name,
                Url = resolvedUrl,
                StaticUrl = localizedSettings.StaticUrl ?? Default.StaticUrl ?? resolvedUrl,
                SupportEmail = localizedSettings.SupportEmail ?? Default.SupportEmail,
                Description = localizedSettings.Description ?? Default.Description,
            };
        }

        // Ensure Default.StaticUrl falls back to Default.Url if not set
        var defaultUrl = Default.Url;
        return new LocalizedApplicationSettings
        {
            Name = Default.Name,
            Url = defaultUrl,
            StaticUrl = Default.StaticUrl ?? defaultUrl,
            SupportEmail = Default.SupportEmail,
            Description = Default.Description,
        };
    }
}

/// <summary>
/// Culture-specific application settings containing localized application information.
/// Provides localized values for application name, description, URL, static files URL, and support contact.
/// </summary>
public class LocalizedApplicationSettings
{
    /// <summary>
    /// Localized name of the application
    /// </summary>
    public string Name { get; init; }

    /// <summary>
    /// Localized description of the application
    /// </summary>
    public string Description { get; init; }

    /// <summary>
    /// URL for the application in the specific culture
    /// </summary>
    public string Url { get; set; }

    /// <summary>
    /// Base URL for static files (images, assets, etc.) in the specific culture.
    /// Falls back to Url if not provided.
    /// </summary>
    public string StaticUrl { get; set; }

    /// <summary>
    /// Support email address for the specific culture
    /// </summary>
    public string SupportEmail { get; set; }
}

Typical uses: layout headers, splash screens, footers, <meta> tags, and emails that should show the right product name for the active language.

LocalizationSettings

• Namespace: CodeBlock.DevKit.Web.Localization
• What you use it for: the list of supported languages, which one is default, which language is active now, text direction, font string for the page, and helpers like HasMoreThanOneLanguage() when you want to hide a language switcher.

// Copyright (c) CodeBlock.Dev. All rights reserved.
// For more information visit https://codeblock.dev

namespace CodeBlock.DevKit.Web.Localization;

/// <summary>
/// Configuration settings for application localization and multi-language support.
/// Manages supported languages, default language, and language-specific properties like fonts and text direction.
/// </summary>
public class LocalizationSettings
{
    private const string DEFAULT_COOKIE_NAME = "CodeBlock.DevKit.Culture";

    /// <summary>
    /// Initializes localization settings with default cookie name for storing user's culture preference.
    /// </summary>
    public LocalizationSettings()
    {
        CookieName = DEFAULT_COOKIE_NAME;
    }

    /// <summary>
    /// Name of the cookie used to store the user's preferred culture/language.
    /// </summary>
    public string CookieName { get; set; }

    /// <summary>
    /// Collection of supported languages with their properties and configurations.
    /// </summary>
    public List<SupportedLanguage> Languages { get; set; }

    /// <summary>
    /// Checks if the specified language code is supported by the application.
    /// </summary>
    /// <param name="code">The language code to check (e.g., "en-US", "fr-FR")</param>
    /// <returns>True if the language is supported; otherwise, false</returns>

    public bool HasLanguage(string code)
    {
        return Languages.Any(l => l.Code == code);
    }

    /// <summary>
    /// Determines if the application supports more than one language.
    /// Useful for conditionally showing language switcher UI.
    /// </summary>
    /// <returns>True if multiple languages are supported; otherwise, false</returns>

    public bool HasMoreThanOneLanguage()
    {
        return Languages.Count > 1;
    }

    /// <summary>
    /// Gets the display name of a language by its code.
    /// </summary>
    /// <param name="code">The language code</param>
    /// <returns>The language name or null if not found</returns>

    public string GetLanguageName(string code)
    {
        var language = Languages.FirstOrDefault(l => l.Code == code);

        return language?.Name;
    }

    /// <summary>
    /// Gets the text direction (LTR/RTL) for the current language.
    /// Useful for supporting right-to-left languages like Arabic or Hebrew.
    /// </summary>
    /// <returns>The text direction ("ltr" or "rtl")</returns>

    public string GetCurrentLanguageDirection()
    {
        var language = Languages.FirstOrDefault(l => l.Code == GetCurrentLanguageCode());

        return language?.Direction;
    }

    /// <summary>
    /// Gets the recommended font for a specific language.
    /// Useful for ensuring proper text rendering for different scripts.
    /// </summary>
    /// <param name="langeCode">The language code</param>
    /// <returns>The recommended font name or null if not found</returns>

    public string GetFont(string langeCode)
    {
        var language = Languages.FirstOrDefault(l => l.Code == langeCode);

        return language?.Font;
    }

    /// <summary>
    /// Gets the default language code configured for the application.
    /// </summary>
    /// <returns>The default language code</returns>

    public string GetDefaultLanguageCode()
    {
        var defaultLanguage = GetDefaultLanguage();

        return defaultLanguage.Code;
    }

    /// <summary>
    /// Gets an array of all supported language codes.
    /// Useful for populating language selection dropdowns.
    /// </summary>
    /// <returns>Array of supported language codes</returns>

    public string[] GetLanguageCodes()
    {
        return Languages.Select(l => l.Code).ToArray();
    }

    /// <summary>
    /// Gets the current language code from the current thread's culture.
    /// </summary>
    /// <returns>The current language code</returns>

    public string GetCurrentLanguageCode()
    {
        return Thread.CurrentThread.CurrentCulture.Name;
    }

    /// <summary>
    /// Gets the recommended font for the current language.
    /// </summary>
    /// <returns>The recommended font name or null if not found</returns>

    public string GetCurrentLanguageFont()
    {
        var language = Languages.FirstOrDefault(l => l.Code == GetCurrentLanguageCode());

        return language?.Font;
    }

    /// <summary>
    /// Gets the display name of the current language.
    /// </summary>
    /// <returns>The current language name or null if not found</returns>

    public string GetCurrentLanguageName()
    {
        var language = Languages.FirstOrDefault(l => l.Code == GetCurrentLanguageCode());

        return language?.Name;
    }

    /// <summary>
    /// Gets the short name of the current language.
    /// </summary>
    /// <returns>The current language short name or null if not found</returns>

    public string GetCurrentLanguageShortName()
    {
        var language = Languages.FirstOrDefault(l => l.Code == GetCurrentLanguageCode());

        return language?.ShortName;
    }

    /// <summary>
    /// Creates a default localization settings instance with English as the default language.
    /// Used when no configuration is provided in appsettings.json.
    /// </summary>
    /// <returns>Default localization settings with English language</returns>

    public static LocalizationSettings CreateDefault()
    {
        return new LocalizationSettings
        {
            CookieName = DEFAULT_COOKIE_NAME,
            Languages = new List<SupportedLanguage> { SupportedLanguage.CreateDefault() },
        };
    }

    /// <summary>
    /// Gets the default language from the configured languages.
    /// Falls back to the first language if no default is specified.
    /// </summary>
    /// <returns>The default language or first available language</returns>
    private SupportedLanguage GetDefaultLanguage()
    {
        var defaultLanguage = Languages.FirstOrDefault(l => l.IsDefault);
        var firstLanguage = Languages.FirstOrDefault();

        return defaultLanguage ?? firstLanguage;
    }
}

/// <summary>
/// Represents a supported language with its properties and configuration.
/// Contains language metadata like name, code, direction, and font preferences.
/// </summary>
public class SupportedLanguage
{
    /// <summary>
    /// Full display name of the language (e.g., "English", "Français").
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// Short name of the language (e.g., "En", "Fr").
    /// </summary>
    public string ShortName { get; set; }

    /// <summary>
    /// Culture code of the language (e.g., "en-US", "fr-FR").
    /// </summary>
    public string Code { get; set; }

    /// <summary>
    /// Text direction: "ltr" for left-to-right, "rtl" for right-to-left.
    /// </summary>
    public string Direction { get; set; }

    /// <summary>
    /// Recommended font for rendering text in this language.
    /// </summary>
    public string Font { get; set; }

    /// <summary>
    /// Whether this language is the default language for the application.
    /// </summary>
    public bool IsDefault { get; set; }

    /// <summary>
    /// Creates a default English language configuration.
    /// Used as fallback when no languages are configured.
    /// </summary>
    /// <returns>Default English language settings</returns>
    public static SupportedLanguage CreateDefault()
    {
        return new SupportedLanguage()
        {
            Direction = "ltr",
            Font = "RobotoMedium",
            Name = "English",
            Code = "en-US",
            ShortName = "En",
            IsDefault = true,
        };
    }
}

Typical uses: language menus, dir/lang on the document, applying a per-language font in markup, or any UI that should react when the user changes language.

IStringLocalizer / IStringLocalizer<T>

For longer or repeated copy (labels, messages, validation text), inject IStringLocalizer<TResource> where TResource is the marker type for a .resx—in the template that is often SharedResource. The same abstraction works in services, Razor, Blazor, and API code as long as the host registers localization (which DevKit’s web setup does).

Copy-pastable examples live in Tutorials.

Web UI vs API

Razor and Blazor hosts remember the visitor’s language in a cookie whose name comes from LocalizationSettings.CookieName; that drives the culture behind Localized and GetCurrentLanguage* helpers on normal page loads.

HTTP API hosts do not use that cookie for incoming API calls. Callers instead send a language hint on each request; see Choose language on API calls.