namespace DigitalData.Core.Contracts.CultureServices
{
    /// <summary>
    /// Defines the interface for string localization, allowing retrieval of localized strings based on keys and arguments.
    /// This service facilitates internationalization by providing an easy way to manage and access localized text strings
    /// within an application, supporting dynamic content translation according to the current culture settings.
    /// </summary>
    public interface IKeyTranslationService
    {
        /// <summary>
        /// Retrieves the localized string associated with the specified key. This method is used
        /// when no additional formatting is required for the localized string.
        /// </summary>
        /// <param name="key">The key identifying the localized string in the resource files.</param>
        /// <returns>The localized string associated with the specified key. If the key does not exist,
        /// a fallback mechanism may return the key itself or a default message indicating the missing localization.</returns>
        string Translate(string key);

        /// <summary>
        /// Retrieves the localized string for the specified enum key. This method simplifies localization
        /// by allowing direct use of enum values as keys for retrieving localized strings.
        /// </summary>
        /// <param name="key">The enum value used as the key for the localized string.</param>
        /// <returns>The localized string associated with the specified enum key. If the corresponding string does not exist,
        /// a fallback mechanism may return the enum name itself or a default message indicating the missing localization.</returns>
        string Translate(Enum key) => Translate(key.ToString());

        /// <summary>
        /// Retrieves the formatted localized string for the specified key, using the provided arguments to format
        /// the string. This method is useful for localizing strings that require dynamic content insertion, such as
        /// names, dates, or numbers, which may vary in placement or format based on the culture.
        /// </summary>
        /// <param name="key">The key identifying the localized string in the resource files.</param>
        /// <param name="arguments">An object array that contains zero or more objects to format into the localized string.
        /// These objects are inserted into the localized string based on the current culture's formatting rules.</param>
        /// <returns>The formatted localized string associated with the specified key. If the key does not exist,
        /// a fallback mechanism may return a formatted string using the key and arguments, or a default message indicating
        /// the missing localization.</returns>
        string Translate(string key, params object[] arguments);

        /// <summary>
        /// Retrieves the formatted localized string for the specified enum key, using the provided arguments to format
        /// the string. This method extends the localization capabilities to enums, facilitating the use of enums as keys
        /// for retrieving formatted localized strings with dynamic content.
        /// </summary>
        /// <param name="key">The enum value used as the key for the localized string.</param>
        /// <param name="arguments">An object array that contains zero or more objects to format into the localized string.
        /// These objects are inserted into the localized string based on the current culture's formatting rules.</param>
        /// <returns>The formatted localized string associated with the specified enum key. If the corresponding string does not exist,
        /// a fallback mechanism may return a formatted string using the enum name and arguments, or a default message indicating
        /// the missing localization.</returns>
        string Translate(Enum key, params object[] arguments) => Translate(key.ToString(), arguments);
    }
}