remote_translation_loader 1.0.4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92eee5223d395967a5ed0da0f77e8b0082596974847bf384b39a4bec420f6c4f
-  data.tar.gz: 9353b66874cf73808bbf137ec49ddc0cb5f32b968fce808ff249ec7aa88e8308
+  metadata.gz: 59ac9fed7d52b1170939188c6351ff9f1cadb3fce0d75a4449abd88cbb072d83
+  data.tar.gz: 36876a8b0aa0420dd664edad81d3996c633fc15d9d74837705975818d40826c4
 SHA512:
-  metadata.gz: ea0fdabb80e283838537963f7e06c6cd26f0880e12d56398fb799437146775cf940a6a0f85df31409c1feebb1da0f69cb266b9731393f8626022dcbc385e39a3
-  data.tar.gz: 873aa22bd67fb54947a4e4eb66033891003d3d008da58a5189110ef69df45d3de0040df8b77accb26dde183ba8f5b9aef7bec1ea04e5ae760ad3d245d35f826c
+  metadata.gz: 85f5a569008fd4af358e37eb52863dc13f1e9d985623843d9f696488856bb460d98e54db331d42c0c4686fae3dba586caa9e72924db622b69df468c48cf5e016
+  data.tar.gz: 4b4060fc821ee2eb958c59e96beb0d0b5a961859c3257f14679bd122eafd979dbeea7ac118e6f3c5b8bc9efed5b300bf70a26b36df37b3ff40648f23d9633260

data/README.md

@@ -1,19 +1,30 @@
 # RemoteTranslationLoader
 
-**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.
+[![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)
+
+
+**RemoteTranslationLoader** is a Ruby gem designed to dynamically fetch and load translation files (YAML or JSON) 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.
 
 ---
 
 ## **Features**
 
-- Fetch translations from multiple sources:
-   - **HTTP URLs**
+- Fetch translations from multiple sources, auto-detected from the source string:
+   - **HTTP(S) URLs**
    - **Local files**
-   - **AWS S3 buckets**
+   - **AWS S3 buckets** (`s3://bucket/key`)
+- Mix sources of different kinds in a single call — no need to instantiate a fetcher per type.
+- Supports both **YAML** and **JSON** translation files.
 - 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.
+- Automatic retry with backoff for transient HTTP failures.
+- Structured error classes (`FetchError`, `ParseError`, `ValidationError`) instead of generic runtime errors.
+- Rake task and Rails `Railtie` for zero-config integration.
 - CLI tool for manual loading.
 
 ---
@@ -42,21 +53,42 @@ gem install remote_translation_loader
 
 ## **Usage**
 
-### **Basic Usage**
+### **Basic Usage — auto-detected sources**
+
+The simplest way to use the gem: just pass a list of sources. Each one is
+auto-detected as HTTP, a local file, or S3 (`s3://bucket/key`) — you can freely
+mix all three in one call:
 
-#### **1. HTTP Fetching**
 ```ruby
 require 'remote_translation_loader'
 
+RemoteTranslationLoader.load([
+  'https://example.com/en.yml',
+  '/path/to/local/fr.yml',
+  's3://my-bucket/translations/de.yml'
+])
+```
+
+`RemoteTranslationLoader.load(sources, **options)` is sugar for
+`RemoteTranslationLoader::Loader.new(sources).fetch_and_load(**options)`.
+
+Note: using an `s3://` source requires the `aws-sdk-s3` gem — add
+`gem 'aws-sdk-s3'` to your Gemfile if you fetch from S3.
+
+### **Explicit fetchers**
+
+You can still force every source through a specific fetcher instead of
+auto-detection:
+
+#### **1. HTTP Fetching**
+```ruby
 urls = ['https://example.com/en.yml', 'https://example.com/fr.yml']
-loader = RemoteTranslationLoader::Loader.new(urls)
+loader = RemoteTranslationLoader::Loader.new(urls, fetcher: RemoteTranslationLoader::Fetchers::HttpFetcher.new)
 loader.fetch_and_load
 ```
 
 #### **2. Local File Fetching**
 ```ruby
-require 'remote_translation_loader'
-
 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
@@ -64,10 +96,8 @@ loader.fetch_and_load
 
 #### **3. AWS S3 Fetching**
 ```ruby
-require 'remote_translation_loader'
-
 bucket = 'your-s3-bucket'
-s3_fetcher = RemoteTranslationLoader::Fetchers::S3Fetcher.new(bucket, region: 'us-east-1')
+s3_fetcher = RemoteTranslationLoader::Fetchers::S3Fetcher.new(bucket, s3_client: Aws::S3::Client.new(region: 'us-east-1'))
 keys = ['translations/en.yml', 'translations/fr.yml']
 
 loader = RemoteTranslationLoader::Loader.new(keys, fetcher: s3_fetcher)
@@ -109,7 +139,22 @@ remote_translation_loader https://example.com/en.yml /path/to/local/fr.yml
 
 ## **Rails Integration**
 
-### **1. Rake Task**
+### **1. Zero-config with the Railtie (recommended)**
+
+When `remote_translation_loader` is loaded inside a Rails app, its `Railtie` is
+required automatically. Configure sources once and translations load on boot,
+and refresh on every reload in development:
+
+#### `config/initializers/remote_translation_loader.rb`
+```ruby
+RemoteTranslationLoader.configure do |config|
+  config.sources = ['https://example.com/en.yml', 's3://my-bucket/fr.yml']
+  config.namespace = 'remote'
+  config.logger = Rails.logger
+end
+```
+
+### **3. Rake Task**
 Use the provided Rake task to fetch translations in a Rails application:
 
 #### Add this to your `Rakefile`:
@@ -123,17 +168,16 @@ load 'remote_translation_loader/tasks/remote_translation_loader.rake'
 rake translations:load[https://example.com/en.yml,/path/to/local/fr.yml]
 ```
 
-### **2. Automatic Loading**
+### **4. Manual Initializer**
 
-Add an initializer to load translations on application startup:
+If you'd rather not use the Railtie, load translations explicitly:
 
 #### `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')
+RemoteTranslationLoader.load(urls, namespace: 'remote')
 ```
 
 ---

data/lib/remote_translation_loader/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module RemoteTranslationLoader
+  class Configuration
+    attr_accessor :sources, :namespace, :dry_run, :logger
+
+    def initialize
+      @sources = []
+      @namespace = nil
+      @dry_run = false
+      @logger = Logger.new($stdout)
+    end
+  end
+end

data/lib/remote_translation_loader/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RemoteTranslationLoader
+  class Error < StandardError; end
+
+  # Raised when a fetcher can't retrieve content from its source
+  # (network failure, missing file, S3 error, etc.).
+  class FetchError < Error; end
+
+  # Raised when fetched content can't be parsed as YAML/JSON.
+  class ParseError < Error; end
+
+  # Raised when parsed content isn't a valid translations hash.
+  class ValidationError < Error; end
+end

data/lib/remote_translation_loader/fetchers/base_fetcher.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "yaml"
+require "json"
+
 module RemoteTranslationLoader
   module Fetchers
     class BaseFetcher
@@ -7,10 +10,21 @@ module RemoteTranslationLoader
         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}"
+      def parse(content, format: :yaml)
+        case format
+        when :json
+          JSON.parse(content)
+        else
+          YAML.safe_load(content, aliases: true)
+        end
+      rescue Psych::SyntaxError, Psych::DisallowedClass, JSON::ParserError => e
+        raise ParseError, "Failed to parse content: #{e.message}"
+      end
+
+      # Infers :json vs :yaml from a source's file extension. Defaults to :yaml
+      # (covers .yml/.yaml and extension-less sources like plain URLs).
+      def format_for(source)
+        File.extname(source.to_s).delete_prefix(".").downcase == "json" ? :json : :yaml
       end
     end
   end

data/lib/remote_translation_loader/fetchers/file_fetcher.rb

@@ -1,15 +1,12 @@
 # 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?
+    class FileFetcher < BaseFetcher
+      def fetch(path)
+        raise FetchError, "File not found: #{path}" unless File.exist?(path)
 
-        parse(response.body.to_s)
+        parse(File.read(path), format: format_for(path))
       end
     end
   end

data/lib/remote_translation_loader/fetchers/http_fetcher.rb

@@ -1,12 +1,39 @@
 # frozen_string_literal: true
 
+require "http"
+
 module RemoteTranslationLoader
   module Fetchers
-    class FileFetcher < BaseFetcher
-      def fetch(path)
-        raise "File not found: #{path}" unless File.exist?(path)
+    class HttpFetcher < BaseFetcher
+      DEFAULT_RETRIES = 3
+      DEFAULT_TIMEOUT = 10 # seconds
+      RETRYABLE_ERRORS = [HTTP::Error, HTTP::TimeoutError, HTTP::ConnectionError].freeze
+
+      def initialize(retries: DEFAULT_RETRIES, timeout: DEFAULT_TIMEOUT)
+        @retries = retries
+        @timeout = timeout
+      end
+
+      def fetch(url)
+        response = with_retries(url) { HTTP.timeout(@timeout).get(url) }
+        raise FetchError, "Failed to fetch data from #{url} (status #{response.status})" unless response.status.success?
+
+        parse(response.body.to_s, format: format_for(url))
+      end
+
+      private
+
+      def with_retries(url)
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue *RETRYABLE_ERRORS => e
+          raise FetchError, "Failed to fetch data from #{url}: #{e.message}" if attempt > @retries
 
-        parse(File.read(path))
+          sleep(2**(attempt - 1) * 0.1)
+          retry
+        end
       end
     end
   end

data/lib/remote_translation_loader/fetchers/s3_fetcher.rb

@@ -1,17 +1,35 @@
 # 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
+      def initialize(bucket, s3_client: nil)
+        @bucket = bucket
+        @s3_client_override = s3_client
+      end
+
+      def fetch(key)
+        response = s3_client.get_object(bucket: @bucket, key: key)
+        parse(response.body.read, format: format_for(key))
+      rescue Aws::S3::Errors::ServiceError => e
+        raise FetchError, "Failed to fetch #{key} from S3 bucket #{@bucket}: #{e.message}"
       end
 
-      def fetch(bucket, key)
-        response = @s3_client.get_object(bucket: bucket, key: key)
-        parse(response.body.read)
+      private
+
+      # Building the real Aws::S3::Client (and requiring aws-sdk-s3) is deferred
+      # until the first actual fetch, so simply constructing an S3Fetcher never
+      # requires the aws-sdk-s3 gem or AWS credentials/region to be configured.
+      def s3_client
+        @s3_client ||= @s3_client_override || begin
+          begin
+            require "aws-sdk-s3"
+          rescue LoadError
+            raise LoadError, "S3Fetcher requires the aws-sdk-s3 gem. Add `gem 'aws-sdk-s3'` to your Gemfile."
+          end
+
+          Aws::S3::Client.new
+        end
       end
     end
   end

data/lib/remote_translation_loader/loader.rb

@@ -1,19 +1,25 @@
-require 'i18n'
+require "i18n"
+require "logger"
 
 module RemoteTranslationLoader
   class Loader
-    def initialize(urls, fetcher: Fetchers::HttpFetcher.new)
+    # `fetcher:` can be left unset to auto-detect the right fetcher per source
+    # (http(s):// -> HttpFetcher, s3://bucket/key -> S3Fetcher, else -> FileFetcher).
+    # Pass an explicit fetcher to force every source through it instead.
+    def initialize(urls, fetcher: nil, logger: Logger.new($stdout))
       @urls = urls
       @fetcher = fetcher
+      @resolver = SourceResolver.new if @fetcher.nil?
+      @logger = logger
     end
 
     def fetch_and_load(dry_run: false, namespace: nil)
       @urls.each do |url|
-        content = @fetcher.fetch(url)
-        validate_translations!(content)
+        content = fetch_content(url)
+        validate_translations!(content, url)
 
         if dry_run
-          puts "Simulating loading for #{url}: #{content.inspect}"
+          @logger.info("Simulating loading for #{url}: #{content.inspect}")
         else
           merge_into_i18n(content, namespace: namespace)
         end
@@ -22,8 +28,19 @@ module RemoteTranslationLoader
 
     private
 
-    def validate_translations!(translations)
-      raise "Invalid translations format!" unless translations.is_a?(Hash)
+    def fetch_content(url)
+      if @fetcher
+        @fetcher.fetch(url)
+      else
+        fetcher, key = @resolver.resolve(url)
+        fetcher.fetch(key)
+      end
+    end
+
+    def validate_translations!(translations, source)
+      return if translations.is_a?(Hash)
+
+      raise ValidationError, "Invalid translations format for #{source}: expected a Hash, got #{translations.class}"
     end
 
     def merge_into_i18n(content, namespace: nil)
@@ -35,7 +52,7 @@ module RemoteTranslationLoader
         merged = deep_merge(existing, translations)
         I18n.backend.store_translations(locale.to_sym, merged)
       end
-      puts "Translations loaded successfully!"
+      @logger.info("Translations loaded successfully!")
     end
 
     def deep_merge(existing, incoming)

data/lib/remote_translation_loader/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RemoteTranslationLoader
+  # Zero-config Rails integration. Configure once:
+  #
+  #   RemoteTranslationLoader.configure do |config|
+  #     config.sources = ["https://example.com/en.yml", "s3://bucket/fr.yml"]
+  #     config.namespace = "remote"
+  #   end
+  #
+  # and translations are fetched on boot, and refreshed on every reload in
+  # development.
+  class Railtie < ::Rails::Railtie
+    initializer "remote_translation_loader.load_translations" do
+      RemoteTranslationLoader.load_configured_translations
+    end
+
+    config.to_prepare do
+      RemoteTranslationLoader.load_configured_translations if Rails.env.development?
+    end
+  end
+end

data/lib/remote_translation_loader/source_resolver.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RemoteTranslationLoader
+  # Given a plain source string, resolves which Fetcher should handle it and
+  # what key/path/url to pass to that fetcher's `#fetch`. This lets a single
+  # Loader mix HTTP, local file, and S3 sources in one call without the
+  # caller having to construct fetchers manually.
+  #
+  #   s3://my-bucket/path/to/en.yml -> S3Fetcher
+  #   http(s)://...                 -> HttpFetcher
+  #   anything else                 -> FileFetcher
+  class SourceResolver
+    S3_URI = %r{\As3://(?<bucket>[^/]+)/(?<key>.+)\z}.freeze
+    HTTP_URI = %r{\Ahttps?://}i.freeze
+
+    def initialize
+      @s3_fetchers = {}
+      @http_fetcher = Fetchers::HttpFetcher.new
+      @file_fetcher = Fetchers::FileFetcher.new
+    end
+
+    # Returns [fetcher, key] where `fetcher.fetch(key)` retrieves the content.
+    def resolve(source)
+      str = source.to_s
+
+      if (match = S3_URI.match(str))
+        [s3_fetcher_for(match[:bucket]), match[:key]]
+      elsif HTTP_URI.match?(str)
+        [@http_fetcher, str]
+      else
+        [@file_fetcher, str]
+      end
+    end
+
+    private
+
+    def s3_fetcher_for(bucket)
+      @s3_fetchers[bucket] ||= Fetchers::S3Fetcher.new(bucket)
+    end
+  end
+end

data/lib/remote_translation_loader/version.rb

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

data/lib/remote_translation_loader.rb

@@ -1,11 +1,40 @@
 # frozen_string_literal: true
 
 require_relative "remote_translation_loader/version"
-require_relative "remote_translation_loader/loader"
+require_relative "remote_translation_loader/errors"
+require_relative "remote_translation_loader/configuration"
 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"
+require_relative "remote_translation_loader/source_resolver"
+require_relative "remote_translation_loader/loader"
 
 module RemoteTranslationLoader
+  class << self
+    # One-liner convenience: RemoteTranslationLoader.load(["en.yml", "https://.../fr.yml"])
+    def load(sources, **options)
+      Loader.new(sources).fetch_and_load(**options)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Used by the Railtie to fetch+load whatever was set via `.configure`.
+    def load_configured_translations
+      config = configuration
+      return if config.sources.empty?
+
+      Loader.new(config.sources, logger: config.logger)
+            .fetch_and_load(dry_run: config.dry_run, namespace: config.namespace)
+    end
+  end
 end
+
+require_relative "remote_translation_loader/railtie" if defined?(Rails::Railtie)

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.2"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: remote_translation_loader
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 2.0.0
 platform: ruby
 authors:
 - Gokul (gklsan)
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-11-30 00:00:00.000000000 Z
+date: 2026-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -25,19 +24,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: yaml
+  name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -53,19 +52,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.13.0
 - !ruby/object:Gem::Dependency
-  name: i18n
+  name: aws-sdk-s3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.14.5
+        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.14.5
+        version: '1'
 description: The remote_translation_loader gem allows you to fetch YAML translation
   files from remote sources and dynamically load them into your Rails application’s
   I18n translations without writing them to local files.
@@ -81,13 +80,18 @@ files:
 - README.md
 - Rakefile
 - lib/remote_translation_loader.rb
+- lib/remote_translation_loader/configuration.rb
+- lib/remote_translation_loader/errors.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/railtie.rb
+- lib/remote_translation_loader/source_resolver.rb
 - lib/remote_translation_loader/tasks/remote_translation_loader.rake
 - lib/remote_translation_loader/version.rb
+- mise.toml
 - sig/remote_translation_loader.rbs
 homepage: https://github.com/gklsan/remote_translation_loader
 licenses:
@@ -95,8 +99,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/gklsan/remote_translation_loader
   source_code_uri: https://github.com/gklsan/remote_translation_loader
-  changelog_uri: https://github.com/gklsan/remote_translation_loader
-post_install_message: 
+  bug_tracker_uri: https://github.com/gklsan/remote_translation_loader/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -111,8 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.6
 specification_version: 4
 summary: Fetches and loads remote YAML translation files into Rails I18n
 test_files: []