Add the ability to customize localization (#6096)

Add the ability to customize localization

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Other changes
 
 * Fixed unwanted road movement simulation when using static GPX files to simulate location.
+* Added `LocalizationManager` to support the ability to provide custom localization for specific strings in the SDK when `LocalizationManager.customLocalizationBundle` is set.
 
 ## v3.3.0-beta.1
 

Package.swift

@@ -74,6 +74,7 @@ let package = Package(
             ],
             resources: [
                 .copy("Fixtures"),
+                .process("Resources"),
             ]
         ),
         .target(

Sources/MapboxNavigationCore/Localization/LocalizationManager.swift

@@ -0,0 +1,48 @@
+import _MapboxNavigationHelpers
+import Foundation
+
+// swiftformat:disable enumNamespaces
+/// This class handles the localization of the string inside of the SDK.
+public struct LocalizationManager {
+    /// Set this bundle if you want to provide a custom localization for some string in the SDK. If the provided bundle
+    /// does not contain the localized version, the string from the default bundle inside the SDK will be used.
+    public static var customLocalizationBundle: Bundle? {
+        get { _customLocalizationBundle.read() }
+        set { _customLocalizationBundle.update(newValue) }
+    }
+
+    private static let _customLocalizationBundle: NSLocked<Bundle?> = .init(nil)
+    private static let nonExistentKeyValue = "_nonexistent_key_value_"
+
+    /// Retrieves the localized string for a given key.
+    /// - Parameters:
+    ///   - key: The key for the string to localize.
+    ///   - tableName: The name of the table containing the localized string  identified by `key`.
+    ///   - defaultBundle: The default bundle containing the table's strings file.
+    ///   - value: The value to use if the key is not found (optional).
+    ///   - comment: A note to the translator describing the context where the localized string is presented to the
+    /// user.
+    /// - Returns: A localized string.
+    public static func localizedString(
+        _ key: String,
+        tableName: String? = nil,
+        defaultBundle: Bundle,
+        value: String,
+        comment: String = ""
+    ) -> String {
+        if let customBundle = customLocalizationBundle {
+            let customString = NSLocalizedString(
+                key,
+                tableName: tableName,
+                bundle: customBundle,
+                value: nonExistentKeyValue,
+                comment: comment
+            )
+            if customString != nonExistentKeyValue {
+                return customString
+            }
+        }
+
+        return NSLocalizedString(key, tableName: tableName, bundle: defaultBundle, value: value, comment: comment)
+    }
+}

Sources/MapboxNavigationCore/Localization/String+Localization.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+extension String {
+    func localizedString(
+        value: String,
+        tableName: String? = nil,
+        defaultBundle: Bundle = .mapboxNavigationUXCore,
+        comment: String = ""
+    ) -> String {
+        LocalizationManager.localizedString(
+            self,
+            tableName: tableName,
+            defaultBundle: defaultBundle,
+            value: value,
+            comment: comment
+        )
+    }
+}

Sources/MapboxNavigationCore/Map/Style/RouteAnnotationMapFeatures.swift

@@ -321,9 +321,7 @@ extension NavigationRoutes {
                 signed: true
             )
         } else {
-            NSLocalizedString(
-                "SAME_TIME",
-                bundle: .mapboxNavigationUXCore,
+            "SAME_TIME".localizedString(
                 value: "Similar ETA",
                 comment: "Alternatives selection note about equal travel time."
             )

Sources/MapboxNavigationUIKit/BannerDismissalViewController.swift

@@ -1,3 +1,4 @@
+import MapboxNavigationCore
 import UIKit
 
 /// Banner that is shown at the top of the screen and allows to dismiss already presented banners
@@ -73,9 +74,7 @@ public class BannerDismissalViewController: UIViewController, Banner {
         let backButton = BackButton(type: .system)
         backButton.translatesAutoresizingMaskIntoConstraints = false
 
-        let backButtonTitle = NSLocalizedString(
-            "BACK",
-            bundle: .mapboxNavigation,
+        let backButtonTitle = "BACK".localizedString(
             value: "Back",
             comment: "Title of the back button."
         )

Sources/MapboxNavigationUIKit/BottomBannerViewController.swift

@@ -205,9 +205,7 @@ open class BottomBannerViewController: UIViewController, NavigationComponent {
 
         if let hardcodedTime = dateComponentsFormatter.string(from: 61), routeProgress.durationRemaining < 60 {
             timeRemainingLabel.text = String.localizedStringWithFormat(
-                NSLocalizedString(
-                    "LESS_THAN",
-                    bundle: .mapboxNavigation,
+                "LESS_THAN".localizedString(
                     value: "<%@",
                     comment: "Format string for a short distance or time less than a minimum threshold; 1 = duration remaining"
                 ),

Sources/MapboxNavigationUIKit/CarPlay/CarPlayManager.swift

@@ -188,12 +188,7 @@ public class CarPlayManager: NSObject {
 
     /// The bar button that exits the navigation session.
     public lazy var exitButton: CPBarButton = {
-        let title = NSLocalizedString(
-            "CARPLAY_END",
-            bundle: .mapboxNavigation,
-            value: "End",
-            comment: "Title for end navigation button"
-        )
+        let title = "CARPLAY_END".localizedString(value: "End", comment: "Title for end navigation button")
 
         let exitButton = CPBarButton(title: title) { [weak self] (_: CPBarButton) in
             self?.carPlayNavigationViewController?.exitNavigation(byCanceling: true)
@@ -205,19 +200,8 @@ public class CarPlayManager: NSObject {
     /// The bar button that mutes the voice turn-by-turn instruction announcements during navigation.
     @MainActor
     public lazy var muteButton: CPBarButton = {
-        let muteTitle = NSLocalizedString(
-            "CARPLAY_MUTE",
-            bundle: .mapboxNavigation,
-            value: "Mute",
-            comment: "Title for mute button"
-        )
-
-        let unmuteTitle = NSLocalizedString(
-            "CARPLAY_UNMUTE",
-            bundle: .mapboxNavigation,
-            value: "Unmute",
-            comment: "Title for unmute button"
-        )
+        let muteTitle = "CARPLAY_MUTE".localizedString(value: "Mute", comment: "Title for mute button")
+        let unmuteTitle = "CARPLAY_UNMUTE".localizedString(value: "Unmute", comment: "Title for unmute button")
 
         let title = isVoiceMuted ? unmuteTitle : muteTitle
         let muteButton = CPBarButton(title: title) { [weak self] (button: CPBarButton) in
@@ -238,9 +222,7 @@ public class CarPlayManager: NSObject {
 
     /// The bar button that brings alternative routes selection during navigation.
     public lazy var alternativeRoutesButton: CPBarButton = {
-        let title = NSLocalizedString(
-            "CARPLAY_ALTERNATIVES",
-            bundle: .mapboxNavigation,
+        let title = "CARPLAY_ALTERNATIVES".localizedString(
             value: "Alternatives",
             comment: "Title for alternatives selection list button"
         )
@@ -536,9 +518,7 @@ extension CarPlayManager {
                 return
             }
 
-            let name = NSLocalizedString(
-                "CARPLAY_CURRENT_LOCATION",
-                bundle: .mapboxNavigation,
+            let name = "CARPLAY_CURRENT_LOCATION".localizedString(
                 value: "Current Location",
                 comment: "Name of the waypoint associated with the current location"
             )
@@ -682,23 +662,17 @@ extension CarPlayManager {
     }
 
     private func defaultTripPreviewTextConfiguration() -> CPTripPreviewTextConfiguration {
-        let goTitle = NSLocalizedString(
-            "CARPLAY_GO",
-            bundle: .mapboxNavigation,
+        let goTitle = "CARPLAY_GO".localizedString(
             value: "Go",
             comment: "Title for start button in CPTripPreviewTextConfiguration"
         )
 
-        let alternativeRoutesTitle = NSLocalizedString(
-            "CARPLAY_MORE_ROUTES",
-            bundle: .mapboxNavigation,
+        let alternativeRoutesTitle = "CARPLAY_MORE_ROUTES".localizedString(
             value: "More Routes",
             comment: "Title for alternative routes in CPTripPreviewTextConfiguration"
         )
 
-        let overviewTitle = NSLocalizedString(
-            "CARPLAY_OVERVIEW",
-            bundle: .mapboxNavigation,
+        let overviewTitle = "CARPLAY_OVERVIEW".localizedString(
             value: "Overview",
             comment: "Title for overview button in CPTripPreviewTextConfiguration"
         )
@@ -712,9 +686,7 @@ extension CarPlayManager {
     }
 
     private func defaultTripPreviewBackButton() -> CPBarButton {
-        let title = NSLocalizedString(
-            "CARPLAY_PREVIEW_BACK",
-            bundle: .mapboxNavigation,
+        let title = "CARPLAY_PREVIEW_BACK".localizedString(
             value: "Back",
             comment: "Title for trip preview back button"
         )