Class: LingoDotDev::Engine

Inherits:
Object
  • Object
show all
Defined in:
lib/lingodotdev.rb

Overview

Main engine for localizing content via the Lingo.dev API.

The Engine class provides methods for text, object, and chat localization with support for batch operations, progress tracking, and concurrent processing.

Examples:

Basic text localization

engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id')
result = engine.localize_text('Hello', target_locale: 'es', source_locale: 'en')
# => "Hola"

Object localization

data = { greeting: 'Hello', farewell: 'Goodbye' }
result = engine.localize_object(data, target_locale: 'fr', source_locale: 'en')
# => { greeting: "Bonjour", farewell: "Au revoir" }

Batch localization

results = engine.batch_localize_text('Hello', target_locales: ['es', 'fr', 'de'], source_locale: 'en')
# => ["Hola", "Bonjour", "Hallo"]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, engine_id: nil, api_url: 'https://api.lingo.dev', batch_size: 25, ideal_batch_item_size: 250) {|config| ... } ⇒ Engine

Creates a new Engine instance.

Examples:

Basic initialization

engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id')

With custom configuration

engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id', batch_size: 50)

With block configuration

engine = LingoDotDev::Engine.new(api_key: 'your-api-key', engine_id: 'your-engine-id') do |config|
  config.batch_size = 50
  config.ideal_batch_item_size = 500
end

Parameters:

  • api_key (String) —

    your Lingo.dev API key (required)

  • engine_id (String, nil) (defaults to: nil) —

    the engine ID for localization processing (optional)

  • api_url (String) (defaults to: 'https://api.lingo.dev') —

    the API endpoint URL (default: 'https://api.lingo.dev')

  • batch_size (Integer) (defaults to: 25) —

    maximum items per batch, 1-250 (default: 25)

  • ideal_batch_item_size (Integer) (defaults to: 250) —

    target word count per batch item, 1-2500 (default: 250)

Yields:

  • (config) —

    optional block for additional configuration

Yield Parameters:

Raises:



174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/lingodotdev.rb', line 174

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,
    api_url: api_url,
    batch_size: batch_size,
    ideal_batch_item_size: ideal_batch_item_size
  )
  @session_id = SecureRandom.hex(16)
  yield @config if block_given?
  @config.send(:validate!)
end

Instance Attribute Details

#config ⇒ Configuration (readonly)

Returns the engine's configuration.

Returns:



148
149
150
 
# File 'lib/lingodotdev.rb', line 148

def config
  @config
end

Class Method Details

.quick_batch_translate(content, api_key:, engine_id: nil, target_locales:, source_locale:, fast: true, api_url: 'https://api.lingo.dev') ⇒ Array<String>, Array<Hash>

One-off batch translation to multiple locales without managing engine lifecycle.

Creates a temporary engine instance, performs batch translations, and returns the results. Suitable for single batch translations where engine configuration is not needed.

Examples:

Batch translate text

results = LingoDotDev::Engine.quick_batch_translate(
  'Hello',
  api_key: 'your-api-key',
  engine_id: 'your-engine-id',
  target_locales: ['es', 'fr', 'de'],
  source_locale: 'en'
)
# => ["Hola", "Bonjour", "Hallo"]

Batch translate object

results = LingoDotDev::Engine.quick_batch_translate(
  { greeting: 'Hello' },
  api_key: 'your-api-key',
  target_locales: ['es', 'fr'],
  source_locale: 'en'
)
# => [{ greeting: "Hola" }, { greeting: "Bonjour" }]

Parameters:

  • content (String, Hash) —

    the content to translate (String for text, Hash for object)

  • api_key (String) —

    your Lingo.dev API key

  • engine_id (String, nil) (defaults to: nil) —

    the engine ID for localization processing (optional)

  • target_locales (Array<String>) —

    array of target locale codes

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean) (defaults to: true) —

    enable fast mode for quicker results (default: true)

  • api_url (String) (defaults to: 'https://api.lingo.dev') —

    the API endpoint URL (default: 'https://api.lingo.dev')

Returns:

  • (Array<String>, Array<Hash>) —

    array of localized results (Strings if input was String, Hashes if input was Hash)

Raises:

  • (ValidationError) —

    if content is not a String or Hash, or other validation fails

  • (APIError) —

    if any API request fails



770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
 
# File 'lib/lingodotdev.rb', line 770

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
    engine.batch_localize_text(
      content,
      target_locales: target_locales,
      source_locale: source_locale,
      fast: fast,
      concurrent: true
    )
  when Hash
    target_locales.map do |target_locale|
      engine.localize_object(
        content,
        target_locale: target_locale,
        source_locale: source_locale,
        fast: fast,
        concurrent: true
      )
    end
  else
    raise ValidationError, 'Content must be a String or Hash'
  end
end

.quick_translate(content, api_key:, engine_id: nil, target_locale:, source_locale:, fast: true, api_url: 'https://api.lingo.dev') ⇒ String, Hash

One-off translation without managing engine lifecycle.

Creates a temporary engine instance, performs the translation, and returns the result. Suitable for single translations where engine configuration is not needed.

Examples:

Translate text

result = LingoDotDev::Engine.quick_translate('Hello', api_key: 'your-api-key', engine_id: 'your-engine-id', target_locale: 'es', source_locale: 'en')
# => "Hola"

Translate object

result = LingoDotDev::Engine.quick_translate(
  { greeting: 'Hello', farewell: 'Goodbye' },
  api_key: 'your-api-key',
  engine_id: 'your-engine-id',
  target_locale: 'fr',
  source_locale: 'en'
)
# => { greeting: "Bonjour", farewell: "Au revoir" }

Parameters:

  • content (String, Hash) —

    the content to translate (String for text, Hash for object)

  • api_key (String) —

    your Lingo.dev API key

  • engine_id (String, nil) (defaults to: nil) —

    the engine ID for localization processing (optional)

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean) (defaults to: true) —

    enable fast mode for quicker results (default: true)

  • api_url (String) (defaults to: 'https://api.lingo.dev') —

    the API endpoint URL (default: 'https://api.lingo.dev')

Returns:

  • (String, Hash) —

    localized content (String if input was String, Hash if input was Hash)

Raises:

  • (ValidationError) —

    if content is not a String or Hash, or other validation fails

  • (APIError) —

    if the API request fails



711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
 
# File 'lib/lingodotdev.rb', line 711

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
    engine.localize_text(
      content,
      target_locale: target_locale,
      source_locale: source_locale,
      fast: fast
    )
  when Hash
    engine.localize_object(
      content,
      target_locale: target_locale,
      source_locale: source_locale,
      fast: fast,
      concurrent: true
    )
  else
    raise ValidationError, 'Content must be a String or Hash'
  end
end

Instance Method Details

#batch_localize_objects(objects, target_locale:, source_locale:, fast: nil, reference: nil, concurrent: false) ⇒ Array<Hash>

Localizes multiple objects to the same target locale.

Examples:

Basic usage

objects = [
  { title: 'Welcome', body: 'Hello there' },
  { title: 'About', body: 'Learn more' }
]
results = engine.batch_localize_objects(objects, target_locale: 'es', source_locale: 'en')
# => [
#   { title: "Bienvenido", body: "Hola" },
#   { title: "Acerca de", body: "Aprende más" }
# ]

Parameters:

  • objects (Array<Hash>) —

    array of Hash objects to localize

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Returns:

  • (Array<Hash>) —

    array of localized Hash objects in the same order as input

Raises:

  • (ValidationError) —

    if objects is not an Array, objects is empty, target_locale is missing, or any object is not a Hash

  • (APIError) —

    if any API request fails



586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
 
# File 'lib/lingodotdev.rb', line 586

def batch_localize_objects(objects, target_locale:, source_locale:, fast: nil, reference: nil, concurrent: false)
  raise ValidationError, 'Objects must be an Array' unless objects.is_a?(Array)
  raise ValidationError, 'Objects cannot be empty' if objects.empty?
  raise ValidationError, 'Target locale is required' if target_locale.nil? || target_locale.empty?

  objects.each do |obj|
    raise ValidationError, 'Each object must be a Hash' unless obj.is_a?(Hash)
  end

  if concurrent
    threads = objects.map do |obj|
      Thread.new do
        localize_object(
          obj,
          target_locale: target_locale,
          source_locale: source_locale,
          fast: fast,
          reference: reference,
          concurrent: true
        )
      end
    end
    threads.map(&:value)
  else
    objects.map do |obj|
      localize_object(
        obj,
        target_locale: target_locale,
        source_locale: source_locale,
        fast: fast,
        reference: reference,
        concurrent: concurrent
      )
    end
  end
end

#batch_localize_text(text, target_locales:, source_locale:, fast: nil, reference: nil, concurrent: false) ⇒ Array<String>

Localizes text to multiple target locales.

Examples:

Basic usage

results = engine.batch_localize_text('Hello', target_locales: ['es', 'fr', 'de'], source_locale: 'en')
# => ["Hola", "Bonjour", "Hallo"]

With concurrent processing

results = engine.batch_localize_text('Hello', target_locales: ['es', 'fr', 'de', 'ja'], source_locale: 'en', concurrent: true)

Parameters:

  • text (String) —

    the text to localize

  • target_locales (Array<String>) —

    array of target locale codes

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Returns:

  • (Array<String>) —

    array of localized strings in the same order as target_locales

Raises:

  • (ValidationError) —

    if text is nil, target_locales is not an Array, or target_locales is empty

  • (APIError) —

    if any API request fails



531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
 
# File 'lib/lingodotdev.rb', line 531

def batch_localize_text(text, target_locales:, source_locale:, fast: nil, reference: nil, concurrent: false)
  raise ValidationError, 'Text cannot be nil' if text.nil?
  raise ValidationError, 'Target locales must be an Array' unless target_locales.is_a?(Array)
  raise ValidationError, 'Target locales cannot be empty' if target_locales.empty?

  if concurrent
    threads = target_locales.map do |target_locale|
      Thread.new do
        localize_text(
          text,
          target_locale: target_locale,
          source_locale: source_locale,
          fast: fast,
          reference: reference
        )
      end
    end
    threads.map(&:value)
  else
    target_locales.map do |target_locale|
      localize_text(
        text,
        target_locale: target_locale,
        source_locale: source_locale,
        fast: fast,
        reference: reference
      )
    end
  end
end

#localize_chat(chat, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false) {|progress| ... } ⇒ Array<Hash>

Localizes chat messages while preserving structure.

Each message must have :name and :text keys. The structure of messages is preserved while all text content is localized.

Examples:

Basic usage

chat = [
  { name: 'user', text: 'Hello!' },
  { name: 'assistant', text: 'Hi there!' }
]
result = engine.localize_chat(chat, target_locale: 'ja', source_locale: 'en')
# => [
#   { name: 'user', text: 'こんにちは！' },
#   { name: 'assistant', text: 'こんにちは！' }
# ]

Parameters:

  • chat (Array<Hash>) —

    array of chat messages, each with :name and :text keys

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • on_progress (Proc, nil) (defaults to: nil) —

    callback for progress updates (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Yields:

  • (progress) —

    optional block for progress tracking

Yield Parameters:

  • progress (Integer) —

    completion percentage (0-100)

Returns:

  • (Array<Hash>) —

    array of localized chat messages

Raises:

  • (ValidationError) —

    if target_locale is missing, chat is nil, not an Array, or messages are invalid

  • (APIError) —

    if the API request fails



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/lingodotdev.rb', line 308

def localize_chat(chat, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)
  raise ValidationError, 'Target locale is required' if target_locale.nil? || target_locale.empty?
  raise ValidationError, 'Chat cannot be nil' if chat.nil?
  raise ValidationError, 'Chat must be an Array' unless chat.is_a?(Array)

  chat.each do |message|
    unless message.is_a?(Hash) && message[:name] && message[:text]
      raise ValidationError, 'Each chat message must have :name and :text keys'
    end
  end

  callback = block || on_progress

  response = localize_raw(
    { chat: chat },
    target_locale: target_locale,
    source_locale: source_locale,
    fast: fast,
    reference: reference,
    concurrent: concurrent
  ) do |progress, chunk, processed_chunk|
    callback&.call(progress)
  end

  raise APIError, 'API did not return localized chat' unless response.key?('chat')
  response['chat']
end

#localize_html(html, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false) {|progress| ... } ⇒ String

Localizes an HTML document while preserving structure and formatting.

Handles both text content and localizable attributes (alt, title, placeholder, meta content).

Examples:

Basic usage

html = '<html><head><title>Hello</title></head><body><p>World</p></body></html>'
result = engine.localize_html(html, target_locale: 'es', source_locale: 'en')
# => "<html lang=\"es\">..."

Parameters:

  • html (String) —

    the HTML document string to be localized

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • on_progress (Proc, nil) (defaults to: nil) —

    callback for progress updates (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Yields:

  • (progress) —

    optional block for progress tracking

Yield Parameters:

  • progress (Integer) —

    completion percentage (0-100)

Returns:

  • (String) —

    the localized HTML document as a string, with updated lang attribute

Raises:



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
 
# File 'lib/lingodotdev.rb', line 360

def localize_html(html, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)
  raise ValidationError, 'Target locale is required' if target_locale.nil? || target_locale.empty?
  raise ValidationError, 'HTML cannot be nil' if html.nil?

  callback = block || on_progress

  doc = Nokogiri::HTML::Document.parse(html)

  localizable_attributes = {
    'meta' => ['content'],
    'img' => ['alt'],
    'input' => ['placeholder'],
    'a' => ['title']
  }

  unlocalizable_tags = ['script', 'style']

  extracted_content = {}

  get_path = lambda do |node, attribute = nil|
    indices = []
    current = node
    root_parent = nil

    while current
      parent = current.parent
      break unless parent

      if parent == doc.root
        root_parent = current.name.downcase if current.element?
        break
      end

      siblings = parent.children.select do |n|
        (n.element? || (n.text? && n.text.strip != ''))
      end

      index = siblings.index(current)
      if index
        indices.unshift(index)
      end

      current = parent
    end

    base_path = root_parent ? "#{root_parent}/#{indices.join('/')}" : indices.join('/')
    attribute ? "#{base_path}##{attribute}" : base_path
  end

  process_node = lambda do |node|
    parent = node.parent
    while parent && !parent.is_a?(Nokogiri::XML::Document)
      if parent.element? && unlocalizable_tags.include?(parent.name.downcase)
        return
      end
      parent = parent.parent
    end

    if node.text?
      text = node.text.strip
      if text != ''
        extracted_content[get_path.call(node)] = text
      end
    elsif node.element?
      element = node
      tag_name = element.name.downcase
      attributes = localizable_attributes[tag_name] || []
      attributes.each do |attr|
        value = element[attr]
        if value && value.strip != ''
          extracted_content[get_path.call(element, attr)] = value
        end
      end

      element.children.each do |child|
        process_node.call(child)
      end
    end
  end

  head = doc.at_css('head')
  if head
    head.children.select do |n|
      n.element? || (n.text? && n.text.strip != '')
    end.each do |child|
      process_node.call(child)
    end
  end

  body = doc.at_css('body')
  if body
    body.children.select do |n|
      n.element? || (n.text? && n.text.strip != '')
    end.each do |child|
      process_node.call(child)
    end
  end

  localized_content = localize_raw(
    extracted_content,
    target_locale: target_locale,
    source_locale: source_locale,
    fast: fast,
    reference: reference,
    concurrent: concurrent
  ) do |progress, chunk, processed_chunk|
    callback&.call(progress)
  end

  doc.root['lang'] = target_locale if doc.root

  localized_content.each do |path, value|
    node_path, attribute = path.split('#')
    parts = node_path.split('/')
    root_tag = parts[0]
    indices = parts[1..-1]

    parent = root_tag == 'head' ? doc.at_css('head') : doc.at_css('body')
    next unless parent
    current = parent

    indices.each do |index_str|
      index = index_str.to_i
      siblings = parent.children.select do |n|
        (n.element? || (n.text? && n.text.strip != ''))
      end

      current = siblings[index]
      break unless current

      if current.element?
        parent = current
      end
    end

    if current
      if attribute
        if current.element?
          current[attribute] = value
        end
      else
        if current.text?
          current.content = value
        end
      end
    end
  end

  doc.to_html
end

#localize_object(obj, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false) {|progress| ... } ⇒ Hash

Localizes all string values in a Hash.

Examples:

Basic usage

data = { greeting: 'Hello', farewell: 'Goodbye' }
result = engine.localize_object(data, target_locale: 'es', source_locale: 'en')
# => { greeting: "Hola", farewell: "Adiós" }

Parameters:

  • obj (Hash) —

    the Hash object to localize

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • on_progress (Proc, nil) (defaults to: nil) —

    callback for progress updates (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Yields:

  • (progress) —

    optional block for progress tracking

Yield Parameters:

  • progress (Integer) —

    completion percentage (0-100)

Returns:

  • (Hash) —

    a new Hash with localized string values

Raises:

  • (ValidationError) —

    if target_locale is missing, obj is nil, or obj is not a Hash

  • (APIError) —

    if the API request fails



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/lingodotdev.rb', line 256

def localize_object(obj, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)
  raise ValidationError, 'Target locale is required' if target_locale.nil? || target_locale.empty?
  raise ValidationError, 'Object cannot be nil' if obj.nil?
  raise ValidationError, 'Object must be a Hash' unless obj.is_a?(Hash)

  callback = block || on_progress

  response = localize_raw(
    obj,
    target_locale: target_locale,
    source_locale: source_locale,
    fast: fast,
    reference: reference,
    concurrent: concurrent,
    &callback
  )

  raise APIError, 'API returned empty localization response' if response.empty?
  response
end

#localize_text(text, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false) {|progress| ... } ⇒ String

Localizes a string to the target locale.

Examples:

Basic usage

result = engine.localize_text('Hello', target_locale: 'es', source_locale: 'en')
# => "Hola"

With progress tracking

result = engine.localize_text('Hello', target_locale: 'de', source_locale: 'en') do |progress|
  puts "Progress: #{progress}%"
end

Parameters:

  • text (String) —

    the text to localize

  • target_locale (String) —

    the target locale code (e.g., 'es', 'fr', 'ja')

  • source_locale (String) —

    the source locale code (e.g., 'en')

  • fast (Boolean, nil) (defaults to: nil) —

    enable fast mode for quicker results (optional)

  • reference (Hash, nil) (defaults to: nil) —

    existing translations keyed by locale code, e.g. { 'es' => { 'key' => 'valor' } } (optional)

  • on_progress (Proc, nil) (defaults to: nil) —

    callback for progress updates (optional)

  • concurrent (Boolean) (defaults to: false) —

    enable concurrent processing (default: false)

Yields:

  • (progress) —

    optional block for progress tracking

Yield Parameters:

  • progress (Integer) —

    completion percentage (0-100)

Returns:

  • (String) —

    the localized text

Raises:



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/lingodotdev.rb', line 213

def localize_text(text, target_locale:, source_locale:, fast: nil, reference: nil, on_progress: nil, concurrent: false, &block)
  raise ValidationError, 'Target locale is required' if target_locale.nil? || target_locale.empty?
  raise ValidationError, 'Text cannot be nil' if text.nil?

  callback = block || on_progress

  response = localize_raw(
    { text: text },
    target_locale: target_locale,
    source_locale: source_locale,
    fast: fast,
    reference: reference,
    concurrent: concurrent
  ) do |progress, chunk, processed_chunk|
    callback&.call(progress)
  end

  raise APIError, 'API did not return localized text' unless response.key?('text')
  response['text']
end

#recognize_locale(text) ⇒ String

Detects the locale of the given text.

Examples:

Basic usage

locale = engine.recognize_locale('Bonjour le monde')
# => "fr"

Japanese text

locale = engine.recognize_locale('こんにちは世界')
# => "ja"

Parameters:

  • text (String) —

    the text to analyze

Returns:

  • (String) —

    the detected locale code (e.g., 'en', 'es', 'ja')

Raises:



639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/lingodotdev.rb', line 639

def recognize_locale(text)
  raise ValidationError, 'Text cannot be empty' if text.nil? || text.strip.empty?

  begin
    response = make_request(
      "#{config.api_url}/process/recognize",
      json: { text: text }
    )

    handle_response(response)
    data = JSON.parse(response.body, symbolize_names: true)
    data[:locale] || ''
  rescue StandardError => e
    raise APIError, "Request failed: #{e.message}"
  end
end

#whoami ⇒ Hash?

Returns information about the authenticated user.

Examples:

Basic usage

user = engine.whoami
# => { email: "[email protected]", id: "user-id" }

Returns:

  • (Hash, nil) —

    a Hash with :email and :id keys if authenticated, nil otherwise



663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
 
# File 'lib/lingodotdev.rb', line 663

def whoami
  begin
    response = make_request("#{config.api_url}/users/me", method: :get)

    status_code = response.code.to_i
    return nil unless status_code >= 200 && status_code < 300

    data = JSON.parse(response.body, symbolize_names: true)
    return nil unless data[:email]

    { email: data[:email], id: data[:id] }
  rescue StandardError => e
    raise APIError, "Request failed: #{e.message}" if e.message.include?('Server error')
    nil
  end
end