better_translate 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04ce5f4b9e73378af8eec2409688e26dfef6fb42268b8817800c8c3433877eaf
-  data.tar.gz: 0b34308c1ef74dd3ad74b8cbc0b546cf831f2e43c3f3e2628cb636511ab33289
+  metadata.gz: '08c6af60f2eb66076d7f9fe0e603d13ae497f637380fba4a261961d570097312'
+  data.tar.gz: 7973a4254e17ae0a714e7fea96124916ffd27539e1610ef9ad1409627854af3b
 SHA512:
-  metadata.gz: e63e571fa9f0a881c25d35d4cb31f5cfaa0fbed2e84d3847e50f9b6f811685b5a13666408b48f0e61666232916c8cbf803dda11a6e51bcca9813f1e97b696435
-  data.tar.gz: 94f9664d32402395d9a575c2e1ae8f04b29781421fd7a4b266ae7bf0c7a2c21d345ab73762397d50028d01482255b0a10319c4799c25056256c39e0d43269df0
+  metadata.gz: 0bee7264dfe205b313a3326602c81590cda09ab283fc6a98145452c14c8d4ef4f756f1a2cfae6836c88a8fb9240f35549b7a8dc4ffdeb782d7fcfbc34d738bb0
+  data.tar.gz: ac9dc01081105b202448ac4dd0cec510b8f7bff7eb72426a009650a756cd9ff74ca97b2916fa569f14569f9963d3ce0798f7dadbfc1b7411e51ea975b645dd0a

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to BetterTranslate will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-03-12
+
+### Added
+- Custom Translation Provider support:
+  - New generator: `rails generate better_translate:provider YourProviderName`
+  - Provider registration system via `BetterTranslate::Service.register_provider`
+  - Dynamic API key configuration for custom providers
+  - Comprehensive documentation and examples for creating custom providers
+  - Template files with implementation instructions
+- Enhanced Service class:
+  - Provider registry for managing custom providers
+  - Improved error handling with better error messages
+  - Method to list all available providers
+- Updated documentation:
+  - New section in README for custom providers
+  - Step-by-step guide for implementing custom translation services
+  - Example implementation for DeepL integration
+
 ## [0.4.2] - 2025-03-11
 
 ### Added

data/README.md

@@ -19,7 +19,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
 
 ## Why BetterTranslate? 🤔
 
-- 🌐 **AI-Powered Translation**: Leverage ChatGPT and Google Gemini for high-quality translations
+- 🌐 **AI-Powered Translation**: Leverage ChatGPT, Google Gemini, and custom providers for high-quality translations
 - 🔄 **Smart Translation Modes**:
   - `Override`: Full file rewrite
   - `Incremental`: Update only new/modified keys
@@ -29,6 +29,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
   - Dot notation support
 - 🛠 **Developer-Friendly**:
   - Rails generators included
+  - Custom provider support
   - Comprehensive test suite
   - LRU caching for performance
   - Progress tracking
@@ -47,7 +48,7 @@ BetterTranslate simplifies the translation of YAML files in your Ruby/Rails appl
 Add the gem to your Gemfile:
 
 ```ruby
-gem 'better_translate', '~> 0.4.2'
+gem 'better_translate', '~> 0.5.0'
 ```
 
 Then run:
@@ -159,6 +160,12 @@ The gem includes generators to simplify tasks:
   rails generate better_translate:analyze
   ```
 
+- **Create Custom Provider:**
+
+  ```bash
+  rails generate better_translate:provider YourProviderName
+  ```
+
   The `better_translate:analyze` generator will:
   - Scan all YAML files in your locales directory
   - Find similar translations using Levenshtein distance
@@ -172,6 +179,76 @@ The gem includes generators to simplify tasks:
   - Optimize your translation files
   - Reduce translation costs
 
+### Custom Translation Providers
+
+BetterTranslate allows you to create and use custom translation providers, enabling integration with any translation API or service. This feature is particularly useful if you want to use a translation service not natively supported by BetterTranslate, such as DeepL, Microsoft Translator, Amazon Translate, or any other API-based translation service.
+
+1. **Generate a custom provider template:**
+
+   ```bash
+   rails generate better_translate:provider DeepL
+   ```
+
+   This creates a new provider class in `app/providers/deep_l_provider.rb` and a README with implementation instructions.
+
+2. **Implement the translation logic:**
+
+   Edit the generated provider file to implement the `translate_text` method with your API-specific code:
+
+   ```ruby
+   # app/providers/deep_l_provider.rb
+   module Providers
+     class DeepLProvider < BetterTranslate::Providers::BaseProvider
+       def initialize(api_key)
+         @api_key = api_key
+       end
+
+       def translate_text(text, target_lang_code, target_lang_name)
+         # Implement your API call to DeepL here
+         # Return the translated text as a string
+       end
+     end
+   end
+   ```
+
+3. **Register your provider:**
+
+   Create an initializer to register your custom provider:
+
+   ```ruby
+   # config/initializers/better_translate_providers.rb
+   # Require the provider file to ensure it's loaded
+   require Rails.root.join('app', 'providers', 'deep_l_provider')
+   
+   BetterTranslate::Service.register_provider(
+     :deepl,
+     ->(api_key) { Providers::DeepLProvider.new(api_key) }
+   )
+   ```
+   
+   Note: The `require` statement is important to ensure the provider class is loaded before it's used.
+
+4. **Update your configuration:**
+
+   Add your API key to the BetterTranslate configuration:
+
+   ```ruby
+   # config/initializers/better_translate.rb
+   BetterTranslate.configure do |config|
+     config.provider = :deepl
+     config.deepl_key = ENV['DEEPL_API_KEY']
+     # ... other configuration
+   end
+   ```
+
+5. **Use your custom provider:**
+
+   Your custom provider will now be used when you call `BetterTranslate.magic` or any other translation method.
+
+6. **Troubleshooting:**
+
+   If you encounter a `NameError` related to the `Providers` module, make sure the provider file is properly required in your initializer as shown in step 3. The `require` statement ensures that the provider class is loaded before it's used.
+
 ### Translation Helpers
 
 BetterTranslate provides helper methods to simplify translation tasks.

data/lib/better_translate/service.rb

@@ -1,6 +1,8 @@
 module BetterTranslate
   # Service class that handles translation requests using the configured provider.
   # Implements a Least Recently Used (LRU) cache to avoid redundant translation requests.
+  # Supports built-in providers (ChatGPT, Gemini) and custom providers registered via
+  # the register_provider class method.
   #
   # @example
   #   service = BetterTranslate::Service.new
@@ -9,6 +11,9 @@ module BetterTranslate
     # Maximum number of translations to keep in the LRU cache
     MAX_CACHE_SIZE = 1000
 
+    # Registry for custom providers
+    @@provider_registry = {}
+
     # Initializes a new Service instance.
     # Sets up the translation provider based on configuration and initializes the LRU cache.
     #
@@ -30,22 +35,22 @@ module BetterTranslate
     # @return [String] The translated text
     def translate(text, target_lang_code, target_lang_name)
       cache_key = "#{text}:#{target_lang_code}"
-      
+
       # Prova a recuperare dalla cache
       cached = cache_get(cache_key)
       return cached if cached
-      
+
       # Traduci e salva in cache
       start_time = Time.now
       result = provider_instance.translate_text(text, target_lang_code, target_lang_name)
       duration = Time.now - start_time
-      
+
       BetterTranslate::Utils.track_metric("translation_request_duration", {
         provider: @provider_name,
         text_length: text.length,
         duration: duration
       })
-      
+
       cache_set(cache_key, result)
     end
 
@@ -77,7 +82,7 @@ module BetterTranslate
         oldest_key = @cache_order.shift
         @translation_cache.delete(oldest_key)
       end
-      
+
       @translation_cache[key] = value
       @cache_order.push(key)
       value
@@ -87,7 +92,8 @@ module BetterTranslate
 
     # Creates or returns a cached instance of the translation provider.
     # The provider is determined by the configuration and instantiated with the appropriate API key.
-    # Supports ChatGPT and Gemini providers.
+    # Supports built-in providers (ChatGPT, Gemini) and custom providers registered via
+    # the register_provider class method.
     #
     # @return [BetterTranslate::Providers::BaseProvider] An instance of the configured translation provider
     # @raise [RuntimeError] If the configured provider is not supported
@@ -98,8 +104,41 @@ module BetterTranslate
                              when :gemini
                                Providers::GeminiProvider.new(BetterTranslate.configuration.google_gemini_key)
                              else
-                               raise "Provider non supportato: #{@provider_name}"
+                               if @@provider_registry.key?(@provider_name)
+                                 # Get the API key from configuration dynamically
+                                 api_key_method = "#{@provider_name}_key".to_sym
+                                 if BetterTranslate.configuration.respond_to?(api_key_method)
+                                   api_key = BetterTranslate.configuration.send(api_key_method)
+                                   @@provider_registry[@provider_name].call(api_key)
+                                 else
+                                   raise "API key configuration missing for provider: #{@provider_name}. Add config.#{@provider_name}_key to your BetterTranslate configuration."
+                                 end
+                               else
+                                 raise "Provider not supported: #{@provider_name}. Available providers: #{available_providers.join(', ')}"
+                               end
                              end
     end
+
+    # Returns a list of all available provider names
+    # @return [Array<Symbol>] List of available provider names
+    def available_providers
+      [:chatgpt, :gemini] + @@provider_registry.keys
+    end
+
+    # Registers a custom provider for use with BetterTranslate
+    # 
+    # @param name [Symbol] The name of the provider to register
+    # @param factory [Proc] A proc that takes an API key and returns a provider instance
+    # @return [Symbol] The name of the registered provider
+    # 
+    # @example Register a custom DeepL provider
+    #   BetterTranslate::Service.register_provider(
+    #     :deepl,
+    #     ->(api_key) { Providers::DeepLProvider.new(api_key) }
+    #   )
+    def self.register_provider(name, factory)
+      @@provider_registry[name] = factory
+      name
+    end
   end
 end

data/lib/better_translate/version.rb

@@ -9,5 +9,5 @@ module BetterTranslate
   # - PATCH version for backwards-compatible bug fixes
   #
   # @return [String] The current version in the format "MAJOR.MINOR.PATCH"
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

data/lib/generators/better_translate/templates/better_translate.rb

@@ -1,5 +1,5 @@
 BetterTranslate.configure do |config|
-  # Choose the provider to use: :chatgpt or :gemini
+  # Choose the provider to use: :chatgpt, :gemini, or any custom provider registered with BetterTranslate::Service.register_provider
   config.provider = :chatgpt
 
   # API key for OpenAI
@@ -7,6 +7,13 @@ BetterTranslate.configure do |config|
 
   # API key for Google Gemini
   config.google_gemini_key = ENV.fetch("GOOGLE_GEMINI_KEY") { "YOUR_GOOGLE_GEMINI_KEY" }
+  
+  # Custom provider API keys
+  # If you've created a custom provider using 'rails generate better_translate:provider YourProvider',
+  # add its API key here following the naming convention: config.your_provider_key
+  # 
+  # Example for a custom DeepL provider:
+  # config.deepl_key = ENV.fetch("DEEPL_API_KEY") { "YOUR_DEEPL_API_KEY" }
 
   # Source language (for example "en" if the source file is in English)
   config.source_language = "en"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_translate
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Alessio Bussolari