fix: correct reference parameter format in docs and tests

Author: AndreyHirsa

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lingodotdev (0.2.0)
+    lingodotdev (0.2.1)
       json (~> 2.0)
       nokogiri (~> 1.0)
 

README.md

@@ -210,13 +210,12 @@ result = engine.localize_text(
 
 ### Reference context
 
-Provide additional context to improve translation accuracy:
+Provide existing translations as reference to improve translation accuracy. The `reference` hash maps locale codes to key-value content objects:
 
 ```ruby
 reference = {
-  context: 'greeting',
-  tone: 'formal',
-  domain: 'business'
+  'es' => { 'greeting' => 'Hola', 'farewell' => 'Adiós' },
+  'fr' => { 'greeting' => 'Bonjour', 'farewell' => 'Au revoir' }
 }
 
 result = engine.localize_text(
@@ -314,7 +313,7 @@ Localizes a string to the target locale.
   - `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')
-  - `reference` (Hash, optional): Additional context for translation
+  - `reference` (Hash, optional): Existing translations keyed by locale code, e.g. `{ 'es' => { 'key' => 'valor' } }`
   - `on_progress` (Proc, optional): Progress callback
   - `concurrent` (Boolean): Enable concurrent processing
   - `&block`: Alternative progress callback
@@ -342,7 +341,7 @@ Localizes an HTML document while preserving structure and formatting. Handles bo
   - `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')
-  - `reference` (Hash, optional): Additional context for translation
+  - `reference` (Hash, optional): Existing translations keyed by locale code, e.g. `{ 'es' => { 'key' => 'valor' } }`
   - `on_progress` (Proc, optional): Progress callback
   - `concurrent` (Boolean): Enable concurrent processing
   - `&block`: Alternative progress callback

lib/lingodotdev.rb

@@ -190,7 +190,7 @@ def initialize(api_key:, engine_id: nil, api_url: 'https://api.lingo.dev', batch
     # @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, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param on_progress [Proc, nil] callback for progress updates (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
@@ -237,7 +237,7 @@ def localize_text(text, target_locale:, source_locale:, fast: nil, reference: ni
     # @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, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param on_progress [Proc, nil] callback for progress updates (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
@@ -283,7 +283,7 @@ def localize_object(obj, target_locale:, source_locale:, fast: nil, reference: n
     # @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, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param on_progress [Proc, nil] callback for progress updates (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
@@ -341,7 +341,7 @@ def localize_chat(chat, target_locale:, source_locale:, fast: nil, reference: ni
     # @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, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param on_progress [Proc, nil] callback for progress updates (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
@@ -514,7 +514,7 @@ def localize_html(html, target_locale:, source_locale:, fast: nil, reference: ni
     # @param target_locales [Array<String>] array of target locale codes
     # @param source_locale [String] the source locale code (e.g., 'en')
     # @param fast [Boolean, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
     # @return [Array<String>] array of localized strings in the same order as target_locales
@@ -565,7 +565,7 @@ def batch_localize_text(text, target_locales:, source_locale:, fast: nil, refere
     # @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, nil] enable fast mode for quicker results (optional)
-    # @param reference [Hash, nil] additional context for translation (optional)
+    # @param reference [Hash, nil] existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)
     # @param concurrent [Boolean] enable concurrent processing (default: false)
     #
     # @return [Array<Hash>] array of localized Hash objects in the same order as input

lib/lingodotdev/version.rb

@@ -3,6 +3,6 @@
 # Ruby SDK for Lingo.dev localization and translation API.
 module LingoDotDev
   # Current version of the LingoDotDev SDK.
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end
 

spec/lingo_dot_dev/engine_spec.rb

@@ -69,7 +69,7 @@
 
     it 'localizes text with reference context' do
       engine = described_class.new(api_key: api_key, engine_id: engine_id)
-      reference = { context: 'greeting' }
+      reference = { 'es' => { 'text' => 'Hola' } }
       result = engine.localize_text(
         'Hello',
         target_locale: target_locale,