Merge pull request #57 from transifex/stelios/push-configuration

Introduce push configuration

CHANGELOG.md

@@ -86,3 +86,16 @@ based on user's preference and supported languages by the app developer.
 - Tags and status filters can be either specified during initialization and/or
 when `fetchTranslations()` is called.
 - Fixes issue where the passed custom session was not being used.
+
+## Transifex iOS SDK 2.0.0
+
+*July 7, 2023*
+
+- Adds `t()` translation method for cases where Transifex iOS logic cannot
+intercept the localization (e.g. SwiftUI).
+- `pushTranslations()` now reports back any generated warnings as a separate
+array.
+- Push logic detects and reports warnings such as duplicate source string keys
+or empty source string keys.
+- `pushTranslations()` now accepts a configuration object that holds any extra
+options that might need to be set during the push logic.

README.md

@@ -195,7 +195,7 @@ method.
 * `sourceString` (required): The actual source string.
 * `developerComment` (optional): An optional comment provided by the developer to
 assist the translators.
-* `occurrencies` (required): A list of relative paths where the source string is located in
+* `occurrences` (required): A list of relative paths where the source string is located in
 the project.
 * `tags` (optional): An optional list of tags that will appear alongside the source string in
 the Transifex dashboard.

Sources/Transifex/CDSHandler.swift

@@ -49,6 +49,76 @@ public enum TXCDSWarning: Error {
     case emptyKey(SourceString: String)
 }
 
+/// Class that holds the configuration of the `pushTranslations()` method that controls various aspect
+/// of the push to CDS.
+public final class TXPushConfiguration : NSObject {
+    /// Purge content
+    ///
+    /// If `purge`: true in meta object, then replace the entire resource content with the pushed content of
+    /// this request.
+    ///
+    /// If `purge`: false in meta object (the default), then append the source content of this request to the
+    /// existing resource content.
+    @objc
+    public let purge: Bool
+
+    /// Replace tags
+    ///
+    /// If `overrideTags`: true in meta object, then replace the existing string tags with the tags of this
+    /// request.
+    ///
+    /// If `overrideTags`: false in meta object (the default), then append tags from source content to
+    /// tags of existing strings instead of overwriting them.
+    @objc
+    public let overrideTags: Bool
+
+    /// Replace occurrences
+    ///
+    /// If `overrideOccurrences`: true in meta object, then replace the existing string occurrences with
+    /// the occurrences of this request.
+    ///
+    /// If `overrideOccurrences`: false in meta object (the default), then append occurrences from
+    /// source content to occurrences of existing strings instead of overwriting them.
+    @objc
+    public let overrideOccurrences: Bool
+
+    /// Keep translations
+    ///
+    /// If `keepTranslations`: true in meta object (the default), then preserve translations on source
+    /// content updates.
+    ///
+    /// If `keepTranslations`: false in meta object, then delete translations on source string content
+    /// updates.
+    @objc
+    public let keepTranslations: Bool
+
+    /// Dry run
+    ///
+    /// If `dryRun`: true in meta object, then emulate a content push, without doing actual changes.
+    @objc
+    public let dryRun: Bool
+
+    @objc
+    public init(purge: Bool = false,
+                overrideTags: Bool = false,
+                overrideOccurrences: Bool = false,
+                keepTranslations: Bool = true,
+                dryRun: Bool = false) {
+        self.purge = purge
+        self.overrideTags = overrideTags
+        self.overrideOccurrences = overrideOccurrences
+        self.keepTranslations = keepTranslations
+        self.dryRun = dryRun
+    }
+
+    /// Description of the configuration used for debugging purposes
+    public override var debugDescription: String {
+        """
+TXPushConfiguration(purge: \(purge), overrideTags: \(overrideTags), overrideOccurrences: \(overrideOccurrences), keepTranslations: \(keepTranslations), dryRun: \(dryRun))
+"""
+    }
+}
+
 /// Handles the logic of a pull HTTP request to CDS for a certain locale code
 class CDSPullRequest {
     let code : String
@@ -175,6 +245,26 @@ class CDSHandler {
         var data: [String:SourceString]
         struct Meta: Encodable {
             var purge: Bool
+            var overrideTags: Bool
+            var overrideOccurrences: Bool
+            var keepTranslations: Bool
+            var dryRun: Bool
+
+            enum CodingKeys: String, CodingKey {
+                case purge
+                case overrideTags = "override_tags"
+                case overrideOccurrences = "override_occurrences"
+                case keepTranslations = "keep_translations"
+                case dryRun = "dry_run"
+            }
+
+            init(from configuration: TXPushConfiguration) {
+                purge = configuration.purge
+                overrideTags = configuration.overrideTags
+                overrideOccurrences = configuration.overrideOccurrences
+                keepTranslations = configuration.keepTranslations
+                dryRun = configuration.dryRun
+            }
         }
         var meta: Meta
     }
@@ -407,14 +497,17 @@ class CDSHandler {
     ///
     /// - Parameters:
     ///   - translations: A list of `TXSourceString` objects
-    ///   - purge: Whether the request will replace the entire resource content (true) or not (false)
-    ///   Defaults to false
-    ///   - completionHandler: a callback function to call when the operation is complete
+    ///   - configuration: A configuration object containing all the options that will be used alongside
+    ///   the push operation (see `TXPushConfiguration`).
+    ///   - completionHandler: A callback to be called when the push operation is complete with a
+    /// boolean argument that informs the caller that the operation was successful (true) or not (false) and
+    /// an array that may or may not contain any errors produced during the push operation and an array of
+    /// non-blocking errors (warnings) that may have been generated during the push procedure.
     public func pushTranslations(_ translations: [TXSourceString],
-                                 purge: Bool = false,
+                                 configuration: TXPushConfiguration = TXPushConfiguration(),
                                  completionHandler: @escaping (Bool, [TXCDSError], [TXCDSWarning]) -> Void) {
         let serializedResult = Self.serializeTranslations(translations,
-                                                          purge: purge)
+                                                          configuration: configuration)
         switch serializedResult.0 {
         case .success(let jsonData):
             guard jsonData.count > 0 else {
@@ -636,11 +729,12 @@ failed: \(details.failed)
     /// Serialize the given translation units to the final data that should be passed in the push CDS request.
     ///
     /// - Parameter translations: a list of `TXSourceString` objects
-    /// - Parameter purge: Whether the resulting data will replace the entire resource content or not
+    /// - Parameter configuration: A configuration object containing all the options that will be used alongside
+    ///   the push operation (see `TXPushConfiguration`).
     /// - Returns: A tuple containing the Result object that either contains the Data object ready to be
     /// used in the CDS request or an error and the list of warnings generated during processing.
     private static func serializeTranslations(_ translations: [TXSourceString],
-                                              purge: Bool = false) -> (Result<Data, Error>, [TXCDSWarning]) {
+                                              configuration: TXPushConfiguration = TXPushConfiguration()) -> (Result<Data, Error>, [TXCDSWarning]) {
         var sourceStrings: [String:SourceString] = [:]
         var warnings: [TXCDSWarning] = []
 
@@ -658,7 +752,7 @@ failed: \(details.failed)
         }
 
         let data = PushData(data: sourceStrings,
-                            meta: PushData.Meta(purge: purge))
+                            meta: PushData.Meta(from: configuration))
 
         return (Result { try JSONEncoder().encode(data) }, warnings)
     }

Sources/Transifex/Core.swift

@@ -178,16 +178,17 @@ class NativeCore : TranslationProvider {
     ///
     /// - Parameters:
     ///   - translations: A list of `TXSourceString` objects.
-    ///   - purge: Whether to replace the entire resource  content (true) or not (false). Defaults to false.
+    ///   - configuration: A configuration object containing all the options that will be used alongside
+    ///   the push operation (see `TXPushConfiguration`).
     ///   - completionHandler: A callback to be called when the push operation is complete with a
     /// boolean argument that informs the caller that the operation was successful (true) or not (false) and
     /// an array that may or may not contain any errors produced during the push operation and an array of
     /// non-blocking errors (warnings) that may have been generated during the push procedure.
     func pushTranslations(_ translations: [TXSourceString],
-                          purge: Bool = false,
+                          configuration: TXPushConfiguration = TXPushConfiguration(),
                           completionHandler: @escaping (Bool, [Error], [Error]) -> Void) {
         cdsHandler.pushTranslations(translations,
-                                    purge: purge,
+                                    configuration: configuration,
                                     completionHandler: completionHandler)
     }
 
@@ -352,7 +353,7 @@ render '\(stringToRender)' locale code: \(localeCode) params: \(params). Error:
 /// A static class that is the main point of entry for all the functionality of Transifex Native throughout the SDK.
 public final class TXNative : NSObject {
     /// The SDK version
-    internal static let version = "1.0.4"
+    internal static let version = "2.0.0"
 
     /// The filename of the file that holds the translated strings and it's bundled inside the app.
     public static let STRINGS_FILENAME = "txstrings.json"
@@ -553,17 +554,18 @@ token: \(token)
     ///
     /// - Parameters:
     ///   - translations: A list of `TXSourceString` objects.
-    ///   - purge: Whether to replace the entire resource content (true) or not (false). Defaults to false.
+    ///   - configuration: A configuration object containing all the options that will be used alongside
+    ///   the push operation (see `TXPushConfiguration`).
     ///   - completionHandler: A callback to be called when the push operation is complete with a
     /// boolean argument that informs the caller that the operation was successful (true) or not (false) and
     /// an array that may or may not contain any errors produced during the push operation and an array of
     /// non-blocking errors (warnings) that may have been generated during the push procedure.
     @objc
     public static func pushTranslations(_ translations: [TXSourceString],
-                                        purge: Bool = false,
+                                        configuration: TXPushConfiguration = TXPushConfiguration(),
                                         completionHandler: @escaping (Bool, [Error], [Error]) -> Void) {
         tx?.pushTranslations(translations,
-                             purge: purge,
+                             configuration: configuration,
                              completionHandler: completionHandler)
     }