lokalise_manager 5.1.0 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e651c10cfc08624f8bbfe88970210ed7a9e012e8637cc8cbb61aa4328942016b
-  data.tar.gz: f0dea631f1afba287ff49ff7336a1d74030347feafbafb848e8e5f445d466df9
+  metadata.gz: 82874b49ae901318d91845641a40e1c0b085764e53179799dffb54f84e205fc0
+  data.tar.gz: 5c8035fed54faf4dbd82eba23acaf172af60bf0d0cd4f4b0705bace632b1049a
 SHA512:
-  metadata.gz: d4792e56612597b654536c72b0c29550b15c9e3666da1422208d613e546cb2870b9749a7150111e40296bd5e2550ca9eacedc55715b0c28292eb1cff45eddf9c
-  data.tar.gz: 59cfbc87f48a4293fa064946d638b27510211d05bdd8dd5b9c4c63716455b55cdec851da5b2f35b4a4941d153639874bf87e2e34040cc433fe6a46ce978bc0c8
+  metadata.gz: 473fc616ce635982fe180396a3f2be51c974fd05bbca4e5f1a4780cdda9f10951a0763ce1c366abccae96ba618a20f7d9d94b150c4f9423ba72d678dec2f53cf
+  data.tar.gz: 24b1bd4791c79ef2ff0e6f1fc096b23a50a63878f55c66c10b0830d4ac614e76890a7b50d376cef649dae6970ded2215088ca95b9c96ee3124574b7594eda086

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 5.1.1
+
+* Update documentation, minor code fixes
+
 ## 5.1.0 (09-Feb-2024)
 
 * Handle rare case when the server returns HTML instead of JSON which happens when too many requests are sent

data/README.md

@@ -6,17 +6,22 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/9b682367a274ee3dcdee/maintainability)](https://codeclimate.com/github/bodrovis/lokalise_manager/maintainability)
 ![Downloads total](https://img.shields.io/gem/dt/lokalise_manager)
 
-This gem provides [Lokalise](http://lokalise.com) integration for Ruby and allows to exchange translation files between your project and TMS easily. It relies on [ruby-lokalise-api](https://lokalise.github.io/ruby-lokalise-api) to send APIv2 requests.
+The LokaliseManager gem provides seamless integration with [Lokalise](http://lokalise.com), enabling easy exchange of translation files between your Ruby project and the Lokalise translation management system (TMS). It leverages the [ruby-lokalise-api](https://lokalise.github.io/ruby-lokalise-api) to send and manage APIv2 requests.
 
-If you are looking for a Rails integration, please check [lokalise_rails](https://github.com/bodrovis/lokalise_rails) which provides a set of Rake tasks for importing/exporting.
+For integration directly with Rails applications, refer to [lokalise_rails](https://github.com/bodrovis/lokalise_rails), which offers a suite of Rake tasks specifically designed for importing and exporting translation files.
 
-## Getting started
+## Getting Started
 
 ### Requirements
 
-This gem requires Ruby 3.0+. You will also need to [setup a Lokalise account](https://app.lokalise.com/signup) and create a [translation project](https://docs.lokalise.com/en/articles/1400460-projects). Finally, you will need to generate a [read/write API token](https://docs.lokalise.com/en/articles/1929556-api-tokens) at your Lokalise profile.
+- **Ruby version**: Ruby 3.0 or higher is required.
+- **Lokalise account**: You must have an active [Lokalise account](https://app.lokalise.com/signup).
+- **Project setup**: Create a [translation project](https://docs.lokalise.com/en/articles/1400460-projects) within your Lokalise account.
+- **API token**: Obtain a read/write [API token](https://docs.lokalise.com/en/articles/1929556-api-tokens) from your Lokalise profile.
 
-Alternatively, you can utilize a token obtained via OAuth 2 flow. When using such a token, you'll have to set `:use_oauth2_token` option to `true` (see below).
+### Optional
+
+- **OAuth 2 token**: If you prefer using an OAuth 2 token instead of a standard API token, set the `:use_oauth2_token` option to `true` in your configuration settings.
 
 ### Installation
 

data/lib/lokalise_manager/error.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module LokaliseManager
-  # LokaliseManager error class, subclass of StandardError
+  # The Error class provides a custom exception type for the LokaliseManager,
+  # allowing the library to raise specific errors that can be easily identified
+  # and handled separately from other StandardError exceptions in Ruby.
   class Error < StandardError
     # Initializes a new Error object
     def initialize(message = '')

data/lib/lokalise_manager/global_config.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module LokaliseManager
-  # Global configuration options available for LokaliseManager
+  # GlobalConfig provides a central place to manage configuration settings for LokaliseManager.
+  # It allows setting various operational parameters such as API tokens, paths, and behavior modifiers.
   class GlobalConfig
     class << self
       attr_accessor :api_token, :project_id
@@ -11,58 +12,57 @@ module LokaliseManager
                   :max_retries_export, :max_retries_import, :use_oauth2_token, :silent_mode,
                   :raise_on_export_fail
 
-      # Main interface to provide configuration options
+      # Yield self to block for configuration
       def config
         yield self
       end
 
-      # When enabled, will re-raise any exception that happens during file exporting
+      # Return whether to raise on export failure
       def raise_on_export_fail
-        @raise_on_export_fail || true
+        @raise_on_export_fail.nil? ? true : @raise_on_export_fail
       end
 
-      # When enabled, won't print any debugging info to $stdout
+      # Return whether debugging information is suppressed
       def silent_mode
         @silent_mode || false
       end
 
-      # When enabled, will use OAuth 2 Lokalise client and will require to provide a token obtained via OAuth 2 flow
-      # rather than via Lokalise profile
+      # Return whether to use OAuth2 tokens instead of regular API tokens
       def use_oauth2_token
         @use_oauth2_token || false
       end
 
-      # Full path to directory with translation files
+      # Return the path to locales
       def locales_path
         @locales_path || "#{Dir.getwd}/locales"
       end
 
-      # Project branch to use
+      # Return the project branch
       def branch
         @branch || ''
       end
 
-      # Set request timeouts for the Lokalise API client
+      # Return API request timeouts
       def timeouts
         @timeouts || {}
       end
 
-      # Maximum number of retries for file exporting
+      # Return the max retries for export
       def max_retries_export
         @max_retries_export || 5
       end
 
-      # Maximum number of retries for file importing
+      # Return the max retries for import
       def max_retries_import
         @max_retries_import || 5
       end
 
-      # Regular expression used to select translation files with proper extensions
+      # Return the regex for file extensions
       def file_ext_regexp
         @file_ext_regexp || /\.ya?ml\z/i
       end
 
-      # Options for import rake task
+      # Return import options with defaults
       def import_opts
         @import_opts || {
           format: 'ruby_yaml',
@@ -74,33 +74,32 @@ module LokaliseManager
         }
       end
 
-      # Options for export rake task
+      # Return export options
       def export_opts
         @export_opts || {}
       end
 
-      # Enables safe mode for import. When enabled, will check whether the target folder is empty or not
+      # Return whether import should check if target is empty
       def import_safe_mode
         @import_safe_mode.nil? ? false : @import_safe_mode
       end
 
-      # Additional file skip criteria to apply when performing export
+      # Return whether to skip file export based on a lambda condition
       def skip_file_export
         @skip_file_export || ->(_) { false }
       end
 
+      # Load translations from raw data
       def translations_loader
-        @translations_loader || ->(raw_data) { YAML.safe_load raw_data }
+        @translations_loader || ->(raw_data) { YAML.safe_load(raw_data) }
       end
 
-      # Converts translations data to the proper format
+      # Convert raw translation data to YAML format
       def translations_converter
         @translations_converter || ->(raw_data) { YAML.dump(raw_data).gsub('\\\\n', '\n') }
       end
 
-      # Infers lang ISO for the given translation file
-      # The lambda expects to accept the raw contents of the translation file
-      # and the full path to the file (instance of the `Pathname` class)
+      # Infer language ISO code from translation file
       def lang_iso_inferer
         @lang_iso_inferer || ->(data, _path) { YAML.safe_load(data)&.keys&.first }
       end

data/lib/lokalise_manager/task_definitions/base.rb

@@ -5,17 +5,18 @@ require 'pathname'
 
 module LokaliseManager
   module TaskDefinitions
-    # Base class for LokaliseManager task definitions that includes common methods and logic
+    # Base class for LokaliseManager task definitions, including common methods and logic.
+    # This class serves as the foundation for importer and exporter classes, handling API
+    # client interactions and configuration merging.
     class Base
       using LokaliseManager::Utils::HashUtils
 
       attr_accessor :config
 
-      # Creates a new importer or exporter. It accepts custom config and merges it
-      # with the global config (custom config take precendence)
+      # Initializes a new task object by merging custom and global configurations.
       #
-      # @param custom_opts [Hash]
-      # @param global_config [Object]
+      # @param custom_opts [Hash] Custom configurations for specific tasks.
+      # @param global_config [Object] Reference to the global configuration.
       def initialize(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
         primary_opts = global_config
                        .singleton_methods
@@ -32,10 +33,12 @@ module LokaliseManager
         @config = config_klass.new all_opts
       end
 
-      # Creates a Lokalise API client
+      # Creates or retrieves a Lokalise API client based on configuration.
       #
-      # @return [RubyLokaliseApi::Client]
+      # @return [RubyLokaliseApi::Client] Lokalise API client.
       def api_client
+        return @api_client if @api_client
+
         client_opts = [config.api_token, config.timeouts]
         client_method = config.use_oauth2_token ? :oauth2_client : :client
 
@@ -51,41 +54,36 @@ module LokaliseManager
 
       private
 
-      # Checks task options
-      #
-      # @return Array
+      # Checks and validates task options, raising errors if configurations are missing.
       def check_options_errors!
         errors = []
         errors << 'Project ID is not set!' if config.project_id.nil? || config.project_id.empty?
         errors << 'Lokalise API token is not set!' if config.api_token.nil? || config.api_token.empty?
-
-        raise(LokaliseManager::Error, errors.join(' ')) if errors.any?
+        raise LokaliseManager::Error, errors.join(' ') if errors.any?
       end
 
-      # Checks whether the provided file has a proper extension as dictated by the `file_ext_regexp` option
+      # Determines if the file has the correct extension based on the configuration.
       #
-      # @return Boolean
-      # @param raw_path [String, Pathname]
+      # @param raw_path [String, Pathname] Path to check.
+      # @return [Boolean] True if the extension matches, 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
 
-      # Returns directory and filename for the given entry
+      # Extracts the directory and filename from a given path.
       #
-      # @return Array
-      # @param entry [String]
+      # @param entry [String] The file path.
+      # @return [Array] Contains [Pathname, Pathname] representing the directory and filename.
       def subdir_and_filename_for(entry)
         Pathname.new(entry).split
       end
 
-      # Returns Lokalise project ID and branch, semicolumn separated
+      # Constructs a project identifier string that may include a branch.
       #
-      # @return [String]
+      # @return [String] Project identifier potentially including the branch.
       def project_id_with_branch
-        return config.project_id.to_s if config.branch.to_s.strip.empty?
-
-        "#{config.project_id}:#{config.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.
@@ -93,7 +91,7 @@ module LokaliseManager
       # Until this is fixed, we revert to this quick'n'dirty solution.
       EXCEPTIONS = [JSON::ParserError, RubyLokaliseApi::Error::TooManyRequests].freeze
 
-      # Sends request with exponential backoff mechanism
+      # Implements an exponential backoff strategy for handling retries after failures.
       def with_exp_backoff(max_retries)
         return unless block_given?
 

data/lib/lokalise_manager/task_definitions/exporter.rb

@@ -4,14 +4,14 @@ require 'base64'
 
 module LokaliseManager
   module TaskDefinitions
-    # Exporter class is used when you want to upload translation files from your project to Lokalise
+    # Class to handle exporting translation files from a local project to Lokalise.
     class Exporter < Base
-      # Lokalise allows no more than 6 requests per second
+      # Maximum number of concurrent uploads to avoid exceeding Lokalise API rate limits.
       MAX_THREADS = 6
 
-      # Performs translation file export to Lokalise and returns an array of queued processes
+      # Exports translation files to Lokalise and handles any necessary concurrency and error checking.
       #
-      # @return [Array]
+      # @return [Array] An array of process statuses for each file uploaded.
       def export!
         check_options_errors!
 
@@ -25,16 +25,21 @@ module LokaliseManager
           end
         end
 
-        $stdout.print('Task complete!') unless config.silent_mode
+        print_completion_message unless config.silent_mode
 
         queued_processes
       end
 
       private
 
+      # Handles parallel uploads of a group of files, utilizing threading.
+      #
+      # @param files_group [Array] Group of files to be uploaded.
+      # @return [Array] Array of threads handling the file uploads.
+
       def parallel_upload(files_group)
         files_group.map do |file_data|
-          do_upload(*file_data)
+          Thread.new { do_upload(*file_data) }
         end.map(&:value)
       end
 
@@ -44,21 +49,28 @@ module LokaliseManager
         raise(thread.error.class, "Error while trying to upload #{thread.path}: #{thread.error.message}")
       end
 
-      # Performs the actual file uploading to Lokalise. If the API rate limit is exceeed,
-      # applies exponential backoff
+      # Performs the actual upload of a file to Lokalise.
+      #
+      # @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.
       def do_upload(f_path, r_path)
         proc_klass = Struct.new(:success, :process, :path, :error, keyword_init: true)
-
-        Thread.new do
+        begin
           process = with_exp_backoff(config.max_retries_export) do
-            api_client.upload_file project_id_with_branch, opts(f_path, r_path)
+            api_client.upload_file(project_id_with_branch, opts(f_path, r_path))
           end
-          proc_klass.new success: true, process: process, path: f_path
+          proc_klass.new(success: true, process: process, path: f_path)
         rescue StandardError => e
-          proc_klass.new success: false, path: f_path, error: e
+          proc_klass.new(success: false, path: f_path, error: e)
         end
       end
 
+      # Prints a completion message to standard output.
+      def print_completion_message
+        $stdout.print('Task complete!')
+      end
+
       # Gets translation files from the specified directory
       def all_files
         loc_path = config.locales_path

data/lib/lokalise_manager/task_definitions/importer.rb

@@ -6,11 +6,14 @@ require 'fileutils'
 
 module LokaliseManager
   module TaskDefinitions
-    # Importer class is used when you want to download translation files from Lokalise into your project
+    # The Importer class is responsible for downloading translation files from Lokalise
+    # and importing them into the specified project directory. This class extends the Base class,
+    # which provides shared functionality and configuration management.
     class Importer < Base
-      # Performs translation files import from Lokalise
+      # Initiates the import process by checking configuration, ensuring safe mode conditions,
+      # downloading files, and processing them. Outputs task completion status.
       #
-      # @return [Boolean]
+      # @return [Boolean] Returns true if the import completes successfully, false if cancelled.
       def import!
         check_options_errors!
 
@@ -27,10 +30,9 @@ module LokaliseManager
 
       private
 
-      # Downloads files from Lokalise using the specified config.
-      # Utilizes exponential backoff if "too many requests" error is received
+      # Downloads translation files from Lokalise, handling retries and errors using exponential backoff.
       #
-      # @return [Hash]
+      # @return [Hash] Returns 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
@@ -39,45 +41,40 @@ module LokaliseManager
         raise e.class, "There was an error when trying to download files: #{e.message}"
       end
 
-      # Opens ZIP archive (local or remote) with translations and processes its entries
+      # Opens a ZIP archive from a given path and processes each entry if it matches the required file extension.
       #
-      # @param path [String]
+      # @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|
-          fetch_zip_entries(zip) { |entry| process!(entry) }
-        end
-      rescue StandardError => e
-        raise(e.class, "There was an error when trying to process the downloaded files: #{e.message}")
-      end
-
-      # Iterates over ZIP entries. Each entry may be a file or folder.
-      def fetch_zip_entries(zip)
-        return unless block_given?
-
-        zip.each do |entry|
-          next unless proper_ext? entry.name
+          zip.each do |entry|
+            next unless proper_ext?(entry.name)
 
-          yield entry
+            process_entry(entry)
+          end
         end
+      rescue StandardError => e
+        raise e.class, "Error processing ZIP file: #{e.message}"
       end
 
-      # Processes ZIP entry by reading its contents and creating the corresponding translation file
-      def process!(zip_entry)
-        data = data_from zip_entry
-        subdir, filename = subdir_and_filename_for zip_entry.name
-        full_path = "#{config.locales_path}/#{subdir}"
+      # Processes a single ZIP entry by extracting data, determining the correct directory structure,
+      # and writing the data to the appropriate 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
 
-        File.open(File.join(full_path, filename), 'w+:UTF-8') do |f|
-          f.write config.translations_converter.call(data)
-        end
+        File.write(File.join(full_path, filename), config.translations_converter.call(data), mode: 'w+:UTF-8')
       rescue StandardError => e
-        raise e.class, "Error when trying to process #{zip_entry&.name}: #{e.message}"
+        raise e.class, "Error processing entry #{zip_entry.name}: #{e.message}"
       end
 
-      # Checks whether the user wishes to proceed when safe mode is enabled and the target directory is not empty
+      # 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.
       #
-      # @return [Boolean]
+      # @return [Boolean] Returns 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)
 
@@ -87,9 +84,10 @@ module LokaliseManager
         answer.to_s.strip == 'Y'
       end
 
-      # Opens a local file or a remote URL using the provided patf
+      # Opens a local file or a remote URL using the provided path, safely handling different path schemes.
       #
-      # @return [String]
+      # @param path [String] The path to the file, either a local path or a URL.
+      # @return [IO] Returns an IO object for the file.
       def open_file_or_remote(path)
         parsed_path = URI.parse(path)
 
@@ -100,6 +98,9 @@ module LokaliseManager
         end
       end
 
+      # Loads translations from the ZIP file.
+      #
+      # @param zip_entry [Zip::Entry] The ZIP entry to process.
       def data_from(zip_entry)
         config.translations_loader.call zip_entry.get_input_stream.read
       end

data/lib/lokalise_manager/version.rb

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

data/lib/lokalise_manager.rb

@@ -6,34 +6,34 @@ require 'yaml'
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
-# LokaliseManager main module that exposes helper methods:
-#
-#   importer = LokaliseManager.importer api_token: '1234abc', project_id: '123.abc'
-#   exporter = LokaliseManager.exporter api_token: '1234abc', project_id: '123.abc'
-#
-# Use the instantiated objects to import or export your translation files:
+# 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.
 #
+# 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!
 #
 module LokaliseManager
   class << self
-    # Initializes a new importer client which is used to download
-    # translation files from Lokalise to the current project
+    # Creates an importer object for downloading 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.
     #
-    # @return [LokaliseManager::TaskDefinitions::Importer]
-    # @param custom_opts [Hash]
-    # @param global_config [Object]
     def importer(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
       LokaliseManager::TaskDefinitions::Importer.new custom_opts, global_config
     end
 
-    # Initializes a new exporter client which is used to upload
-    # translation files from the current project to Lokalise
+    # Creates an exporter object for uploading translation files to Lokalise.
+    #
+    # @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.
     #
-    # @return [LokaliseManager::TaskDefinitions::Exporter]
-    # @param custom_opts [Hash]
-    # @param global_config [Object]
     def exporter(custom_opts = {}, global_config = LokaliseManager::GlobalConfig)
       LokaliseManager::TaskDefinitions::Exporter.new custom_opts, global_config
     end

data/lokalise_manager.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'rubyzip', '~> 2.3'
   spec.add_dependency 'zeitwerk', '~> 2.4'
 
-  spec.add_development_dependency 'dotenv', '~> 2.5'
+  spec.add_development_dependency 'dotenv', '~> 3.0'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.6'
   spec.add_development_dependency 'rubocop', '~> 1.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lokalise_manager
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.1.1
 platform: ruby
 authors:
 - Ilya Krukowski
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-09 00:00:00.000000000 Z
+date: 2024-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-lokalise-api
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -238,7 +238,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: Lokalise integration for Ruby