ccn/Packages/Localization/Sources/Public/Methods/Localize.swift

import Foundation

/// A reusable, bundle-bound localizer that resolves String Catalog entries for an explicit locale.
///
/// A server has no single "current" locale, so each lookup must name the locale to use. An instance
/// is bound to the bundle whose catalog holds the strings, then invoked like a function to resolve a
/// key in a chosen locale.
public struct Localize: Sendable {

    // MARK: Properties

    /// The backend that resolves keys against the catalog.
    private let resolver: any CatalogResolving

    // MARK: Initializers

    /// Creates a localizer backed by the String Catalog in the given bundle.
    /// - Parameters:
    ///   - bundle: the bundle whose String Catalog contains the keys to resolve.
    ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
    public init(
        bundle: Bundle,
        table: String = "Localizable"
    ) {
        self.init(resolver: StringCatalog(
            bundle: bundle,
            table: table
        ))
    }

    /// Creates a localizer backed by the given resolver.
    ///
    /// The seam for tests and alternative backends; the public API resolves against a bundled catalog.
    /// - Parameter resolver: the backend that resolves keys to localized strings.
    init(
        resolver: any CatalogResolving
    ) {
        self.resolver = resolver
    }

    // MARK: Methods

    /// Resolves a catalog key in the given locale.
    ///
    /// Invoked by calling the instance directly, for example `localize("index.title", locale: locale)`.
    /// - Parameters:
    ///   - key: the String Catalog key to look up.
    ///   - locale: the locale to resolve the key in.
    /// - Returns: the localized string for the locale, the source-language string when the locale has no
    ///   entry, or the key itself when the catalog has no entry for it.
    public func callAsFunction(
        _ key: String,
        locale: Locale
    ) -> String {
        resolver.string(
            for: key,
            in: locale
        )
    }

}