lokalise_rails 0.0.2.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8651b760040e8d699c07b833ee9225683a59816a7e17e8c045e8c3c57ab0c27
-  data.tar.gz: 6f50abd924998842e093d6ceb2773a711428eb840ff95ca60a6b02b4dcd6aeef
+  metadata.gz: b8341e9150b8080050eb672077a415739178279e452ccad5d9f25bc7a24f83be
+  data.tar.gz: 4b6a74a12e62625d7bd6a41c8b46a93d029ef315551d4c6883375d9bf765aa72
 SHA512:
-  metadata.gz: 30cfd51602a186da7f2986ce816ce4577412ae95a853111daf76ed62f8e1a57d0847b48e466cbefe6a5a6c978685bdbd6301eeb76c64ec92bbe06e5f962106d1
-  data.tar.gz: 53c8154a59228d3795de7f53a326cf2a05fc892503744aaeed88a38a30cbf812a1156042f870590db5d9a21dd796f15975989b4c2ac98f98842a619ca1ab5d4e
+  metadata.gz: 13f5680ba0f8cfcd279929d7ab577712b1392760ca1d11460f6290d03d1ac9c4fe4915057656e3440cdda5a0958e5b230547549c9f2d4fe431c774fd7fe9ebd2
+  data.tar.gz: 4b98524742a8ed099f176351e073526db7e9fdae8e492318ac9f86c5b6ec8a7e650d9726a0b57571856e04a973e7aa9bcd7456aa9a6117e677d5039de33d1580

data/CHANGELOG.md

@@ -1,10 +1,19 @@
 # Changelog
 
-## 0.0.2 (26-Sep-20)
+## 1.0.1 (14-Oct-20)
 
-* Fix rake task
-* Fix config template
+* Minor bug fixes and spec updates
 
-## 0.0.1 (26-Sep-20)
+## 1.0.0 (01-Oct-20)
 
-* Initial release
+* Added export feature
+* More convenient configuration and additional options
+* Other major enhancements
+
+## 0.2.0 (26-Sep-20)
+
+* Allow to override options properly
+
+## 0.1.0 (26-Sep-20)
+
+* Initial (proper) release

data/README.md

@@ -1,6 +1,6 @@
 # LokaliseRails
 
-<!-- [![Gem Version](https://badge.fury.io/rb/ruby-lokalise-api.svg)](https://badge.fury.io/rb/ruby-lokalise-api) -->
+[![Gem Version](https://badge.fury.io/rb/lokalise_rails.svg)](https://badge.fury.io/rb/lokalise_rails)
 [![Build Status](https://travis-ci.org/bodrovis/lokalise_rails.svg?branch=master)](https://travis-ci.org/bodrovis/lokalise_rails)
 [![Test Coverage](https://codecov.io/gh/bodrovis/lokalise_rails/graph/badge.svg)](https://codecov.io/gh/bodrovis/lokalise_rails)
 
@@ -10,34 +10,39 @@ This gem provides [Lokalise](http://lokalise.com) integration for Ruby on Rails
 
 ### Requirements
 
-This gem requires Ruby 2.5+ and Rails 5.1+. It might work with older versions of Rails though. You will also need to setup a Lokalise account and a translation project. Finally, you will need to generate a read/write API token at your Lokalise profile.
+This gem requires Ruby 2.5+ and Rails 5.1+. It might work with older versions of Rails though. 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.
 
 ### Installation
 
-Add the gem to your `Gemfile`
+Add the gem to your `Gemfile`:
 
 ```ruby
 gem 'lokalise_rails'
 ```
 
-and run
+and run:
 
 ```
 bundle install
 rails g lokalise_rails:install
 ```
 
-The latter command will generate a new initializer `lokalise_rails.rb` looking like this:
+The latter command will generate a new config file `config/lokalise_rails.rb` looking like this:
 
 ```ruby
 require 'lokalise_rails'
 
-LokaliseRails.api_token = ENV['LOKALISE_API_TOKEN']
-LokaliseRails.project_id = ENV['LOKALISE_PROJECT_ID']
-# ...
+LokaliseRails.config do |c|
+  c.api_token = ENV['LOKALISE_API_TOKEN']
+  c.project_id = ENV['LOKALISE_PROJECT_ID']
+
+  # ...other options
+end
 ```
 
-You have to provide `api_token` and `project_id` to proceed. [Other options can be customized as well (see below)](https://github.com/bodrovis/lokalise_rails#import-settings) but they have sensible defaults.
+You have to provide `api_token` and `project_id` to proceed. `project_id` can be found in your Lokalise project settings.
+
+[Other options can be customized as well (see below)](https://github.com/bodrovis/lokalise_rails#import-settings) but they have sensible defaults.
 
 ## Importing translations from Lokalise
 
@@ -47,31 +52,46 @@ To import translations from the specified Lokalise project to your Rails app, ru
 rails lokalise_rails:import
 ```
 
-Please note that any existing files inside the `locales` directory will be overwritten! You may enable [safe mode](https://github.com/bodrovis/lokalise_rails#import-settings) to check whether the folder is empty or not.
+Please note that any duplicating files inside the `locales` directory (or any other directory that you've specified in the options) will be overwritten! You may enable [safe mode](https://github.com/bodrovis/lokalise_rails#import-settings) to check whether the folder is empty or not.
 
-## Configuration
+## Exporting translations to Lokalise
 
-Options are specified in the `config/initializers/lokalise_rails.rb` file.
+To export translations from your Rails app to the specified Lokalise project, run the following command:
 
-### Global settings
+```
+rails lokalise_rails:export
+```
 
-* `LokaliseRails.api_token` (`string`, required) - Lokalise API token with read/write permissions.
-* `LokaliseRails.project_id` (`string`, required) - Lokalise project ID. You must have import/export permissions in the specified project.
-* `locales_path` - method returning a string with the path to your translation files. Defaults to `"#{Rails.root}/config/locales"`. To provide a custom path, override the method inside the initializer (make sure that the path exists!):
+## Running tasks programmatically
+
+You can also run the import and export tasks from the Rails app:
 
 ```ruby
-class LokaliseRails
-  class << self
-    def locales_path
-      "#{Rails.root}/config/locales_custom"
-    end
-  end
-end
+require "#{Rails.root}/config/lokalise_rails.rb"
+
+# Import the files:
+result = LokaliseRails::TaskDefinition::Importer.import!
+# `result` contains a boolean value with the result of the operation
+
+# Export the files:
+processes = LokaliseRails::TaskDefinition::Exporter.export!
+# `processes` contains a list of queued background processes
 ```
 
+## Configuration
+
+Options are specified in the `config/lokalise_rails.rb` file.
+
+### Global settings
+
+* `api_token` (`string`, required) - Lokalise API token with read/write permissions.
+* `project_id` (`string`, required) - Lokalise project ID. You must have import/export permissions in the specified project.
+* `locales_path` (`string`) - path to the directory with your translation files. Defaults to `"#{Rails.root}/config/locales"`.
+* `file_ext_regexp` (`regexp`) - regular expression applied to file extensions to determine which files should be imported and exported. Defaults to `/\.ya?ml\z/i` (YAML files).
+
 ### Import settings
 
-* `LokaliseRails.import_opts` (`hash`) - options that will be passed to Lokalise API when downloading translations to your app. Here are the default options:
+* `import_opts` (`hash`) - options that will be passed to Lokalise API when downloading translations to your app. Here are the default options:
 
 ```ruby
 {
@@ -84,8 +104,33 @@ end
 }
 ```
 
-Full list of available options [can be found at the official API documentation](https://app.lokalise.com/api2docs/curl/#transition-download-files-post).
-* `LokaliseRails.import_safe_mode` (`boolean`) - default to `false`. When this option is enabled, the import task will check whether the `locales` directory is empty or not. If it is not empty, you will be prompted to continue.
+Full list of available import options [can be found in the official API documentation](https://app.lokalise.com/api2docs/curl/#transition-download-files-post).
+* `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.
+
+### Export settings
+
+* `export_opts` (`hash`) - options that will be passed to Lokalise API when uploading translations. Full list of available export options [can be found in the official documentation](https://app.lokalise.com/api2docs/curl/#transition-download-files-post). By default, the following options are provided:
+  + `data` (`string`, required) - base64-encoded contents of the translation file.
+  + `filename` (`string`, required) - translation file name. If the file is stored under a subdirectory (for example, `nested/en.yml` inside the `locales/` directory), the whole path acts as a name. Later when importing files with such names, they will be placed into the proper subdirectories.
+  + `lang_iso` (`string`, required) - language ISO code which is determined using the root key inside your YAML file. For example, in this case the `lang_iso` is `en_US`:
+
+```yaml
+en_US:
+  my_key: "my value"
+```
+
+**Please note** that if your Lokalise project does not have a language with the specified `lang_iso` code, the export will fail.
+
+* `skip_file_export` (`lambda` or `proc`) - specify additional exclusion criteria for the exported files. By default, the rake task will ignore all non-file entries and all files with improper extensions (the latter is controlled by the `file_ext_regexp`). Lambda passed to this option should accept a single argument which is full path to the file (instance of the [`Pathname` class](https://ruby-doc.org/stdlib-2.7.1/libdoc/pathname/rdoc/Pathname.html)). For example, to exclude all files that have `fr` part in their names, add the following config:
+
+```ruby
+c.skip_file_export = ->(file) { f.split[1].to_s.include?('fr') }
+```
+
+## Running tests
+
+1. Copypaste `.env.example` file as `.env`. Put your Lokalise API token and project ID inside. The `.env` file is excluded from version control so your data is safe. All in all, we use pre-recorded VCR cassettes, so the actual API requests won’t be sent. However, providing at least some values is required.
+2. Run `rspec .`. Observe test results and code coverage.
 
 ## License
 

data/lib/generators/lokalise_rails/install_generator.rb

@@ -2,7 +2,7 @@
 
 require 'rails/generators'
 
-class LokaliseRails
+module LokaliseRails
   module Generators
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('../templates', __dir__)
@@ -10,7 +10,7 @@ class LokaliseRails
       desc 'Creates a LokaliseRails config file.'
 
       def copy_config
-        template 'lokalise_rails_config.rb', "#{Rails.root}/config/initializers/lokalise_rails.rb"
+        template 'lokalise_rails_config.rb', "#{Rails.root}/config/lokalise_rails.rb"
       end
     end
   end

data/lib/generators/templates/lokalise_rails_config.rb

@@ -2,28 +2,33 @@
 
 require 'lokalise_rails'
 
-# These are mandatory options that you must set before running rake tasks:
-LokaliseRails.api_token = ENV['LOKALISE_API_TOKEN']
-LokaliseRails.project_id = ENV['LOKALISE_PROJECT_ID']
-
-# Import options have the following defaults:
-# LokaliseRails.import_opts = {
-#   format: 'yaml',
-#   placeholder_format: :icu,
-#   yaml_include_root: true,
-#   original_filenames: true,
-#   directory_prefix: '',
-#   indentation: '2sp'
-# }
-
-# Safe mode is disabled by default:
-# LokaliseRails.import_safe_mode = false
-
-# Provide a custom path to the directory with your translation files:
-# class LokaliseRails
-#   class << self
-#     def locales_path
-#       "#{Rails.root}/config/locales"
-#     end
-#   end
-# end
+LokaliseRails.config do |c|
+  # These are mandatory options that you must set before running rake tasks:
+  # c.api_token = ENV['LOKALISE_API_TOKEN']
+  # c.project_id = ENV['LOKALISE_PROJECT_ID']
+
+  # Provide a custom path to the directory with your translation files:
+  # c.locales_path = "#{Rails.root}/config/locales"
+
+  # Import options have the following defaults:
+  # c.import_opts = {
+  #   format: 'yaml',
+  #   placeholder_format: :icu,
+  #   yaml_include_root: true,
+  #   original_filenames: true,
+  #   directory_prefix: '',
+  #   indentation: '2sp'
+  # }
+
+  # Safe mode for imports is disabled by default:
+  # c.import_safe_mode = false
+
+  # Additional export options (only filename, contents, and lang_iso params are provided by default)
+  # c.export_opts = {}
+
+  # Provide additional file exclusion criteria for exports (by default, any file with the proper extension will be exported)
+  # c.skip_file_export = ->(file) { file.split[1].to_s.include?('fr') }
+
+  # Regular expression to use when choosing the files to extract from the downloaded archive and upload to Lokalise
+  # c.file_ext_regexp = /\.ya?ml\z/i
+end

data/lib/lokalise_rails.rb

@@ -2,29 +2,54 @@
 
 require 'lokalise_rails/task_definition/base'
 require 'lokalise_rails/task_definition/importer'
+require 'lokalise_rails/task_definition/exporter'
 
-class LokaliseRails
-  @project_id = nil
-  @import_opts = {
-    format: 'yaml',
-    placeholder_format: :icu,
-    yaml_include_root: true,
-    original_filenames: true,
-    directory_prefix: '',
-    indentation: '2sp'
-  }
-  # @export_opts = {
-  #
-  # }
-  @import_safe_mode = false
-  @api_token = nil
-
+module LokaliseRails
   class << self
-    attr_accessor :import_opts, :import_safe_mode, :api_token, :export_opts,
-                  :project_id
+    attr_accessor :api_token, :project_id
+    attr_writer :import_opts, :import_safe_mode, :export_opts, :locales_path,
+                :file_ext_regexp, :skip_file_export
+
+    # Main interface to provide configuration options for rake tasks
+    def config
+      yield self
+    end
 
+    # Full path to directory with translation files
     def locales_path
-      "#{Rails.root}/config/locales"
+      @locales_path || "#{Rails.root}/config/locales"
+    end
+
+    # Regular expression used to select translation files with proper extensions
+    def file_ext_regexp
+      @file_ext_regexp || /\.ya?ml\z/i
+    end
+
+    # Options for import rake task
+    def import_opts
+      @import_opts || {
+        format: 'yaml',
+        placeholder_format: :icu,
+        yaml_include_root: true,
+        original_filenames: true,
+        directory_prefix: '',
+        indentation: '2sp'
+      }
+    end
+
+    # Options for export rake task
+    def export_opts
+      @export_opts || {}
+    end
+
+    # Enables safe mode for import. When enabled, will check whether the target folder is empty or not
+    def import_safe_mode
+      @import_safe_mode.nil? ? false : @import_safe_mode
+    end
+
+    # Additional file skip criteria to apply when performing export
+    def skip_file_export
+      @skip_file_export || ->(_) { false }
     end
   end
 end

data/lib/lokalise_rails/railtie.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require 'rubygems'
 require 'rake'
 
-class LokaliseRails
+module LokaliseRails
   class Railtie < Rails::Railtie
     rake_tasks do
-      load "tasks/lokalise_rails_tasks.rake"
+      load 'tasks/lokalise_rails_tasks.rake'
     end
   end
 end

data/lib/lokalise_rails/task_definition/base.rb

@@ -1,17 +1,48 @@
 # frozen_string_literal: true
 
 require 'ruby-lokalise-api'
-require 'open-uri'
+require 'pathname'
 
-class LokaliseRails
+module LokaliseRails
   module TaskDefinition
     class Base
       class << self
-        def check_required_opts
-          return [false, 'Project ID is not set! Aborting...'] unless LokaliseRails.project_id
-          return [false, 'Lokalise API token is not set! Aborting...'] unless LokaliseRails.api_token
+        attr_writer :api_client
 
-          [true, '']
+        # Creates a Lokalise API client
+        #
+        # @return [Lokalise::Client]
+        def api_client
+          @api_client ||= ::Lokalise.client LokaliseRails.api_token
+        end
+
+        # Checks task options
+        #
+        # @return Array
+        def opt_errors
+          errors = []
+          errors << 'Project ID is not set! Aborting...' if LokaliseRails.project_id.nil? || LokaliseRails.project_id.empty?
+          errors << 'Lokalise API token is not set! Aborting...' if LokaliseRails.api_token.nil? || LokaliseRails.api_token.empty?
+          errors
+        end
+
+        private
+
+        # Checks whether the provided file has a proper extension as dictated by the `file_ext_regexp` option
+        #
+        # @return Boolean
+        # @param raw_path [String, Pathname]
+        def proper_ext?(raw_path)
+          path = raw_path.is_a?(Pathname) ? raw_path : Pathname.new(raw_path)
+          LokaliseRails.file_ext_regexp.match? path.extname
+        end
+
+        # Returns directory and filename for the given entry
+        #
+        # @return Array
+        # @param entry [String]
+        def subdir_and_filename_for(entry)
+          Pathname.new(entry).split
         end
       end
     end

data/lib/lokalise_rails/task_definition/exporter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module LokaliseRails
+  module TaskDefinition
+    class Exporter < Base
+      class << self
+        # Performs translation file export from Rails to Lokalise and returns an array of queued processes
+        #
+        # @return [Array]
+        def export!
+          errors = opt_errors
+
+          if errors.any?
+            errors.each { |e| $stdout.puts e }
+            return errors
+          end
+
+          queued_processes = []
+          each_file do |full_path, relative_path|
+            queued_processes << api_client.upload_file(
+              LokaliseRails.project_id, opts(full_path, relative_path)
+            )
+          rescue StandardError => e
+            $stdout.puts "Error while trying to upload #{full_path}: #{e.inspect}"
+          end
+
+          $stdout.print 'Task complete!'
+
+          queued_processes
+        end
+
+        # Processes each translation file in the specified directory
+        def each_file
+          return unless block_given?
+
+          loc_path = LokaliseRails.locales_path
+          Dir["#{loc_path}/**/*"].sort.each do |f|
+            full_path = Pathname.new f
+
+            next unless file_matches_criteria? full_path
+
+            relative_path = full_path.relative_path_from Pathname.new(loc_path)
+
+            yield full_path, relative_path
+          end
+        end
+
+        # Generates export options
+        #
+        # @return [Hash]
+        # @param full_p [Pathname]
+        # @param relative_p [Pathname]
+        def opts(full_p, relative_p)
+          content = File.read full_p
+
+          lang_iso = YAML.safe_load(content)&.keys&.first
+
+          initial_opts = {
+            data: Base64.strict_encode64(content.strip),
+            filename: relative_p,
+            lang_iso: lang_iso
+          }
+
+          initial_opts.merge LokaliseRails.export_opts
+        end
+
+        # Checks whether the specified file has to be processed or not
+        #
+        # @return [Boolean]
+        # @param full_path [Pathname]
+        def file_matches_criteria?(full_path)
+          full_path.file? && proper_ext?(full_path) &&
+            !LokaliseRails.skip_file_export.call(full_path)
+        end
+      end
+    end
+  end
+end