feat: make engine_id optional, use /process/localize endpoint

Author: AndreyHirsa

README.md

@@ -61,15 +61,6 @@ result = engine.localize_text(
   source_locale: 'en'
 )
 # => "Hola mundo"
-
-# Fast mode for quicker results
-result = engine.localize_text(
-  'Hello world',
-  target_locale: 'de',
-  source_locale: 'en',
-  fast: true
-)
-# => "Hallo Welt"
 ```
 
 ### Object localization
@@ -285,7 +276,7 @@ The SDK can be configured when creating an engine instance:
 ```ruby
 engine = LingoDotDev::Engine.new(
   api_key: 'your-api-key',          # Required: Your Lingo.dev API key
-  engine_id: 'your-engine-id',      # Required: Your engine ID
+  engine_id: 'your-engine-id',      # Optional: Your engine ID
   api_url: 'https://api.lingo.dev', # Optional: API endpoint URL
   batch_size: 25,                    # Optional: Max items per batch (1-250)
   ideal_batch_item_size: 250         # Optional: Target word count per batch (1-2500)
@@ -306,7 +297,7 @@ end
 | Option                  | Type    | Default                    | Description                               |
 | ----------------------- | ------- | -------------------------- | ----------------------------------------- |
 | `api_key`               | String  | Required                   | Your Lingo.dev API key                    |
-| `engine_id`             | String  | Required                   | Your engine ID for localization processing|
+| `engine_id`             | String  | `nil`                      | Your engine ID for localization processing|
 | `api_url`               | String  | `https://api.lingo.dev`    | API endpoint URL                          |
 | `batch_size`            | Integer | `25`                       | Maximum items per batch (1-250)           |
 | `ideal_batch_item_size` | Integer | `250`                      | Target word count per batch item (1-2500) |
@@ -315,51 +306,49 @@ end
 
 ### Instance methods
 
-#### `localize_text(text, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)`
+#### `localize_text(text, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)`
 
 Localizes a string to the target locale.
 
 - **Parameters:**
   - `text` (String): Text to localize
   - `target_locale` (String): Target locale code (e.g., 'es', 'fr', 'ja')
   - `source_locale` (String): Source locale code (e.g., 'en')
-  - `fast` (Boolean, optional): Enable fast mode
   - `reference` (Hash, optional): Additional context for translation
   - `on_progress` (Proc, optional): Progress callback
   - `concurrent` (Boolean): Enable concurrent processing
   - `&block`: Alternative progress callback
 - **Returns:** Localized string
 
-#### `localize_object(obj, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)`
+#### `localize_object(obj, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)`
 
 Localizes all string values in a Hash.
 
 - **Parameters:** Same as `localize_text`, with `obj` (Hash) instead of `text`
 - **Returns:** Localized Hash
 
-#### `localize_chat(chat, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)`
+#### `localize_chat(chat, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)`
 
 Localizes chat messages. Each message must have `:name` and `:text` keys.
 
 - **Parameters:** Same as `localize_text`, with `chat` (Array) instead of `text`
 - **Returns:** Array of localized chat messages
 
-#### `localize_html(html, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)`
+#### `localize_html(html, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)`
 
 Localizes an HTML document while preserving structure and formatting. Handles both text content and localizable attributes (alt, title, placeholder, meta content).
 
 - **Parameters:**
   - `html` (String): HTML document string to localize
   - `target_locale` (String): Target locale code (e.g., 'es', 'fr', 'ja')
   - `source_locale` (String): Source locale code (e.g., 'en')
-  - `fast` (Boolean, optional): Enable fast mode
   - `reference` (Hash, optional): Additional context for translation
   - `on_progress` (Proc, optional): Progress callback
   - `concurrent` (Boolean): Enable concurrent processing
   - `&block`: Alternative progress callback
 - **Returns:** Localized HTML document string with updated `lang` attribute
 
-#### `batch_localize_text(text, target_locales:, source_locale:, fast: nil, reference: nil, concurrent: false)`
+#### `batch_localize_text(text, target_locales:, source_locale:, reference: nil, concurrent: false)`
 
 Localizes text to multiple target locales.
 
@@ -369,7 +358,7 @@ Localizes text to multiple target locales.
   - Other parameters same as `localize_text`
 - **Returns:** Array of localized strings
 
-#### `batch_localize_objects(objects, target_locale:, source_locale:, fast: nil, reference: nil, concurrent: false)`
+#### `batch_localize_objects(objects, target_locale:, source_locale:, reference: nil, concurrent: false)`
 
 Localizes multiple objects to the same target locale.
 
@@ -395,7 +384,7 @@ Returns information about the authenticated user.
 
 ### Class methods
 
-#### `Engine.quick_translate(content, api_key:, engine_id:, target_locale:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')`
+#### `Engine.quick_translate(content, api_key:, engine_id: nil, target_locale:, source_locale:, api_url: 'https://api.lingo.dev')`
 
 One-off translation without managing engine lifecycle.
 
@@ -404,7 +393,7 @@ One-off translation without managing engine lifecycle.
   - Other parameters as in instance methods
 - **Returns:** Translated String or Hash
 
-#### `Engine.quick_batch_translate(content, api_key:, engine_id:, target_locales:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')`
+#### `Engine.quick_batch_translate(content, api_key:, engine_id: nil, target_locales:, source_locale:, api_url: 'https://api.lingo.dev')`
 
 One-off batch translation to multiple locales.
 
@@ -420,7 +409,7 @@ The SDK defines custom exception classes for different error scenarios:
 
 ```ruby
 begin
-  engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id')
+  engine = LingoDotDev::Engine.new(api_key: 'your-api-key')
   result = engine.localize_text('Hello', target_locale: 'es', source_locale: 'en')
 rescue LingoDotDev::ValidationError => e
   # Invalid input or configuration

lib/lingodotdev.rb

@@ -54,7 +54,7 @@
 # localization with batch operations, progress tracking, and concurrent processing.
 #
 # @example Basic usage
-#   engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id')
+#   engine = LingoDotDev::Engine.new(api_key: 'your-api-key')
 #   result = engine.localize_text('Hello world', target_locale: 'es', source_locale: 'en')
 #   puts result # => "Hola mundo"
 #
@@ -88,7 +88,7 @@ class Configuration
     # @return [String] the API endpoint URL
     attr_accessor :api_url
 
-    # @return [String] the engine ID for localization processing
+    # @return [String, nil] the engine ID for localization processing
     attr_accessor :engine_id
 
     # @return [Integer] maximum number of items per batch (1-250)
@@ -100,13 +100,13 @@ class Configuration
     # Creates a new Configuration instance.
     #
     # @param api_key [String] your Lingo.dev API key (required)
-    # @param engine_id [String] the engine ID for localization processing (required)
+    # @param engine_id [String, nil] the engine ID for localization processing (optional)
     # @param api_url [String] the API endpoint URL (default: 'https://api.lingo.dev')
     # @param batch_size [Integer] maximum items per batch, 1-250 (default: 25)
     # @param ideal_batch_item_size [Integer] target word count per batch item, 1-2500 (default: 250)
     #
     # @raise [ValidationError] if any parameter is invalid
-    def initialize(api_key:, engine_id:, api_url: 'https://api.lingo.dev', batch_size: 25, ideal_batch_item_size: 250)
+    def initialize(api_key:, engine_id: nil, api_url: 'https://api.lingo.dev', batch_size: 25, ideal_batch_item_size: 250)
       @api_key = api_key
       @engine_id = engine_id
       @api_url = api_url
@@ -119,7 +119,6 @@ def initialize(api_key:, engine_id:, api_url: 'https://api.lingo.dev', batch_siz
 
     def validate!
       raise ValidationError, 'API key is required' if api_key.nil? || api_key.empty?
-      raise ValidationError, 'Engine ID is required' if engine_id.nil? || engine_id.empty?
       raise ValidationError, 'API URL must be a valid HTTP/HTTPS URL' unless api_url =~ /\Ahttps?:\/\/.+/
       raise ValidationError, 'Batch size must be between 1 and 250' unless batch_size.is_a?(Integer) && batch_size.between?(1, 250)
       raise ValidationError, 'Ideal batch item size must be between 1 and 2500' unless ideal_batch_item_size.is_a?(Integer) && ideal_batch_item_size.between?(1, 2500)
@@ -151,7 +150,7 @@ class Engine
     # Creates a new Engine instance.
     #
     # @param api_key [String] your Lingo.dev API key (required)
-    # @param engine_id [String] the engine ID for localization processing (required)
+    # @param engine_id [String, nil] the engine ID for localization processing (optional)
     # @param api_url [String] the API endpoint URL (default: 'https://api.lingo.dev')
     # @param batch_size [Integer] maximum items per batch, 1-250 (default: 25)
     # @param ideal_batch_item_size [Integer] target word count per batch item, 1-2500 (default: 250)
@@ -172,7 +171,7 @@ class Engine
     #     config.batch_size = 50
     #     config.ideal_batch_item_size = 500
     #   end
-    def initialize(api_key:, engine_id:, api_url: 'https://api.lingo.dev', batch_size: 25, ideal_batch_item_size: 250)
+    def initialize(api_key:, engine_id: nil, api_url: 'https://api.lingo.dev', batch_size: 25, ideal_batch_item_size: 250)
       @config = Configuration.new(
         api_key: api_key,
         engine_id: engine_id,
@@ -685,7 +684,7 @@ def whoami
     #
     # @param content [String, Hash] the content to translate (String for text, Hash for object)
     # @param api_key [String] your Lingo.dev API key
-    # @param engine_id [String] the engine ID for localization processing
+    # @param engine_id [String, nil] the engine ID for localization processing (optional)
     # @param target_locale [String] the target locale code (e.g., 'es', 'fr', 'ja')
     # @param source_locale [String] the source locale code (e.g., 'en')
     # @param fast [Boolean] enable fast mode for quicker results (default: true)
@@ -709,7 +708,7 @@ def whoami
     #     source_locale: 'en'
     #   )
     #   # => { greeting: "Bonjour", farewell: "Au revoir" }
-    def self.quick_translate(content, api_key:, engine_id:, target_locale:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')
+    def self.quick_translate(content, api_key:, engine_id: nil, target_locale:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')
       engine = new(api_key: api_key, engine_id: engine_id, api_url: api_url)
       case content
       when String
@@ -739,7 +738,7 @@ def self.quick_translate(content, api_key:, engine_id:, target_locale:, source_l
     #
     # @param content [String, Hash] the content to translate (String for text, Hash for object)
     # @param api_key [String] your Lingo.dev API key
-    # @param engine_id [String] the engine ID for localization processing
+    # @param engine_id [String, nil] the engine ID for localization processing (optional)
     # @param target_locales [Array<String>] array of target locale codes
     # @param source_locale [String] the source locale code (e.g., 'en')
     # @param fast [Boolean] enable fast mode for quicker results (default: true)
@@ -764,12 +763,11 @@ def self.quick_translate(content, api_key:, engine_id:, target_locale:, source_l
     #   results = LingoDotDev::Engine.quick_batch_translate(
     #     { greeting: 'Hello' },
     #     api_key: 'your-api-key',
-    #     engine_id: 'your-engine-id',
     #     target_locales: ['es', 'fr'],
     #     source_locale: 'en'
     #   )
     #   # => [{ greeting: "Hola" }, { greeting: "Bonjour" }]
-    def self.quick_batch_translate(content, api_key:, engine_id:, target_locales:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')
+    def self.quick_batch_translate(content, api_key:, engine_id: nil, target_locales:, source_locale:, fast: true, api_url: 'https://api.lingo.dev')
       engine = new(api_key: api_key, engine_id: engine_id, api_url: api_url)
       case content
       when String
@@ -865,6 +863,8 @@ def localize_chunk(chunk, target_locale:, source_locale:, fast:, reference:)
         sessionId: @session_id
       }
 
+      request_body[:engineId] = config.engine_id unless config.engine_id.nil?
+
       if reference && !reference.empty?
         raise ValidationError, 'Reference must be a Hash' unless reference.is_a?(Hash)
         request_body[:reference] = reference
@@ -874,7 +874,7 @@ def localize_chunk(chunk, target_locale:, source_locale:, fast:, reference:)
 
       begin
         response = make_request(
-          "#{config.api_url}/process/#{config.engine_id}/localize",
+          "#{config.api_url}/process/localize",
           json: request_body
         )