Tweaks and fixes throughout the project (#27)
This PR contains the work done to do a little bit of housekeeping pass across all packages and the Website service. To provide further details about the work: * Refreshed the READMEs and source documentation to match the current code; * Tagged every test case consistently across the Infrastructure, Localization, Persistence, and Website test targets; * Removed Website middleware tests now covered by Infrastructure's own suite; * Conformed the `PrepareDB` method to Sendable; * Relaxes the production Compose DATABASE_TLS default from require to prefer; * Added Persistence test verifying the prefer posture falls back to plaintext connections. Reviewed-on: rock-n-code/loud-amsterdam#27 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:
@@ -0,0 +1,44 @@
|
||||
# Localization
|
||||
The server-side localization toolkit the **Loud** services build on: locale-explicit String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list — with no dependencies beyond Foundation.
|
||||
|
||||
## Overview
|
||||
The package provides, grouped by role:
|
||||
| Role | Types |
|
||||
| --- | --- |
|
||||
| Lookup | `Localize`, a bundle-bound localizer that resolves a catalog key for an explicit locale |
|
||||
| Negotiation | `Negotiate`, which picks the best supported language from an `Accept-Language` header per RFC 9110 |
|
||||
| Languages | `LanguageList`, the supported and default languages a bundle's String Catalog defines |
|
||||
| Diagnostics | `CatalogState`, the outcome of reading the catalog (`loaded`, `missing`, or `undecodable`) |
|
||||
|
||||
## Design rules
|
||||
- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`. Adding a language is a translation-only change — once a locale exists in the catalog, `LanguageList` and `Negotiate` pick it up with no code change.
|
||||
- **The locale is always explicit.** A server has no single "current" locale, so every lookup names the locale to resolve in; nothing reads process-wide locale state.
|
||||
- **Raw `.xcstrings` parsing, for Linux parity.** The catalog is decoded from its JSON rather than through Foundation's compiled-catalog APIs, which are unavailable or non-functional on Linux. Consumers must `.copy` the catalog resource verbatim (not `.process` it) so it ships as raw JSON on every platform. Only simple `stringUnit` values are decoded; plural and device variations are not represented.
|
||||
- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` once at startup and warn when it is not `.loaded`, before visitors ever see raw keys.
|
||||
- **Method structs.** `Localize` and `Negotiate` hold their lifetime-fixed configuration (the bundle) in `init` and take only per-call inputs in `callAsFunction`.
|
||||
- **One decoded catalog per bundle.** Catalogs are immutable at runtime, so every `Localize`, `Negotiate`, and `LanguageList` bound to the same bundle and table shares one cached `StringCatalog`.
|
||||
|
||||
## Layout
|
||||
Sources are split by visibility, then by kind, one type per file:
|
||||
```
|
||||
Sources/
|
||||
├── Public/
|
||||
│ ├── Enumerations/ CatalogState
|
||||
│ ├── Methods/ Localize, Negotiate
|
||||
│ └── Types/ LanguageList
|
||||
└── Internal/
|
||||
├── Protocols/ CatalogResolving, the seam between the public API and the catalog backend
|
||||
└── Types/ StringCatalog (the cached .xcstrings decoder), LanguageRange
|
||||
Tests/
|
||||
├── Cases/ the test suites, mirroring the Sources/ layout
|
||||
├── Catalogs/ the String Catalog fixture, copied verbatim so it loads on Linux
|
||||
└── Utils/ the StubCatalog resolver and the suite Tag constants
|
||||
```
|
||||
|
||||
## Testing
|
||||
Every suite carries a tag naming the kind of API it exercises — `.method` or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
|
||||
|
||||
## Requirements
|
||||
- Swift 6.3 toolchain (`swift-tools-version:6.3`).
|
||||
- macOS 15, matching the sibling `Infrastructure` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
|
||||
- No package dependencies — Foundation and Synchronization only.
|
||||
@@ -2,22 +2,19 @@ import Foundation
|
||||
|
||||
/// A backend that resolves localized strings for an explicit locale and reports the languages it serves.
|
||||
///
|
||||
/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored
|
||||
/// and resolved. The shipping implementation, ``StringCatalog``, reads a raw `.xcstrings` catalog so it
|
||||
/// behaves identically on Darwin and Linux. A future backend — for example one built on
|
||||
/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform
|
||||
/// without changing any caller.
|
||||
/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored and resolved. The shipping implementation,
|
||||
/// ``StringCatalog``, reads a raw `.xcstrings` catalog so it behaves identically on Darwin and Linux. A future backend — for example one built on
|
||||
/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform without changing any caller.
|
||||
///
|
||||
/// Resolution never fails: an implementation returns the key itself when it has no localization for it,
|
||||
/// mirroring Foundation's `String(localized:)`. This is the contract both a dictionary lookup and the
|
||||
/// native API can honour, since the native API cannot distinguish a missing key from a translation that
|
||||
/// Resolution never fails: an implementation returns the key itself when it has no localization for it, mirroring Foundation's `String(localized:)`.
|
||||
/// This is the contract both a dictionary lookup and the native API can honour, since the native API cannot distinguish a missing key from a translation that
|
||||
/// happens to equal the key.
|
||||
protocol CatalogResolving: Sendable {
|
||||
|
||||
// MARK: Properties
|
||||
|
||||
/// The source (development) language, used as the final fallback when a locale has no localization
|
||||
/// and as the default language a ``LanguageList`` serves.
|
||||
/// 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.
|
||||
|
||||
@@ -1,8 +1,7 @@
|
||||
/// 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
|
||||
/// 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 {
|
||||
|
||||
@@ -11,8 +10,7 @@ struct LanguageRange {
|
||||
/// 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).
|
||||
/// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when an entry names no weight).
|
||||
let quality: Double
|
||||
|
||||
}
|
||||
|
||||
@@ -95,8 +95,8 @@ extension 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.
|
||||
/// 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.
|
||||
@@ -132,9 +132,8 @@ extension StringCatalog {
|
||||
|
||||
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.
|
||||
/// 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
|
||||
@@ -162,8 +161,8 @@ 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.
|
||||
/// 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
|
||||
|
||||
@@ -1,17 +1,12 @@
|
||||
/// 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.
|
||||
/// 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
|
||||
|
||||
}
|
||||
|
||||
@@ -2,9 +2,8 @@ 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.
|
||||
/// 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
|
||||
@@ -16,8 +15,7 @@ public struct Localize: Sendable {
|
||||
|
||||
/// 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``.
|
||||
/// 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
|
||||
}
|
||||
@@ -56,8 +54,8 @@ public struct Localize: Sendable {
|
||||
/// - 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.
|
||||
/// - 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
|
||||
|
||||
@@ -2,10 +2,9 @@ import Foundation
|
||||
|
||||
/// Negotiates the best supported language for a request from its `Accept-Language` header.
|
||||
///
|
||||
/// 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, honouring the header's `q` weights as RFC 9110 prescribes and
|
||||
/// falling back to the default language.
|
||||
/// 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, honouring the header's `q` weights as
|
||||
/// RFC 9110 prescribes and falling back to the default language.
|
||||
public struct Negotiate: Sendable {
|
||||
|
||||
// MARK: Properties
|
||||
@@ -28,12 +27,10 @@ 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 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.
|
||||
/// 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(
|
||||
@@ -74,9 +71,8 @@ private extension Negotiate {
|
||||
|
||||
/// Parses an `Accept-Language` header value into its ``LanguageRange`` list, ordered by preference.
|
||||
///
|
||||
/// 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.
|
||||
/// 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 language ranges, most preferred first.
|
||||
func ranges(
|
||||
@@ -98,8 +94,7 @@ private extension Negotiate {
|
||||
/// 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.
|
||||
/// 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(
|
||||
@@ -139,8 +134,8 @@ private extension Negotiate {
|
||||
|
||||
/// Finds the supported language that best matches a single `Accept-Language` tag.
|
||||
///
|
||||
/// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the
|
||||
/// supported languages' primary subtags, so a regional tag such as `de-AT` resolves to `de`.
|
||||
/// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the supported languages' primary subtags, so a
|
||||
/// regional tag such as `de-AT` resolves to `de`.
|
||||
/// - Parameters:
|
||||
/// - tag: a single language tag from the header.
|
||||
/// - supported: the supported language identifiers.
|
||||
|
||||
@@ -35,16 +35,14 @@ public struct LanguageList: Sendable {
|
||||
|
||||
/// 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``.
|
||||
/// 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.
|
||||
/// 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
|
||||
}
|
||||
|
||||
@@ -3,7 +3,10 @@ import Testing
|
||||
|
||||
@testable import Localization
|
||||
|
||||
@Suite("Localize method")
|
||||
@Suite(
|
||||
"Localize method",
|
||||
.tags(.method)
|
||||
)
|
||||
struct LocalizeTests {
|
||||
|
||||
// MARK: Constants
|
||||
|
||||
@@ -3,7 +3,10 @@ import Testing
|
||||
|
||||
@testable import Localization
|
||||
|
||||
@Suite("Negotiate method")
|
||||
@Suite(
|
||||
"Negotiate method",
|
||||
.tags(.method)
|
||||
)
|
||||
struct NegotiateTests {
|
||||
|
||||
// MARK: Constants
|
||||
|
||||
@@ -3,7 +3,10 @@ import Testing
|
||||
|
||||
@testable import Localization
|
||||
|
||||
@Suite("LanguageList type")
|
||||
@Suite(
|
||||
"LanguageList type",
|
||||
.tags(.type)
|
||||
)
|
||||
struct LanguageListTests {
|
||||
|
||||
// MARK: Properties tests
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
import Testing
|
||||
|
||||
extension Tag {
|
||||
/// Tests exercising a method of the Localization package.
|
||||
@Tag static var method: Tag
|
||||
/// Tests exercising a type of the Localization package.
|
||||
@Tag static var type: Tag
|
||||
}
|
||||
Reference in New Issue
Block a user