lokalise_rails 0.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec64235246d319002907d0e605f89196248a50698bb3a7f50f0bebdd706cf7d5
-  data.tar.gz: 8ae1100974fe1c4672a0ad264e83f70cdd424e77ae7a28249b921a26b086296b
+  metadata.gz: 02b78ecae0b5dbf76599249606858c5b24e31fc9826f8795feb34abac9d5ffb4
+  data.tar.gz: b7bc51d45b689181ae0d3d5366f507ae0e43c878c4ab55979ba54d7089eb49f7
 SHA512:
-  metadata.gz: e77be0ceee5396a3343855f6fb917dfbf8d68568497f9afa0700c73a9fbbf1f7aa6ff1c07ff36c33c8ee55c83b2a77bb3cdd6fc012fe90e038c186b157eaac42
-  data.tar.gz: 8655ee9cfd99362515d2acf669669b9ed8017590e3b0cd695ac6ac51826944d0945dba2f363ea7c269d284664237264be6e3ec9fc6989886799113549b4d9dfd
+  metadata.gz: 838ddae7af99842dbc4a7ce900c8b02a07571ff9c561e642e3bac6f92dbaabd9132f775b0ff1877ffd18fc20c1bf84ec3f7792139bad0c9fc97dec1d03389e64
+  data.tar.gz: 79c0314752c8e48b552eb78c564d24da0cd14fa41b1195909d8d06ca81913322fefa56a696f3c20d1c53c51aa16feb731c85f6fdd860242c98ad8b018b9c68ae

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.2.0 (11-Nov-20)
+
+* New option `translations_loader`
+* New option `translations_converter`
+* New option `lang_iso_inferer`
+
+## 1.1.0 (23-Oct-20)
+
+* New option `branch`
+* New option `timeouts`
+* New method `.reset_api_client!` for the task definitions
+
+## 1.0.1 (14-Oct-20)
+
+* 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,50 @@ 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
+```
+
+## Running tasks programmatically
 
-* `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!):
+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"`.
+* `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 +110,43 @@ 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') }
+```
+
+### Settings to work with formats other than YAML
+
+If your translation files are not in YAML format, you will need to adjust the following options:
+
+* `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).
+* `translations_loader` (`lambda` or `proc`) - loads translations data and makes sure they are valid before saving them to a translation file. Defaults to `->(raw_data) { YAML.safe_load raw_data }`. In the simplest case you may just return the data back, for example `-> (raw_data) { raw_data }`.
+* `translations_converter` (`lambda` or `proc`) - converts translations data to a proper format before saving them to a translation file. Defaults to `->(raw_data) { raw_data.to_yaml }`. In the simplest case you may just return the data back, for example `-> (raw_data) { raw_data }`.
+* `lang_iso_inferer` (`lambda` or `proc`) - infers language ISO code based on the translation file data before uploading it to Lokalise. Defaults to `->(data) { YAML.safe_load(data)&.keys&.first }`.
+
+## 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,49 @@
 
 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') }
+
+  # Set the options below if you would like to work with format other than YAML
+  ## 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
+
+  ## Load translations data and make sure they are valid:
+  ## c.translations_loader = ->(raw_data) { YAML.safe_load raw_data }
+
+  ## Convert translations data to a proper format:
+  ## c.translations_converter = ->(raw_data) { raw_data.to_yaml }
+
+  ## Infer language ISO code for the translation file:
+  ## c.lang_iso_inferer = ->(data) { YAML.safe_load(data)&.keys&.first }
+end

data/lib/lokalise_rails.rb

@@ -2,29 +2,79 @@
 
 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,
+                :translations_loader, :translations_converter, :lang_iso_inferer
+
+    # 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
+
+    def translations_loader
+      @translations_loader || ->(raw_data) { YAML.safe_load raw_data }
+    end
+
+    # Converts translations data to the proper format
+    def translations_converter
+      @translations_converter || ->(raw_data) { raw_data.to_yaml }
+    end
+
+    # Infers lang ISO for the given translation file
+    def lang_iso_inferer
+      @lang_iso_inferer || ->(data) { YAML.safe_load(data)&.keys&.first }
     end
   end
 end

data/lib/lokalise_rails/railtie.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require 'rake'
-
-class LokaliseRails
+module LokaliseRails
   class Railtie < Rails::Railtie
     rake_tasks do
       load 'tasks/lokalise_rails_tasks.rake'

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