namespace MyAi.Data.Services;

/// <summary>
/// Provides access to localised string templates stored in the <c>myAi.Templates</c> table.
/// Implementations are expected to cache templates and refresh periodically.
/// </summary>
public interface ITemplateService
{
    /// <summary>
    /// Returns the template value for the given key and language.
    /// Falls back to <c>"en"</c> when the requested language has no entry.
    /// Returns the raw key string when no matching template is found.
    /// </summary>
    /// <param name="key">Template key (e.g. <c>"html.job-search-start.title"</c>).</param>
    /// <param name="language">Two-letter language code (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
    /// <returns>Template value string.</returns>
    string Get(string key, string language = "en");

    /// <summary>
    /// Retrieves the template and substitutes <c>{{placeholder}}</c> tokens with the provided values.
    /// </summary>
    /// <param name="key">Template key.</param>
    /// <param name="language">Two-letter language code.</param>
    /// <param name="placeholders">Named replacement pairs in the form <c>("name", value)</c>.</param>
    /// <returns>Rendered template string with all placeholders replaced.</returns>
    string Render(string key, string language, params (string Key, string Value)[] placeholders);
}