lokalise_rails 0.0.2.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3534f3c4ec2f391a4bc454f939c70ae39036b855d5f45ef2cca8d1d4da82b22
-  data.tar.gz: cd0af317585439b45ea19fd84025c0237f68c5836f2569de0990bcad60892725
+  metadata.gz: 951a2d142a56078d2d9509fa36c13f87f7069b8f2defa9bd158a90a67aba2b9a
+  data.tar.gz: ac2360ad608a4251c9061454c0fea986f868facb90567a5bcd94ae01d33bd8e3
 SHA512:
-  metadata.gz: ae321510ab6329e94cf8b4b7b29eea10e5dee417564b2aa698d08d9d930615cf29200e46ba6580effc6784d0c7a823b4082199a9e34b70f89bb27594f5ac1753
-  data.tar.gz: 12d9b443f8fecb53db19a2c478ea9d8a38478d8ca7bfa786cfdd19303a41e507afe049370d631ae73d10150594c21ff6762ca40e663bea8db07c3201a13ca602
+  metadata.gz: 4f41072fa0c0e138fc3f6a838b672c50e0f3af799e151b0cbc2b66aa1792446c6cdde4a1426ed1a5243871c48cc55bc9e12439ecc7eb00be090629ad0a77bd4c
+  data.tar.gz: ae1acd8d95ce227c8c16a362d2fb0d0bc371a986e5108043a7d9f3037bf292e1da2a48efa4c84720e7a4f1f1e66c13e757ba59ababe1ab081d77960516340803

data/CHANGELOG.md

@@ -1,10 +1,25 @@
 # Changelog
 
-## 0.0.2 (26-Sep-20)
+## 1.1.0 (23-Oct-20)
 
-* Fix rake task
-* Fix config template
+* New option `branch`
+* New option `timeouts`
+* New method `.reset_api_client!` for the task definitions
 
-## 0.0.1 (26-Sep-20)
+## 1.0.1 (14-Oct-20)
 
-* Initial release
+* Minor bug fixes and spec updates
+
+## 1.0.0 (01-Oct-20)
+
+* 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,43 +1,50 @@
 # 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)
 
 This gem provides [Lokalise](http://lokalise.com) integration for Ruby on Rails and allows to exchange translation files easily. It relies on [ruby-lokalise-api](https://lokalise.github.io/ruby-lokalise-api) to send APIv2 requests.
 
+*If you would like to know how this gem was built, check out the ["How to create a Ruby gem" series at Lokalise blog](https://lokalise.com/blog/create-a-ruby-gem-basics/).*
+
 ## Getting started
 
 ### 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 +54,51 @@ 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
+
+```ruby
+# Export the files:
+processes = LokaliseRails::TaskDefinition::Exporter.export!
 ```
 
+`processes` contains a list of [queued background processes](https://lokalise.github.io/ruby-lokalise-api/api/queued-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).
+* `branch` (`string`) - Lokalise project branch to use. Defaults to `"master"`.
+* `timeouts` (`hash`) - set [request timeouts for the Lokalise API client](https://lokalise.github.io/ruby-lokalise-api/additional_info/customization#setting-timeouts). By default, requests have no timeouts: `{open_timeout: nil, timeout: nil}`. Both values are in seconds.
+
 ### 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,9 +111,34 @@ 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
 
-Copyright (c) [Lokalise team](http://lokalise.com), [Ilya Bodrov](http://bodrovis.tech)
+Copyright (c) [Lokalise team](http://lokalise.com), [Ilya Bodrov](http://bodrovis.tech). License type is [MIT](https://github.com/bodrovis/lokalise_rails/blob/master/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,39 @@
 
 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"
+
+  # Provide a Lokalise project branch to use:
+  # c.branch = 'master'
+
+  # Provide request timeouts for the Lokalise API client:
+  # c.timeouts = {open_timeout: nil, timeout: nil}
+
+  # 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,64 @@
 
 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, :branch, :timeouts
+
+    # 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
+
+    # Project branch to use
+    def branch
+      @branch || 'master'
+    end
+
+    # Set request timeouts for the Lokalise API client
+    def timeouts
+      @timeouts || {}
+    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,9 @@
 # frozen_string_literal: true
 
-require 'rubygems'
-require 'rake'
-
-class LokaliseRails
+module LokaliseRails
   class Railtie < Rails::Railtie
     rake_tasks do
-      load File.expand_path('../../tasks/lokalise_rails_tasks.rake', __FILE__)
+      load 'tasks/lokalise_rails_tasks.rake'
     end
   end
 end

data/lib/lokalise_rails/task_definition/base.rb

@@ -1,17 +1,61 @@
 # 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, LokaliseRails.timeouts
+        end
+
+        # Resets API client
+        def reset_api_client!
+          Lokalise.reset_client!
+          @api_client = nil
+        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
+
+        # Returns Lokalise project ID and branch, semicolumn separated
+        #
+        # @return [String]
+        def project_id_with_branch
+          "#{LokaliseRails.project_id}:#{LokaliseRails.branch}"
         end
       end
     end