lokalise_manager 6.0.0 → 6.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0df6efdcebd1ef7b1f3992a14c997d56859553cf0e1b089d43fe496f479bb1e
-  data.tar.gz: 762127da9ea96e1b5ad532a5217d0f06556b3d9f61b65f722f79a50a406bba23
+  metadata.gz: b058f5acea2966c452c6ad194fbc4e82777c4624d58526f2fde8cc1b81ce0f16
+  data.tar.gz: 133c9fbd8e7d41ca827719e407ecf40612374c3ef5f39602994d4bbe9fa2ab15
 SHA512:
-  metadata.gz: 42c3990642e4598cc746f1f991d57bceb1793b0de6f8a9ff8b7a33d42194c47a9d84243ee045658a4925dda13d2b6ee63bb0464bd48c8094951b60c2b83e8c9b
-  data.tar.gz: 156793b3c527be7e88fa4790db675f98958ba80a2be717259f4e3fca937a1369b9660210d8778b727cce1249f9237873507c6800e88eec33d40aac3bf9b42c8a
+  metadata.gz: 0403ce7ce14ff83d4b2b3e0688350f666a29e6e8d50f4bb224a2c048247f74998569328859e911c2f833d5a7f9d7c1ccba736c94b5c6e2aaf1f4b70c2833c1ca
+  data.tar.gz: 6d4dc48b94da3882706c5c30f6600e899b427fce7e5a7c6ea9e192c9c62c2eadbe2d3228c73d8d49b3a3ed6023b6681dac54f2c58c6124aac147a6588267acf9

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 6.1.1 (20-Feb-2025)
+
+* Prevent error swallowing in rare cases
+
+## 6.1.0 (19-Feb-2025)
+
+* Added support for `import_async` option (default to `false`). When enabled, the [import process will happen in the background](https://developers.lokalise.com/reference/download-files-async) and the gem will use exponential backoff to wait for its completion according to the `max_retries_import` option.
+
 ## 6.0.0 (29-Nov-2024)
 
 * **Breaking change**: rename the `timeouts` config method to `additional_client_opts`. It has the same usage but now enables you to set both client timeouts and override the API host to send requests to.

data/README.md

@@ -146,6 +146,7 @@ importer = LokaliseManager.importer api_token: '1234abc',
 
 * `import_safe_mode` (`boolean`) — default to `false`. When this option is enabled, the import task will check whether the directory set with `locales_path` is empty or not. If it is not empty, you will be prompted to continue.
 * `max_retries_import` (`integer`) — this option is introduced to properly handle Lokalise API rate limiting. If the HTTP status code 429 (too many requests) has been received, this gem will apply an exponential backoff mechanism with a very simple formula: `2 ** retries`. If the maximum number of retries has been reached, a `RubyLokaliseApi::Error::TooManyRequests` exception will be raised and the operation will be halted.
+* `import_async` (`boolean`) — default to `false`. Runs the [import in the background](https://developers.lokalise.com/reference/download-files-async) on Lokalise. Uses exponential backoff to wait for completion, based on `max_retries_import`. Useful only for large projects.
 
 ### Export config
 

data/lib/lokalise_manager/global_config.rb

@@ -10,7 +10,7 @@ module LokaliseManager
                   :file_ext_regexp, :skip_file_export, :branch, :additional_client_opts,
                   :translations_loader, :translations_converter, :lang_iso_inferer,
                   :max_retries_export, :max_retries_import, :use_oauth2_token, :silent_mode,
-                  :raise_on_export_fail
+                  :raise_on_export_fail, :import_async
 
       # Yield self to block for configuration
       def config
@@ -84,6 +84,11 @@ module LokaliseManager
         @import_safe_mode.nil? ? false : @import_safe_mode
       end
 
+      # Return whether import should be performed asynchronously
+      def import_async
+        @import_async.nil? ? false : @import_async
+      end
+
       # Return whether to skip file export based on a lambda condition
       def skip_file_export
         @skip_file_export || ->(_) { false }

data/lib/lokalise_manager/task_definitions/base.rb

@@ -5,30 +5,43 @@ require 'pathname'
 
 module LokaliseManager
   module TaskDefinitions
-    # Base class for LokaliseManager task definitions, providing common methods and logic
-    # for importer and exporter classes. Handles API client interactions and configuration merging.
+    # Base class for LokaliseManager task definitions.
+    #
+    # Provides shared functionality for Importer and Exporter classes, including:
+    # - API client management.
+    # - Configuration merging.
+    # - File validation helpers.
+    # - Exponential backoff for retrying failed API requests.
     class Base
       using LokaliseManager::Utils::HashUtils
 
       attr_accessor :config
 
-      # Initializes a new task object by merging custom and global configurations.
+      # Defines exceptions that should trigger a retry with exponential backoff.
       #
-      # @param custom_opts [Hash] Custom configurations for specific tasks.
-      # @param global_config [Object] Reference to the global configuration.
+      # - `JSON::ParserError`: Occurs when the API responds with non-JSON content (e.g., HTML due to rate limits).
+      # - `RubyLokaliseApi::Error::TooManyRequests`: Raised when too many requests are sent in a short period.
+      EXCEPTIONS = [JSON::ParserError, RubyLokaliseApi::Error::TooManyRequests].freeze
+
+      # Initializes a new task object with merged global and custom configurations.
+      #
+      # @param custom_opts [Hash] Custom configuration options specific to the task.
+      # @param global_config [Object] The global configuration object.
       def initialize(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
         merged_opts = merge_configs(global_config, custom_opts)
         @config = build_config_class(merged_opts)
       end
 
-      # Retrieves or creates a Lokalise API client based on configuration.
+      # Retrieves or initializes the Lokalise API client based on the current configuration.
       #
-      # @return [RubyLokaliseApi::Client] Lokalise API client.
+      # @return [RubyLokaliseApi::Client] An instance of the Lokalise API client.
       def api_client
         @api_client ||= create_api_client
       end
 
-      # Resets API client
+      # Resets the API client, clearing cached instances.
+      #
+      # Useful when switching authentication tokens or handling connection issues.
       def reset_api_client!
         ::RubyLokaliseApi.reset_client!
         ::RubyLokaliseApi.reset_oauth2_client!
@@ -37,7 +50,9 @@ module LokaliseManager
 
       private
 
-      # Creates a Lokalise API client based on configuration.
+      # Creates a new Lokalise API client instance based on the configuration.
+      #
+      # @return [RubyLokaliseApi::Client] The initialized API client.
       def create_api_client
         client_opts = [config.api_token, config.additional_client_opts]
         client_method = config.use_oauth2_token ? :oauth2_client : :client
@@ -46,6 +61,13 @@ module LokaliseManager
       end
 
       # Merges global and custom configurations.
+      #
+      # - Extracts all global config values.
+      # - Merges them with custom options using a deep merge strategy.
+      #
+      # @param global_config [Object] The global configuration object.
+      # @param custom_opts [Hash] The custom configuration options.
+      # @return [Hash] The merged configuration.
       def merge_configs(global_config, custom_opts)
         primary_opts = global_config
                        .singleton_methods
@@ -58,13 +80,19 @@ module LokaliseManager
         primary_opts.deep_merge(custom_opts)
       end
 
-      # Builds a config class with the given options.
+      # Constructs a configuration object from a hash of options.
+      #
+      # Uses a struct to provide attribute-style access to settings.
+      #
+      # @param all_opts [Hash] The merged configuration options.
+      # @return [Struct] A configuration object.
       def build_config_class(all_opts)
-        config_klass = Struct.new(*all_opts.keys, keyword_init: true)
-        config_klass.new(all_opts)
+        Struct.new(*all_opts.keys, keyword_init: true).new(all_opts)
       end
 
-      # Checks and validates task options, raising errors if configurations are missing.
+      # Validates required configuration options.
+      #
+      # @raise [LokaliseManager::Error] If required configurations are missing.
       def check_options_errors!
         errors = []
         errors << 'Project ID is not set!' if config.project_id.nil? || config.project_id.empty?
@@ -72,36 +100,39 @@ module LokaliseManager
         raise LokaliseManager::Error, errors.join(' ') unless errors.empty?
       end
 
-      # Checks if the file has the correct extension based on the configuration.
+      # Checks if a file has a valid extension based on the configuration.
       #
-      # @param raw_path [String, Pathname] Path to check.
-      # @return [Boolean] True if the extension matches, false otherwise.
+      # @param raw_path [String, Pathname] The file path to check.
+      # @return [Boolean] `true` if the file has a valid extension, `false` otherwise.
       def proper_ext?(raw_path)
         path = raw_path.is_a?(Pathname) ? raw_path : Pathname.new(raw_path)
         config.file_ext_regexp.match? path.extname
       end
 
-      # Extracts the directory and filename from a given path.
+      # Extracts the subdirectory and filename from a given path.
       #
       # @param entry [String] The file path.
-      # @return [Array] Contains [Pathname, Pathname] representing the directory and filename.
+      # @return [Array<Pathname, Pathname>] An array containing the subdirectory and filename.
       def subdir_and_filename_for(entry)
         Pathname.new(entry).split
       end
 
-      # Constructs a project identifier string that may include a branch.
+      # Constructs a Lokalise project identifier that may include a branch.
       #
-      # @return [String] Project identifier potentially including the branch.
+      # If a branch is specified, the project ID is formatted as `project_id:branch`.
+      #
+      # @return [String] The formatted project identifier.
       def project_id_with_branch
         config.branch.to_s.strip.empty? ? config.project_id.to_s : "#{config.project_id}:#{config.branch}"
       end
 
-      # In rare cases the server might return HTML instead of JSON.
-      # It happens when too many requests are being sent.
-      # Until this is fixed, we revert to this quick'n'dirty solution.
-      EXCEPTIONS = [JSON::ParserError, RubyLokaliseApi::Error::TooManyRequests].freeze
-
-      # Handles retries with exponential backoff for specific exceptions.
+      # Executes a block with exponential backoff for handling API rate limits and temporary failures.
+      #
+      # Retries the operation for a defined number of attempts, doubling the wait time after each failure.
+      #
+      # @param max_retries [Integer] Maximum number of retries before giving up.
+      # @yield The operation to retry.
+      # @return [Object] The result of the block if successful.
       def with_exp_backoff(max_retries)
         return unless block_given?
 

data/lib/lokalise_manager/task_definitions/exporter.rb

@@ -4,14 +4,21 @@ require 'base64'
 
 module LokaliseManager
   module TaskDefinitions
-    # Class to handle exporting translation files from a local project to Lokalise.
+    # Handles exporting translation files from a local project to Lokalise.
     class Exporter < Base
       # Maximum number of concurrent uploads to avoid exceeding Lokalise API rate limits.
       MAX_THREADS = 6
 
-      # Exports translation files to Lokalise and handles any necessary concurrency and error checking.
+      ProcessResult = Struct.new(:success, :process, :path, :error, keyword_init: true)
+
+      # Exports translation files to Lokalise in batches to optimize performance.
+      #
+      # - Validates configuration.
+      # - Gathers translation files from the project directory.
+      # - Uploads files to Lokalise in parallel, respecting API rate limits.
+      # - Handles errors and ensures failed uploads are reported.
       #
-      # @return [Array] An array of process statuses for each file uploaded.
+      # @return [Array] An array of process results for each uploaded file.
       def export!
         check_options_errors!
 
@@ -28,10 +35,10 @@ module LokaliseManager
 
       private
 
-      # Handles parallel uploads of a group of files, utilizing threading.
+      # Uploads a group of files in parallel using threads.
       #
-      # @param files_group [Array] Group of files to be uploaded.
-      # @return [Array] Array of threads handling the file uploads.
+      # @param files_group [Array] List of file path pairs (full and relative).
+      # @return [Array] Array of results from the upload process.
       def parallel_upload(files_group)
         files_group.map do |file_data|
           Thread.new { do_upload(*file_data) }
@@ -44,34 +51,34 @@ module LokaliseManager
       def raise_on_fail(thread)
         return if thread.success
 
-        raise thread.error.class, "Error while trying to upload #{thread.path}: #{thread.error.message}"
+        raise thread.error
       end
 
-      # Performs the actual upload of a file to Lokalise.
+      # Uploads a single file to Lokalise.
+      #
+      # Uses exponential backoff to retry failed uploads.
       #
-      # @param f_path [Pathname] Full path to the file.
-      # @param r_path [Pathname] Relative path of the file within the project.
-      # @return [Struct] A struct with the success status, process details, and any error information.
+      # @param f_path [Pathname] Full file path.
+      # @param r_path [Pathname] Relative file path within the project.
+      # @return [Struct] Struct containing upload status, process details, and error (if any).
       def do_upload(f_path, r_path)
-        proc_klass = Struct.new(:success, :process, :path, :error, keyword_init: true)
-
         process = with_exp_backoff(config.max_retries_export) do
           api_client.upload_file(project_id_with_branch, opts(f_path, r_path))
         end
 
-        proc_klass.new(success: true, process: process, path: f_path)
+        ProcessResult.new(success: true, process: process, path: f_path)
       rescue StandardError => e
-        proc_klass.new(success: false, path: f_path, error: e)
+        ProcessResult.new(success: false, path: f_path, error: e)
       end
 
-      # Prints a completion message to standard output.
+      # Prints a message indicating that the export process is complete.
       def print_completion_message
         $stdout.puts 'Task complete!'
       end
 
-      # Retrieves all translation files from the specified directory.
+      # Collects all translation files that match export criteria.
       #
-      # @return [Array] Array of [Pathname, Pathname] pairs representing full and relative paths.
+      # @return [Array] List of [Pathname, Pathname] pairs (full and relative paths).
       def all_files
         loc_path = Pathname.new(config.locales_path)
 
@@ -84,11 +91,13 @@ module LokaliseManager
         end
       end
 
-      # Generates options for file upload to Lokalise.
+      # Constructs upload options for a file.
+      #
+      # Reads and encodes the file content in Base64 before sending it to Lokalise.
       #
-      # @param full_p [Pathname] Full path to the file.
+      # @param full_p [Pathname] Full file path.
       # @param relative_p [Pathname] Relative path within the project.
-      # @return [Hash] Options for the Lokalise API upload.
+      # @return [Hash] Upload options including encoded content, filename, and language.
       def opts(full_p, relative_p)
         content = File.read(full_p).strip
 
@@ -99,10 +108,14 @@ module LokaliseManager
         }.merge(config.export_opts)
       end
 
-      # Checks whether the specified file meets the criteria for upload.
+      # Determines if a file meets the criteria for export.
+      #
+      # - Must be a valid file (not a directory).
+      # - Must match the allowed file extensions.
+      # - Must not be explicitly skipped by `skip_file_export`.
       #
-      # @param full_path [Pathname] Full path to the file.
-      # @return [Boolean] True if the file matches criteria, false otherwise.
+      # @param full_path [Pathname] Full file path.
+      # @return [Boolean] `true` if the file should be uploaded, `false` otherwise.
       def file_matches_criteria?(full_path)
         full_path.file? && proper_ext?(full_path) &&
           !config.skip_file_export.call(full_path)

data/lib/lokalise_manager/task_definitions/importer.rb

@@ -6,13 +6,16 @@ require 'fileutils'
 
 module LokaliseManager
   module TaskDefinitions
-    # The Importer class handles downloading translation files from Lokalise
-    # and importing them into the specified project directory.
+    # Handles downloading translation files from Lokalise and importing them into the project directory.
     class Importer < Base
-      # Initiates the import process by checking configuration, ensuring safe mode conditions,
-      # downloading files, and processing them. Outputs task completion status.
+      # Initiates the translation import process.
       #
-      # @return [Boolean] Returns true if the import completes successfully, false if cancelled.
+      # - Validates configuration.
+      # - Ensures safe mode conditions are met.
+      # - Downloads translation files.
+      # - Extracts and processes the downloaded files.
+      #
+      # @return [Boolean] Returns `true` if the import completes successfully, `false` if cancelled.
       def import!
         check_options_errors!
 
@@ -21,7 +24,7 @@ module LokaliseManager
           return false
         end
 
-        open_and_process_zip download_files.bundle_url
+        open_and_process_zip(download_bundle)
 
         $stdout.print('Task complete!') unless config.silent_mode
         true
@@ -29,47 +32,96 @@ module LokaliseManager
 
       private
 
-      # Downloads translation files from Lokalise, handling retries and errors using exponential backoff.
+      # Retrieves the download URL of the translation files.
+      #
+      # If `import_async` is enabled, initiates an asynchronous download process.
+      #
+      # @return [String] The URL of the downloaded translation bundle.
+      def download_bundle
+        return download_files.bundle_url unless config.import_async
+
+        process = download_files_async
+        process.details['download_url'] || process.details[:download_url]
+      end
+
+      # Downloads translation files from Lokalise using a synchronous request.
+      #
+      # Handles retries and errors using exponential backoff.
       #
-      # @return [Hash] Returns the response from Lokalise API containing download details.
+      # @return [Hash] The response from Lokalise API containing download details.
       def download_files
-        with_exp_backoff(config.max_retries_import) do
-          api_client.download_files project_id_with_branch, config.import_opts
+        fetch_with_retry { api_client.download_files(project_id_with_branch, config.import_opts) }
+      end
+
+      # Initiates an asynchronous download request for translation files.
+      #
+      # Waits for the process to complete before proceeding.
+      #
+      # @return [QueuedProcess] The completed async download process object.
+      def download_files_async
+        process = fetch_with_retry { api_client.download_files_async(project_id_with_branch, config.import_opts) }
+        wait_for_async_download(process.process_id)
+      end
+
+      # Waits for an asynchronous translation file download process to finish.
+      #
+      # Uses exponential backoff for polling the process status.
+      #
+      # @param process_id [String] The ID of the asynchronous process.
+      # @return [QueuedProcess] The process object when completed successfully.
+      # @raise [LokaliseManager::Error] If the process fails or takes too long.
+      def wait_for_async_download(process_id)
+        (config.max_retries_import + 1).times do |i|
+          sleep 2**i
+          process = reload_process(process_id)
+
+          case process.status
+          when 'failed' then raise LokaliseManager::Error, 'Asynchronous download process failed'
+          when 'finished' then return process
+          end
         end
-      rescue StandardError => e
-        raise e.class, "There was an error when trying to download files: #{e.message}"
+
+        raise LokaliseManager::Error, "Asynchronous download process timed out after #{config.max_retries_import} tries"
+      end
+
+      # Retrieves the latest status of an asynchronous download process.
+      #
+      # @param process_id [String] The process ID to check.
+      # @return [QueuedProcess] The process object with updated status.
+      def reload_process(process_id)
+        api_client.queued_process project_id_with_branch, process_id
       end
 
-      # Opens a ZIP archive from a given path and processes each entry if it matches the required file extension.
+      # Extracts and processes files from a ZIP archive.
       #
       # @param path [String] The URL or local path to the ZIP archive.
       def open_and_process_zip(path)
         Zip::File.open_buffer(open_file_or_remote(path)) do |zip|
           zip.each { |entry| process_entry(entry) if proper_ext?(entry.name) }
         end
-      rescue StandardError => e
-        raise e.class, "Error processing ZIP file: #{e.message}"
       end
 
-      # Processes a single ZIP entry by extracting data, determining the correct directory structure,
-      # and writing the data to the appropriate file.
+      # Extracts data from a ZIP entry and writes it to the correct directory.
+      #
+      # - Extracts file content.
+      # - Determines the appropriate subdirectory and filename.
+      # - Writes the processed file.
       #
       # @param zip_entry [Zip::Entry] The ZIP entry to process.
       def process_entry(zip_entry)
         data = data_from(zip_entry)
-        subdir, filename = subdir_and_filename_for(zip_entry.name)
-        full_path = File.join(config.locales_path, subdir)
-        FileUtils.mkdir_p full_path
+        full_path = File.join(config.locales_path, *subdir_and_filename_for(zip_entry.name))
+        FileUtils.mkdir_p File.dirname(full_path)
 
-        File.write(File.join(full_path, filename), config.translations_converter.call(data), mode: 'w+:UTF-8')
-      rescue StandardError => e
-        raise e.class, "Error processing entry #{zip_entry.name}: #{e.message}"
+        File.write(full_path, config.translations_converter.call(data), mode: 'w+:UTF-8')
       end
 
-      # Determines if the import should proceed based on the safe mode setting and the content of the target directory.
-      # In safe mode, the directory must be empty, or the user must confirm continuation.
+      # Checks whether the import should proceed under safe mode constraints.
+      #
+      # If `import_safe_mode` is enabled, the target directory must be empty,
+      # or the user must explicitly confirm continuation.
       #
-      # @return [Boolean] Returns true if the import should proceed, false otherwise.
+      # @return [Boolean] `true` if the import should proceed, `false` otherwise.
       def proceed_when_safe_mode?
         return true unless config.import_safe_mode && !Dir.empty?(config.locales_path.to_s)
 
@@ -78,21 +130,30 @@ module LokaliseManager
         $stdin.gets.strip.upcase == 'Y'
       end
 
-      # Opens a local file or a remote URL using the provided path, safely handling different path schemes.
+      # Opens a local file or downloads a remote file.
       #
-      # @param path [String] The path to the file, either a local path or a URL.
-      # @return [IO] Returns an IO object for the file.
+      # @param path [String] The file path (local or URL).
+      # @return [IO] An IO object for reading the file.
       def open_file_or_remote(path)
         uri = URI.parse(path)
         uri.scheme&.start_with?('http') ? uri.open : File.open(path)
       end
 
-      # Loads translations from the ZIP file.
+      # Reads and processes data from a ZIP file entry.
       #
-      # @param zip_entry [Zip::Entry] The ZIP entry to process.
+      # @param zip_entry [Zip::Entry] The ZIP entry containing translation data.
+      # @return [String] The extracted file content.
       def data_from(zip_entry)
         config.translations_loader.call zip_entry.get_input_stream.read
       end
+
+      # Executes a block with exponential backoff for retrying failed operations.
+      #
+      # @yield The operation to retry.
+      # @return [Object] The result of the successful operation.
+      def fetch_with_retry(&block)
+        with_exp_backoff(config.max_retries_import, &block)
+      end
     end
   end
 end

data/lib/lokalise_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LokaliseManager
-  VERSION = '6.0.0'
+  VERSION = '6.1.1'
 end

data/lib/lokalise_manager.rb

@@ -6,33 +6,52 @@ require 'yaml'
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
-# The LokaliseManager module provides functionalities to import and export translation
-# files to and from the Lokalise TMS. It simplifies interactions with the Lokalise API
-# by providing a straightforward interface to instantiate importers and exporters.
+# The `LokaliseManager` module provides a high-level interface for importing and exporting
+# translation files between a Ruby project and the Lokalise TMS.
 #
-# Example:
-#   importer = LokaliseManager.importer(api_token: '1234abc', project_id: '123.abc')
-#   exporter = LokaliseManager.exporter(api_token: '1234abc', project_id: '123.abc')
-#   importer.import!
-#   exporter.export!
+# This module simplifies interactions with the Lokalise API by exposing two factory methods:
+# - `importer` → Instantiates an importer for fetching translations from Lokalise.
+# - `exporter` → Instantiates an exporter for uploading translations to Lokalise.
+#
+# ## Example Usage:
+#
+# ```ruby
+# importer = LokaliseManager.importer(api_token: '1234abc', project_id: '123.abc')
+# exporter = LokaliseManager.exporter(api_token: '1234abc', project_id: '123.abc')
+#
+# importer.import!
+# exporter.export!
+# ```
 #
 module LokaliseManager
   class << self
-    # Creates an importer object for downloading translation files from Lokalise.
+    # Instantiates an importer for retrieving translation files from Lokalise.
     #
-    # @param custom_opts [Hash] Custom options for the importer (e.g., API token and project ID).
-    # @param global_config [Object] Global configuration settings, defaults to LokaliseManager::GlobalConfig.
-    # @return [LokaliseManager::TaskDefinitions::Importer] An instance of the importer.
+    # @param custom_opts [Hash] Custom options for the importer (e.g., `api_token`, `project_id`).
+    # @param global_config [Object] The global configuration object (defaults to `LokaliseManager::GlobalConfig`).
+    # @return [LokaliseManager::TaskDefinitions::Importer] An `Importer` instance for downloading translations.
+    #
+    # ## Example:
+    # ```ruby
+    # importer = LokaliseManager.importer(api_token: 'xyz', project_id: '456.abc')
+    # importer.import!
+    # ```
     #
     def importer(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
       LokaliseManager::TaskDefinitions::Importer.new custom_opts, global_config
     end
 
-    # Creates an exporter object for uploading translation files to Lokalise.
+    # Instantiates an exporter for uploading translation files to Lokalise.
+    #
+    # @param custom_opts [Hash] Custom options for the exporter (e.g., `api_token`, `project_id`).
+    # @param global_config [Object] The global configuration object (defaults to `LokaliseManager::GlobalConfig`).
+    # @return [LokaliseManager::TaskDefinitions::Exporter] An `Exporter` instance for uploading translations.
     #
-    # @param custom_opts [Hash] Custom options for the exporter (e.g., API token and project ID).
-    # @param global_config [Object] Global configuration settings, defaults to LokaliseManager::GlobalConfig.
-    # @return [LokaliseManager::TaskDefinitions::Exporter] An instance of the exporter.
+    # ## Example:
+    # ```ruby
+    # exporter = LokaliseManager.exporter(api_token: 'xyz', project_id: '456.abc')
+    # exporter.export!
+    # ```
     #
     def exporter(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
       LokaliseManager::TaskDefinitions::Exporter.new custom_opts, global_config

data/lokalise_manager.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.extra_rdoc_files = ['README.md']
   spec.require_paths    = ['lib']
 
+  spec.add_dependency 'base64', '~> 0.2.0'
   spec.add_dependency 'ruby-lokalise-api', '~> 9.3'
   spec.add_dependency 'rubyzip', '~> 2.3'
   spec.add_dependency 'zeitwerk', '~> 2.4'

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: lokalise_manager
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.1.1
 platform: ruby
 authors:
 - Ilya Krukowski
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-29 00:00:00.000000000 Z
+date: 2025-02-20 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: ruby-lokalise-api
   requirement: !ruby/object:Gem::Requirement
@@ -223,7 +236,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -238,8 +250,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Lokalise integration for Ruby
 test_files: []