Add UI localization layer and actor-based core

Author: MikeChen1109

CHANGELOG.md

@@ -6,10 +6,21 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-13
+
+### Added
+- Added the new `LiveLocalizationUI` product for UI-level localization wrappers.
+- Added `LiveLocalizedText` for SwiftUI.
+- Added `LiveLocalizedLabel` for UIKit.
+- Added `LiveLocalizationTextAnimation` with `.none` and `.fade` styles.
+- Added UI-layer request coordination tests and demo coverage for the new wrappers.
+
 ### Changed
-- Renamed the package surface from `DebugLocalization` to `LiveLocalizationKit`.
-- Renamed primary modules to `LiveLocalizationCore` and `LiveLocalizationTranslationSupport`.
-- Renamed the shared runtime API to `LiveLocalization`, `LiveLocalizer`, `LiveLocalizationError`, and `LiveLocalizationVersion`.
+- Moved shared localization state to actor-based concurrency instead of relying on `@unchecked Sendable`.
+- Updated `LiveLocalization` shared configuration flow to async usage.
+- Updated the demo app to show both direct core API usage and the new UI wrapper usage in SwiftUI and UIKit.
+- Updated README examples to reflect the current package naming, install path, and UI-layer APIs.
+- Continued the package rename from the previous `DebugLocalization*` surface to the `LiveLocalization*` naming now used across the repository.
 
 ## [0.3.0] - 2026-03-11
 

LiveLocalizationDemo.xcodeproj/project.pbxproj

@@ -9,6 +9,7 @@
 /* Begin PBXBuildFile section */
 		94B75D632F609AAB0000BA49 /* LiveLocalizationCore in Frameworks */ = {isa = PBXBuildFile; productRef = 94B75D622F609AAB0000BA49 /* LiveLocalizationCore */; };
 		94B75D652F609AAB0000BA49 /* LiveLocalizationTranslationSupport in Frameworks */ = {isa = PBXBuildFile; productRef = 94B75D642F609AAB0000BA49 /* LiveLocalizationTranslationSupport */; };
+		94CDC0012F7000010000BA49 /* LiveLocalizationUI in Frameworks */ = {isa = PBXBuildFile; productRef = 94CDC0002F7000010000BA49 /* LiveLocalizationUI */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXContainerItemProxy section */
@@ -58,6 +59,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				94B75D632F609AAB0000BA49 /* LiveLocalizationCore in Frameworks */,
+				94CDC0012F7000010000BA49 /* LiveLocalizationUI in Frameworks */,
 				94B75D652F609AAB0000BA49 /* LiveLocalizationTranslationSupport in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -120,6 +122,7 @@
 			name = LiveLocalizationKit;
 			packageProductDependencies = (
 				94B75D622F609AAB0000BA49 /* LiveLocalizationCore */,
+				94CDC0002F7000010000BA49 /* LiveLocalizationUI */,
 				94B75D642F609AAB0000BA49 /* LiveLocalizationTranslationSupport */,
 			);
 			productName = LiveLocalizationKit;
@@ -607,6 +610,10 @@
 			isa = XCSwiftPackageProductDependency;
 			productName = LiveLocalizationTranslationSupport;
 		};
+		94CDC0002F7000010000BA49 /* LiveLocalizationUI */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = LiveLocalizationUI;
+		};
 /* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = 946450652F5F665E00F1661D /* Project object */;

LiveLocalizationDemo.xcodeproj/xcshareddata/xcschemes/LiveLocalizationKit.xcscheme

@@ -34,7 +34,7 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      language = "zh-Hant"
+      language = "ko"
       launchStyle = "0"
       useCustomWorkingDirectory = "NO"
       ignoresPersistentStateOnLaunch = "NO"

LiveLocalizationKit/ContentView.swift

@@ -1,27 +1,46 @@
 import SwiftUI
 import LiveLocalizationCore
+import LiveLocalizationUI
 
 struct ContentView: View {
     private let englishSourceText = "Payment successful"
+    private let wrapperSourceText = "Continue"
 
-    @State private var displayedText: String
-
-    init() {
-        _displayedText = State(initialValue: englishSourceText)
-    }
+    @State private var coreLocalizedText = "Payment successful"
 
     var body: some View {
-        VStack(spacing: 16) {
+        VStack(spacing: 24) {
             Text("SwiftUI Demo")
                 .font(.headline)
-            Text(displayedText)
+
+            VStack(spacing: 8) {
+                Text("Core API")
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+
+                Text(coreLocalizedText)
+                    .font(.title2)
+                    .multilineTextAlignment(.center)
+                    .padding(.horizontal)
+            }
+
+            VStack(spacing: 8) {
+                Text("UI Wrapper")
+                    .font(.subheadline)
+                    .foregroundStyle(.secondary)
+
+                LiveLocalizedText(
+                    wrapperSourceText,
+                    animationStyle: .fade
+                )
                 .font(.title2)
                 .multilineTextAlignment(.center)
                 .padding(.horizontal)
+            }
         }
         .padding()
         .task {
-            displayedText = await englishSourceText.localize()
+            coreLocalizedText = await englishSourceText.localize()
         }
     }
 }

LiveLocalizationKit/LiveLocalizationKitApp.swift

@@ -5,15 +5,26 @@ import LiveLocalizationTranslationSupport
 @main
 struct LiveLocalizationKitApp: App {
     private let shouldPresentPreparationGate: Bool
+    @State private var isConfigured = false
 
     init() {
         shouldPresentPreparationGate = true
-        LiveLocalization.configure(provider: AppleTranslationProvider())
     }
 
     var body: some Scene {
         WindowGroup {
-            RootDemoView(shouldPresentPreparationGate: shouldPresentPreparationGate)
+            Group {
+                if isConfigured {
+                    RootDemoView(shouldPresentPreparationGate: shouldPresentPreparationGate)
+                } else {
+                    ProgressView()
+                }
+            }
+            .task {
+                guard !isConfigured else { return }
+                await LiveLocalization.configure(provider: AppleTranslationProvider())
+                isConfigured = true
+            }
         }
     }
 }

LiveLocalizationKit/UIKitDemoViewController.swift

@@ -1,10 +1,22 @@
 import UIKit
 import LiveLocalizationCore
+import LiveLocalizationUI
 
 final class UIKitDemoViewController: UIViewController {
-    private let englishSourceText = "Delete"
+    private let coreSourceText = "Delete"
+    private let wrapperSourceText = "Continue"
 
-    private let label: UILabel = {
+    private let coreTitleLabel: UILabel = {
+        let label = UILabel()
+        label.numberOfLines = 1
+        label.textAlignment = .center
+        label.font = .preferredFont(forTextStyle: .headline)
+        label.text = "Core API"
+        label.translatesAutoresizingMaskIntoConstraints = false
+        return label
+    }()
+
+    private let coreLabel: UILabel = {
         let label = UILabel()
         label.numberOfLines = 0
         label.textAlignment = .center
@@ -13,6 +25,26 @@ final class UIKitDemoViewController: UIViewController {
         return label
     }()
 
+    private let wrapperTitleLabel: UILabel = {
+        let label = UILabel()
+        label.numberOfLines = 1
+        label.textAlignment = .center
+        label.font = .preferredFont(forTextStyle: .headline)
+        label.text = "UI Wrapper"
+        label.translatesAutoresizingMaskIntoConstraints = false
+        return label
+    }()
+
+    private let wrapperLabel: LiveLocalizedLabel = {
+        let label = LiveLocalizedLabel()
+        label.numberOfLines = 0
+        label.textAlignment = .center
+        label.font = .preferredFont(forTextStyle: .title2)
+        label.animationStyle = .fade
+        label.translatesAutoresizingMaskIntoConstraints = false
+        return label
+    }()
+
     @available(*, unavailable)
     required init?(coder: NSCoder) {
         fatalError("init(coder:) has not been implemented")
@@ -26,21 +58,32 @@ final class UIKitDemoViewController: UIViewController {
     override func viewDidLoad() {
         super.viewDidLoad()
         view.backgroundColor = .systemBackground
-        view.addSubview(label)
+        let stackView = UIStackView(arrangedSubviews: [
+            coreTitleLabel,
+            coreLabel,
+            wrapperTitleLabel,
+            wrapperLabel
+        ])
+        stackView.axis = .vertical
+        stackView.spacing = 12
+        stackView.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(stackView)
 
         NSLayoutConstraint.activate([
-            label.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),
-            label.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),
-            label.centerYAnchor.constraint(equalTo: view.centerYAnchor)
+            stackView.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),
+            stackView.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),
+            stackView.centerYAnchor.constraint(equalTo: view.centerYAnchor)
         ])
 
-        label.text = englishSourceText
+        coreLabel.text = coreSourceText
         Task { [weak self] in
             guard let self else { return }
-            let localized = await englishSourceText.localize()
+            let localized = await coreSourceText.localize()
             await MainActor.run {
-                self.label.text = localized
+                self.coreLabel.text = localized
             }
         }
+
+        wrapperLabel.setLocalizedText(wrapperSourceText)
     }
 }

Package.swift

@@ -13,6 +13,10 @@ let package = Package(
             name: "LiveLocalizationCore",
             targets: ["LiveLocalizationCore"]
         ),
+        .library(
+            name: "LiveLocalizationUI",
+            targets: ["LiveLocalizationUI"]
+        ),
         .library(
             name: "LiveLocalizationTranslationSupport",
             targets: ["LiveLocalizationTranslationSupport"]
@@ -22,6 +26,10 @@ let package = Package(
         .target(
             name: "LiveLocalizationCore"
         ),
+        .target(
+            name: "LiveLocalizationUI",
+            dependencies: ["LiveLocalizationCore"]
+        ),
         .target(
             name: "LiveLocalizationTranslationSupport",
             dependencies: ["LiveLocalizationCore"]
@@ -30,6 +38,7 @@ let package = Package(
             name: "LiveLocalizationCoreTests",
             dependencies: [
                 "LiveLocalizationCore",
+                "LiveLocalizationUI",
                 "LiveLocalizationTranslationSupport"
             ]
         )

README.md

@@ -22,6 +22,7 @@ https://github.com/MikeChen1109/LiveLocalizationKit.git
 Available products:
 
 - `LiveLocalizationCore`
+- `LiveLocalizationUI`
 - `LiveLocalizationTranslationSupport`
 
 ## Quick Start
@@ -32,12 +33,35 @@ Configure Apple Translation-based preview:
 import LiveLocalizationCore
 import LiveLocalizationTranslationSupport
 
-LiveLocalization.configure(provider: AppleTranslationProvider())
+await LiveLocalization.configure(provider: AppleTranslationProvider())
 let localized = await "Settings".localize()
 ```
 
 For lightweight development flows, `LiveLocalizationCore` also includes providers such as `PseudoLocalizationProvider`, `MockLocalizationProvider`, and `PassthroughLocalizationProvider`.
 
+## UI Layer
+
+`LiveLocalizationUI` adds simple view wrappers on top of the core localizer layer.
+
+SwiftUI:
+
+```swift
+import SwiftUI
+import LiveLocalizationUI
+
+LiveLocalizedText("Continue")
+```
+
+UIKit:
+
+```swift
+import UIKit
+import LiveLocalizationUI
+
+let label = LiveLocalizedLabel()
+label.setLocalizedText("Continue")
+```
+
 ## Apple Translation Preview
 
 If you want a debug flow that checks whether required language packs are available and guides preparation before showing the UI:

Sources/LiveLocalizationCore/LiveLocalization.swift

@@ -3,44 +3,45 @@ import Foundation
 public enum LiveLocalization {
     private static let sharedStore = SharedLocalizerStore()
 
-    public static func configure(provider: any LocalizationProvider) {
-        sharedStore.setLocalizer(LiveLocalizer(provider: provider))
+    public static func configure(provider: any LocalizationProvider) async {
+        await sharedStore.setLocalizer(LiveLocalizer(provider: provider))
     }
 
-    public static func configure(localizer: LiveLocalizer) {
-        sharedStore.setLocalizer(localizer)
+    public static func configure(localizer: LiveLocalizer) async {
+        await sharedStore.setLocalizer(localizer)
     }
 
     public static var localizer: LiveLocalizer {
-        sharedStore.localizer
+        get async {
+            await sharedStore.localizer
+        }
     }
 
     public static var canLocalizeSynchronously: Bool {
-        localizer.canLocalizeSynchronously
+        get async {
+            let localizer = await localizer
+            return await localizer.canLocalizeSynchronously
+        }
     }
 
-    public static func clearCache() {
-        localizer.clearCache()
+    public static func clearCache() async {
+        let localizer = await localizer
+        await localizer.clearCache()
     }
 
-    public static func reset() {
-        configure(provider: PseudoLocalizationProvider())
+    public static func reset() async {
+        await configure(provider: PseudoLocalizationProvider())
     }
 }
 
-private final class SharedLocalizerStore: @unchecked Sendable {
-    private let lock = NSLock()
+private actor SharedLocalizerStore {
     private var currentLocalizer = LiveLocalizer(provider: PseudoLocalizationProvider())
 
     var localizer: LiveLocalizer {
-        lock.lock()
-        defer { lock.unlock() }
         return currentLocalizer
     }
 
     func setLocalizer(_ localizer: LiveLocalizer) {
-        lock.lock()
         currentLocalizer = localizer
-        lock.unlock()
     }
 }