remote_translation_loader 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39a20a05a27f27a7ee285c238b407b1d0053dcaf3e13d00a4c921e55e7046df9
-  data.tar.gz: d804308dbeebe07dc34f6910cae12d795399912c502d93d2c46f35925dac9162
+  metadata.gz: 630b226c234b0e1e9a7924ccb6c9d6aed627d212d8c96f73b5430a0da6e2a33e
+  data.tar.gz: ff2437901e7631175cb2acea53876775b29be23d9d09a8be5c8db5a17b227d42
 SHA512:
-  metadata.gz: 490ec23b5607c361c6872e1cdd7d1265980744c51714e35d36d461c1946d4715a8c89ba74e375efd78a00c20763d0e573ff07d1b38bd43aa6a76c011ecadceeb
-  data.tar.gz: 8c2e25fe0bf39717e51e76001c8387a307a8a001cc875afbf3ae9370e2670aabb1e43a1c53703d86fcc8a243e5af032b4f1302f6eeec5907d43e054c11177a62
+  metadata.gz: 6319d125210796a2aebb8621d50a25f21ebea905321a02295970d0ef4891cfe822c98cbf17460d0bac3ba98179bf76e8498f2989e39357cc5ab4161c67fba17e
+  data.tar.gz: 328d493ea7a39831d05d9cd543d952aeb91bb2d5e731feac10e8390ba8ba01a98f110ab7d7212ebe30e6bb1812822370b71591b825b4ff930cc4b32de29d0ee5

data/README.md

@@ -1,15 +1,31 @@
-# Remote Translation Loader [![Gem Version](https://badge.fury.io/rb/remote_translation_loader.svg)](https://badge.fury.io/rb/remote_translation_loader)
+# RemoteTranslationLoader
 
-`remote_translation_loader` is a Ruby gem for fetching YAML translation files from remote sources and dynamically loading them into your Ruby on Rails application’s I18n translations. This gem is useful for applications that need to integrate external translations without writing them to local files.
+[![Gem Version](https://badge.fury.io/rb/remote_translation_loader.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/remote_translation_loader)
+[![Downloads](https://img.shields.io/gem/dt/remote_translation_loader.svg)](https://badge.fury.io/rb/remote_translation_loader)
+[![Github forks](https://img.shields.io/github/forks/gklsan/remote_translation_loader.svg)](https://github.com/gklsan/remote_translation_loader/network)
+[![Github stars](https://img.shields.io/github/stars/gklsan/remote_translation_loader.svg)](https://github.com/gklsan/remote_translation_loader/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
 
-- Fetch translation files from remote URLs
-- Merge remote translations with local translations
-- Directly load translations into Rails I18n without writing to files
-- Handles YAML parsing errors and HTTP request failures
+**RemoteTranslationLoader** is a Ruby gem designed to dynamically fetch and load translation files (YAML format) into your Ruby or Ruby on Rails application. It supports multiple sources such as HTTP URLs, local files, and AWS S3, allowing you to seamlessly integrate external translations.
 
-## Installation
+---
+
+## **Features**
+
+- Fetch translations from multiple sources:
+   - **HTTP URLs**
+   - **Local files**
+   - **AWS S3 buckets**
+- Supports deep merging of translations with existing `I18n` backend.
+- Namespace support for isolating translations.
+- Dry-run mode to simulate translation loading.
+- Rake tasks for easy integration with Rails applications.
+- CLI tool for manual loading.
+
+---
+
+## **Installation**
 
 Add this line to your application's Gemfile:
 
@@ -17,120 +33,169 @@ Add this line to your application's Gemfile:
 gem 'remote_translation_loader'
 ```
 
-Then execute:
+And then execute:
 
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
+Or install it directly:
 
 ```bash
 gem install remote_translation_loader
 ```
 
-## Usage
+---
 
-### Basic Setup
+## **Usage**
 
-1. **Initialize the Loader**
+### **Basic Usage**
 
-   Create an instance of the `RemoteTranslationLoader::Loader` class with a list of remote YAML URLs:
+#### **1. HTTP Fetching**
+```ruby
+require 'remote_translation_loader'
 
-   ```ruby
-   loader = RemoteTranslationLoader::Loader.new([
-     'https://example.com/translations/en.yml',
-     'https://example.com/translations/fr.yml'
-   ])
-   ```
+urls = ['https://example.com/en.yml', 'https://example.com/fr.yml']
+loader = RemoteTranslationLoader::Loader.new(urls)
+loader.fetch_and_load
+```
 
-2. **Fetch and Load Translations**
+#### **2. Local File Fetching**
+```ruby
+require 'remote_translation_loader'
 
-   Call the `fetch_and_load` method to fetch and load the translations:
+files = ['/path/to/local/en.yml', '/path/to/local/fr.yml']
+loader = RemoteTranslationLoader::Loader.new(files, fetcher: RemoteTranslationLoader::Fetchers::FileFetcher.new)
+loader.fetch_and_load
+```
 
-   ```ruby
-   loader.fetch_and_load
-   ```
+#### **3. AWS S3 Fetching**
+```ruby
+require 'remote_translation_loader'
 
-   This will:
-    - Fetch the YAML files from the specified URLs
-    - Parse the YAML content
-    - Merge the remote translations with your existing local translations
-    - Load the merged translations into Rails I18n
+bucket = 'your-s3-bucket'
+s3_fetcher = RemoteTranslationLoader::Fetchers::S3Fetcher.new(bucket, region: 'us-east-1')
+keys = ['translations/en.yml', 'translations/fr.yml']
 
-### Example
+loader = RemoteTranslationLoader::Loader.new(keys, fetcher: s3_fetcher)
+loader.fetch_and_load
+```
 
+---
+
+### **Advanced Options**
+
+#### **Namespace Support**
+Add a namespace to group translations under a specific key:
 ```ruby
-require 'remote_translation_loader'
+loader.fetch_and_load(namespace: 'remote')
+# Translations will be grouped under the `remote` key, e.g., `remote.en.some_key`
+```
+
+#### **Dry-Run Mode**
+Simulate the loading process without modifying the `I18n` backend:
+```ruby
+loader.fetch_and_load(dry_run: true)
+# Outputs fetched translations to the console without loading them
+```
 
-# Initialize the loader with remote YAML URLs
-loader = RemoteTranslationLoader::Loader.new([
-  'https://example.com/translations/en.yml',
-  'https://example.com/translations/fr.yml'
-])
+---
 
-# Fetch and load translations
-loader.fetch_and_load
+## **CLI Usage**
+
+Install the gem globally and use the CLI tool:
 
-# Now you can use the loaded translations in your application
-puts I18n.t('greetings.hello') # Output will depend on the remote translation files
+```bash
+remote_translation_loader https://example.com/en.yml /path/to/local/fr.yml
 ```
 
-### Handling Errors
+- The CLI fetches and loads the specified translations.
+- Add the executable to your `$PATH` for easier access.
 
-The gem will raise errors in case of:
-- **Invalid YAML Content**: If the remote YAML file is invalid, a `RuntimeError` will be raised with a message indicating a YAML parsing error.
-- **HTTP Request Failures**: If fetching the remote YAML file fails, a `RuntimeError` will be raised with a message indicating the failure.
+---
 
-### Customizing Error Handling
+## **Rails Integration**
 
-You can customize the error handling by rescuing from `RuntimeError` or any other specific exceptions as needed:
+### **1. Rake Task**
+Use the provided Rake task to fetch translations in a Rails application:
 
+#### Add this to your `Rakefile`:
 ```ruby
-begin
-  loader.fetch_and_load
-rescue RuntimeError => e
-  puts "An error occurred: #{e.message}"
-end
+require 'remote_translation_loader'
+load 'remote_translation_loader/tasks/remote_translation_loader.rake'
 ```
 
-## Development
+#### Run the task:
+```bash
+rake translations:load[https://example.com/en.yml,/path/to/local/fr.yml]
+```
 
-To contribute to the development of `remote_translation_loader`, follow these steps:
+### **2. Automatic Loading**
 
-1. **Clone the Repository**
+Add an initializer to load translations on application startup:
 
-   ```bash
-   git clone https://github.com/gklsan/remote_translation_loader.git
-   cd remote_translation_loader
-   ```
+#### `config/initializers/remote_translation_loader.rb`
+```ruby
+require 'remote_translation_loader'
+
+urls = ['https://example.com/en.yml', '/path/to/local/fr.yml']
+loader = RemoteTranslationLoader::Loader.new(urls)
+loader.fetch_and_load(namespace: 'remote')
+```
+
+---
+
+## **Contributing**
 
-2. **Install Dependencies**
+We welcome contributions! Follow these steps:
 
+1. Fork the repository.
+2. Create your feature branch:
    ```bash
-   bundle install
+   git checkout -b feature/my-new-feature
+   ```
+3. Commit your changes:
+   ```bash
+   git commit -m 'Add some feature'
    ```
+4. Push the branch:
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+5. Create a pull request.
+
+---
 
-3. **Run Tests**
+## **Development**
 
-   Run the test suite to ensure everything is working correctly:
+To work on the gem locally:
 
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/gklsan/remote_translation_loader.git
+   cd remote_translation_loader
+   ```
+2. Install dependencies:
+   ```bash
+   bundle install
+   ```
+3. Run tests:
    ```bash
-   bundle exec rspec
+   rspec
    ```
 
-4. **Make Your Changes**
+---
 
-   Implement your changes or features and ensure they are covered by tests.
+## **License**
 
-5. **Submit a Pull Request**
+This gem is released under the MIT License. See the [LICENSE](LICENSE) file for details.
 
-   Push your changes to your forked repository and submit a pull request with a clear description of the changes.
+---
 
-## License
+## **Acknowledgments**
 
-`remote_translation_loader` is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+A big thanks to the open-source community for the inspiration and support. Special mention to contributors who helped shape this gem!
 
-## Contact
+---
 
-For questions or support, please open an issue on [GitHub](https://github.com/gklsan/remote_translation_loader/issues).
+For questions, bug reports, or feature requests, feel free to [open an issue](https://github.com/gklsan/remote_translation_loader/issues). 🚀

data/lib/remote_translation_loader/fetchers/base_fetcher.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RemoteTranslationLoader
+  module Fetchers
+    class BaseFetcher
+      def fetch(_source)
+        raise NotImplementedError, "Subclasses must implement the `fetch` method"
+      end
+
+      def parse(content)
+        YAML.safe_load(content)
+      rescue Psych::SyntaxError => e
+        raise "Failed to parse content: #{e.message}"
+      end
+    end
+  end
+end

data/lib/remote_translation_loader/fetchers/file_fetcher.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'http'
+
+module RemoteTranslationLoader
+  module Fetchers
+    class HttpFetcher < BaseFetcher
+      def fetch(url)
+        response = HTTP.get(url)
+        raise "Failed to fetch data from #{url}" unless response.status.success?
+
+        parse(response.body.to_s)
+      end
+    end
+  end
+end

data/lib/remote_translation_loader/fetchers/http_fetcher.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RemoteTranslationLoader
+  module Fetchers
+    class FileFetcher < BaseFetcher
+      def fetch(path)
+        raise "File not found: #{path}" unless File.exist?(path)
+
+        parse(File.read(path))
+      end
+    end
+  end
+end

data/lib/remote_translation_loader/fetchers/s3_fetcher.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-s3'
+
+module RemoteTranslationLoader
+  module Fetchers
+    class S3Fetcher < BaseFetcher
+      def initialize(s3_client = Aws::S3::Client.new)
+        @s3_client = s3_client
+      end
+
+      def fetch(bucket, key)
+        response = @s3_client.get_object(bucket: bucket, key: key)
+        parse(response.body.read)
+      end
+    end
+  end
+end

data/lib/remote_translation_loader/loader.rb

@@ -0,0 +1,47 @@
+require 'i18n'
+
+module RemoteTranslationLoader
+  class Loader
+    def initialize(urls, fetcher: Fetchers::HttpFetcher.new)
+      @urls = urls
+      @fetcher = fetcher
+    end
+
+    def fetch_and_load(dry_run: false, namespace: nil)
+      @urls.each do |url|
+        content = @fetcher.fetch(url)
+        validate_translations!(content)
+
+        if dry_run
+          puts "Simulating loading for #{url}: #{content.inspect}"
+        else
+          merge_into_i18n(content, namespace: namespace)
+        end
+      end
+    end
+
+    private
+
+    def validate_translations!(translations)
+      raise "Invalid translations format!" unless translations.is_a?(Hash)
+    end
+
+    def merge_into_i18n(content, namespace: nil)
+      content.each do |locale, translations|
+        next unless translations.is_a?(Hash)
+
+        translations = { namespace => translations } if namespace
+        existing = I18n.backend.send(:translations)[locale.to_sym] || {}
+        merged = deep_merge(existing, translations)
+        I18n.backend.store_translations(locale.to_sym, merged)
+      end
+      puts "Translations loaded successfully!"
+    end
+
+    def deep_merge(existing, incoming)
+      existing.merge(incoming) do |_, old_val, new_val|
+        old_val.is_a?(Hash) && new_val.is_a?(Hash) ? deep_merge(old_val, new_val) : new_val
+      end
+    end
+  end
+end

data/lib/remote_translation_loader/tasks/remote_translation_loader.rake

@@ -0,0 +1,11 @@
+namespace :translations do
+  desc "Fetch and load remote translations"
+  task :load, [:urls] => :environment do |_task, args|
+    urls = args[:urls].to_s.split(',')
+    raise "No URLs provided" if urls.empty?
+
+    loader = RemoteTranslationLoader::Loader.new(urls)
+    loader.fetch_and_load
+    puts "Translations loaded successfully!"
+  end
+end

data/lib/remote_translation_loader/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RemoteTranslationLoader
-  VERSION = "1.0.3"
+  VERSION = "1.1.0"
 end

data/lib/remote_translation_loader.rb

@@ -1,54 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "remote_translation_loader/version"
-
-require 'http'
-require 'yaml'
-require 'i18n'
+require_relative "remote_translation_loader/loader"
+require_relative "remote_translation_loader/fetchers/base_fetcher"
+require_relative "remote_translation_loader/fetchers/http_fetcher"
+require_relative "remote_translation_loader/fetchers/file_fetcher"
+require_relative "remote_translation_loader/fetchers/s3_fetcher"
 
 module RemoteTranslationLoader
-  class Loader
-    def initialize(urls)
-      @urls = urls
-    end
-
-    def fetch_and_load
-      @urls.each do |url|
-        yml_content = fetch_yaml(url)
-        merge_into_i18n(yml_content)
-      end
-    end
-
-    private
-
-    def fetch_yaml(url)
-      response = HTTP.get(url)
-      raise "Failed to fetch YAML from #{url}" unless response.status.success?
-
-      begin
-        YAML.safe_load(response.body.to_s)
-      rescue Psych::SyntaxError => e
-        raise "Failed to parse YAML from #{url}: #{e.message}"
-      end
-    end
-
-    def merge_into_i18n(yml_content)
-      yml_content.each do |locale, remote_translations|
-        if remote_translations.is_a?(Hash)
-          existing_translations = I18n.backend.send(:translations)[locale.to_sym] || {}
-          merged_translations = deep_merge(existing_translations, remote_translations)
-
-          I18n.backend.store_translations(locale.to_sym, merged_translations)
-        else
-          raise "Invalid data format for locale #{locale}"
-        end
-      end
-    end
-
-    def deep_merge(existing, incoming)
-      existing.merge(incoming) do |key, oldval, newval|
-        oldval.is_a?(Hash) && newval.is_a?(Hash) ? deep_merge(oldval, newval) : newval
-      end
-    end
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remote_translation_loader
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Gokul (gklsan)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-08 00:00:00.000000000 Z
+date: 2025-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -81,6 +81,12 @@ files:
 - README.md
 - Rakefile
 - lib/remote_translation_loader.rb
+- lib/remote_translation_loader/fetchers/base_fetcher.rb
+- lib/remote_translation_loader/fetchers/file_fetcher.rb
+- lib/remote_translation_loader/fetchers/http_fetcher.rb
+- lib/remote_translation_loader/fetchers/s3_fetcher.rb
+- lib/remote_translation_loader/loader.rb
+- lib/remote_translation_loader/tasks/remote_translation_loader.rake
 - lib/remote_translation_loader/version.rb
 - sig/remote_translation_loader.rbs
 homepage: https://github.com/gklsan/remote_translation_loader
@@ -105,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Fetches and loads remote YAML translation files into Rails I18n