Fixes for the Localization package (#26)

This PR contains the work done to

Reviewed-on: rock-n-code/loud-amsterdam#26
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift

@@ -16,9 +16,13 @@ protocol CatalogResolving: Sendable {
 
     // MARK: Properties
 
-    /// The source (development) language, used as the final fallback when a locale has no localization.
+    /// The source (development) language, used as the final fallback when a locale has no localization
+    /// and as the default language a ``LanguageList`` serves.
     var sourceLanguage: String { get }
 
+    /// The outcome of reading the backing catalog, for consumers to surface at startup.
+    var state: CatalogState { get }
+
     /// Every language the backend can resolve strings for, including the source language.
     var languages: Set<String> { get }
 

Packages/Localization/Sources/Internal/Types/LanguageRange.swift

@@ -0,0 +1,18 @@
+/// A single language range parsed from an `Accept-Language` header entry.
+///
+/// A range pairs the language tag a client asked for with the `q` weight expressing how much the
+/// client prefers it, as RFC 9110 defines them. ``Negotiate`` parses each comma-separated header
+/// entry into one of these, then orders the ranges by descending weight so the most preferred tag
+/// is matched first.
+struct LanguageRange {
+
+    // MARK: Properties
+
+    /// The language tag the client asked for, such as `de` or `de-AT`, or the `*` wildcard.
+    let tag: String
+
+    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when
+    /// an entry names no weight).
+    let quality: Double
+
+}

Packages/Localization/Sources/Internal/Types/StringCatalog.swift

@@ -1,4 +1,5 @@
 import Foundation
+import Synchronization
 
 /// A decoded `.xcstrings` String Catalog, read directly from a bundle's resources.
 ///
@@ -18,6 +19,9 @@ struct StringCatalog: Sendable {
     /// The resolved entries, keyed by catalog key then by language code.
     let entries: [String: [String: String]]
 
+    /// The outcome of reading the catalog from its bundle.
+    let state: CatalogState
+
     // MARK: Computed
 
     /// Every language the catalog provides a localization for, including the source language.
@@ -46,8 +50,9 @@ struct StringCatalog: Sendable {
             forResource: table,
             withExtension: .Extension.stringCatalog
         ) else {
-            self.sourceLanguage = "en"
+            self.sourceLanguage = .Default.sourceLanguage
             self.entries = [:]
+            self.state = .missing
             return
         }
 
@@ -65,9 +70,59 @@ struct StringCatalog: Sendable {
                     (entry.localizations ?? [:])
                         .compactMapValues { $0.stringUnit?.value }
                 }
+            self.state = .loaded
         } catch {
-            self.sourceLanguage = "en"
+            self.sourceLanguage = .Default.sourceLanguage
             self.entries = [:]
+            self.state = .undecodable
+        }
+    }
+
+}
+
+// MARK: - Cache
+
+extension StringCatalog {
+
+    /// A cache key identifying a catalog by its bundle location and table name.
+    private struct Key: Hashable, Sendable {
+        let bundle: URL
+        let table: String
+    }
+
+    /// The decoded catalogs, keyed by bundle and table.
+    private static let cache = Mutex<[Key: StringCatalog]>([:])
+
+    /// Returns the catalog for the given bundle and table, decoding it on first access.
+    ///
+    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList``
+    /// bound to the same bundle shares one decoded catalog instead of re-reading its JSON.
+    /// - Parameters:
+    ///   - bundle: the bundle whose resources contain the String Catalog.
+    ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
+    /// - Returns: the decoded catalog, from the cache when it has been read before.
+    static func cached(
+        bundle: Bundle,
+        table: String = "Localizable"
+    ) -> StringCatalog {
+        let key = Key(
+            bundle: bundle.bundleURL,
+            table: table
+        )
+
+        return cache.withLock { cache in
+            if let catalog = cache[key] {
+                return catalog
+            }
+
+            let catalog = StringCatalog(
+                bundle: bundle,
+                table: table
+            )
+
+            cache[key] = catalog
+
+            return catalog
         }
     }
 
@@ -77,6 +132,9 @@ struct StringCatalog: Sendable {
 
 extension StringCatalog: CatalogResolving {
 
+    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its
+    /// primary language code (`pt`), then the source language, then the key itself. Tags are matched
+    /// case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
     func string(
         for key: String,
         in locale: Locale
@@ -85,15 +143,46 @@ extension StringCatalog: CatalogResolving {
             return key
         }
 
-        let language = locale
-            .language
-            .languageCode?
-            .identifier
-            ?? sourceLanguage
+        for tag in locale.catalogTags {
+            if let match = byLanguage.first(
+                where: { $0.key.lowercased() == tag }
+            ) {
+                return match.value
+            }
+        }
 
-        return byLanguage[language]
-            ?? byLanguage[sourceLanguage]
-            ?? key
+        return byLanguage[sourceLanguage] ?? key
+    }
+
+}
+
+// MARK: - Locale+Extensions
+
+private extension Locale {
+
+    /// The language tags to resolve a catalog entry against, most specific first.
+    ///
+    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes
+    /// `pt-br`), followed by its primary language code when the two differ.
+    var catalogTags: [String] {
+        var tags: [String] = []
+        let identifier = identifier
+            .replacingOccurrences(
+                of: String.Separator.underscore,
+                with: String.Separator.dash
+            )
+            .lowercased()
+
+        if !identifier.isEmpty {
+            tags.append(identifier)
+        }
+
+        if let code = language.languageCode?.identifier.lowercased(),
+           code != identifier {
+            tags.append(code)
+        }
+
+        return tags
     }
 
 }
@@ -127,7 +216,18 @@ private extension StringCatalog {
 // MARK: - String+Constants
 
 private extension String {
+    /// The source language assumed when a catalog is missing or cannot be decoded, matching the
+    /// package's default localization.
+    enum Default {
+        static let sourceLanguage = "en"
+    }
+
     enum Extension {
         static let stringCatalog = "xcstrings"
     }
+
+    enum Separator {
+        static let dash = "-"
+        static let underscore = "_"
+    }
 }