rock-n-code/ccn
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

Fixes for the Localization package (#26)

Browse Source 
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>
This commit is contained in:
javier
2026-07-28 23:37:33 +00:00
committed by javier
parent cdded06ba3
commit 0887135328
16 changed files with 518 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
+5 -1
View File
@@ -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
+18
View File
@@ -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
+110 -10
View File
@@ -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 = "_"
}
}
Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
+17
View File
@@ -0,0 +1,17 @@
/// The outcome of reading a String Catalog from its bundle.
///
/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the
/// language list falls back to the default language — so nothing fails at the call site. This state is
/// the signal a server checks once at startup to warn before visitors ever see raw localization keys.
public enum CatalogState: Equatable, Sendable {
/// The catalog was found and decoded; its entries are resolvable.
case loaded
/// No catalog resource exists in the bundle; every lookup returns its key.
case missing
/// The catalog resource exists but is not valid `.xcstrings` JSON; every lookup returns its key.
case undecodable
}
Packages/Localization/Sources/Public/Methods/Localize.swift
+11 -1
View File
@@ -12,6 +12,16 @@ public struct Localize: Sendable {
/// The backend that resolves keys against the catalog.
private let resolver: any CatalogResolving
// MARK: Computed
/// The outcome of reading the bundle's String Catalog.
///
/// Resolution degrades to returning raw keys rather than failing, so check this once at startup
/// and warn when it is not ``CatalogState/loaded``.
public var catalogState: CatalogState {
resolver.state
}
// MARK: Initializers
/// Creates a localizer backed by the String Catalog in the given bundle.
@@ -22,7 +32,7 @@ public struct Localize: Sendable {
bundle: Bundle,
table: String = "Localizable"
) {
self.init(resolver: StringCatalog(
self.init(resolver: StringCatalog.cached(
bundle: bundle,
table: table
))
Packages/Localization/Sources/Public/Methods/Negotiate.swift
+96 -35
View File
@@ -4,7 +4,8 @@ import Foundation
///
/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
/// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
/// supported language identifier, falling back to the default language.
/// supported language identifier, honouring the header's `q` weights as RFC 9110 prescribes and
/// falling back to the default language.
public struct Negotiate: Sendable {
// MARK: Properties
@@ -27,10 +28,12 @@ public struct Negotiate: Sendable {
/// Picks the best supported language for the given `Accept-Language` header value.
///
/// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
/// The header is split into its language tags (dropping any `q` weights), then each tag is matched
/// against the supported languages in order of preference — first by an exact match, then by its
/// primary language subtag, so `de-AT` resolves to a supported `de`. When the header is absent or
/// matches nothing, the default language is returned.
/// The header is parsed into its language ranges, which are ordered by descending `q` weight as
/// RFC 9110 prescribes: an entry without a weight counts as 1, entries weighted 0 are
/// "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched
/// against the supported languages in turn — first by an exact match, then by its primary language
/// subtag, so `de-AT` resolves to a supported `de` — while the `*` wildcard accepts the default
/// language. When the header is absent or matches nothing, the default language is returned.
/// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
/// - Returns: the identifier of the supported language to serve.
public func callAsFunction(
@@ -40,16 +43,20 @@ public struct Negotiate: Sendable {
return list.default
}
let tags = tags(from: language)
let ranges = ranges(from: language)
guard !tags.isEmpty else {
guard !ranges.isEmpty else {
return list.default
}
let supported = list.all
for tag in tags {
if let match = match(tag: tag, in: supported) {
for range in ranges {
if range.tag == .wildcard {
return list.default
}
if let match = match(range.tag, in: supported) {
return match
}
}
@@ -65,27 +72,69 @@ private extension Negotiate {
// MARK: Methods
/// Extracts the ordered language tags from an `Accept-Language` header value.
/// Parses an `Accept-Language` header value into its ``LanguageRange`` list, ordered by preference.
///
/// Each comma-separated entry is reduced to its language tag by dropping the `;q=` weight, and
/// blank entries are removed. The original order is kept, which mirrors descending preference
/// closely enough for `preferredLocalizations(from:forPreferences:)` to resolve correctly.
/// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by
/// descending weight, entries weighted 0 are dropped as "not acceptable", and equally weighted
/// entries keep the header order.
/// - Parameter acceptLanguage: the raw `Accept-Language` header value.
/// - Returns: the ordered, weight-stripped language tags.
func tags(
/// - Returns: the language ranges, most preferred first.
func ranges(
from acceptLanguage: String
) -> [String] {
) -> [LanguageRange] {
acceptLanguage
.split(separator: .Separator.comma)
.map { entry in
entry
.split(separator: .Separator.semicolon)
.first
.map(String.init)?
.trimmingCharacters(in: .whitespaces)
?? .empty
.compactMap(range(from:))
.filter { $0.quality > 0 }
.enumerated()
.sorted { lhs, rhs in
lhs.element.quality == rhs.element.quality
? lhs.offset < rhs.offset
: lhs.element.quality > rhs.element.quality
}
.filter { !$0.isEmpty }
.map(\.element)
}
/// Parses a single `Accept-Language` header entry into its ``LanguageRange``.
///
/// The entry's language tag precedes the first `;`; a `q` parameter after it sets the weight.
/// A missing or malformed weight counts as 1, the highest preference, matching a tag sent
/// without one.
/// - Parameter entry: a single comma-separated header entry.
/// - Returns: the entry's language range, or `nil` when it has no language tag.
func range(
from entry: Substring
) -> LanguageRange? {
let parts = entry.split(separator: .Separator.semicolon)
let tag = parts.first
.map(String.init)?
.trimmingCharacters(in: .whitespaces)
?? .empty
guard !tag.isEmpty else {
return nil
}
let quality = parts
.dropFirst()
.compactMap { parameter -> Double? in
let parameter = parameter
.trimmingCharacters(in: .whitespaces)
.lowercased()
guard parameter.hasPrefix(.Prefix.quality) else {
return nil
}
return Double(parameter.dropFirst(String.Prefix.quality.count))
}
.first
?? 1
return .init(
tag: tag,
quality: quality
)
}
/// Finds the supported language that best matches a single `Accept-Language` tag.
@@ -97,7 +146,7 @@ private extension Negotiate {
/// - supported: the supported language identifiers.
/// - Returns: the matching supported language, or `nil` when the tag matches none.
func match(
tag: String,
_ tag: String,
in supported: [String]
) -> String? {
let tag = tag.lowercased()
@@ -117,10 +166,32 @@ private extension Negotiate {
}
// MARK: - Character+Extensions
private extension Character {
// MARK: Constants
enum Separator {
static let comma: Character = ","
static let dash: Character = "-"
static let semicolon: Character = ";"
}
}
// MARK: - String+Extensions
private extension String {
// MARK: Constants
static let empty: String = ""
static let wildcard: String = "*"
enum Prefix {
static let quality = "q="
}
/// The primary language subtag, i.e. everything before the first `-` (`de-AT` becomes `de`).
var primarySubtag: String {
@@ -130,13 +201,3 @@ private extension String {
?? self
}
}
// MARK: - Constants
private extension Character {
enum Separator {
static let comma: Character = ","
static let dash: Character = "-"
static let semicolon: Character = ";"
}
}
Packages/Localization/Sources/Public/Types/LanguageList.swift
+21 -20
View File
@@ -8,46 +8,47 @@ public struct LanguageList: Sendable {
// MARK: Properties
/// The language served when none of the supported languages match a request.
///
/// Should match the catalog bundle's development localization.
public let `default`: String
/// The backend that reports the available languages.
private let resolver: any CatalogResolving
// MARK: Initializers
/// Creates a language list backed by the given bundle.
/// - Parameters:
/// - bundle: the bundle whose String Catalog defines the available languages.
/// - default: the language served when none of the supported languages match. Defaults to `"en"`.
/// - Parameter bundle: the bundle whose String Catalog defines the available languages.
public init(
bundle: Bundle,
`default`: String = "en"
bundle: Bundle
) {
self.init(
resolver: StringCatalog(bundle: bundle),
default: `default`
)
self.init(resolver: StringCatalog.cached(bundle: bundle))
}
/// Creates a language list backed by the given resolver.
///
/// The seam for tests and alternative backends; the public API derives languages from a bundled catalog.
/// - Parameters:
/// - resolver: the backend that reports the available languages.
/// - default: the language served when none of the supported languages match.
/// - Parameter resolver: the backend that reports the available languages.
init(
resolver: any CatalogResolving,
`default`: String = "en"
resolver: any CatalogResolving
) {
self.resolver = resolver
self.`default` = `default`
}
// MARK: Computed
/// The outcome of reading the bundle's String Catalog.
///
/// The list degrades to the default language rather than failing, so check this once at startup
/// and warn when it is not ``CatalogState/loaded``.
public var catalogState: CatalogState {
resolver.state
}
/// The language served when none of the supported languages match a request.
///
/// Always the catalog's source (development) language, so the default cannot drift from the
/// bundle the list is bound to.
public var `default`: String {
resolver.sourceLanguage
}
/// Every language the bundle's String Catalog provides a localization for.
///
/// The `Base` internationalization is excluded, as it is a development placeholder rather than a real language.