actiontext_translate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0de2c393d8b1ce42d10f5f3de9da605d055f3eacfa71a0a38338d3a8ef588b40
+  data.tar.gz: bd701532905304c0e8d23fd93e77a42e77781d0f0225d19644807d1793bff420
+SHA512:
+  metadata.gz: 2a32f00eeb6517cda823e6facb7cfcc8e21672b562ad79dc58bed7828501263e2b680bddf7efc77dde0652464e3bf2130d8eca4c82a9dace71fbe6be94c435bc
+  data.tar.gz: 8fda68dee1d2f4884f718f10f0a0ca24f8003b2da9375706dd0ed9d7cafd8ecfcd37456d9c5dc580d27ce10cb17c41ca104e993abecfcdd2f55a66a4868f76f5

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project 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.1.0] - 2024-12-18
+
+### Added
+- Initial release
+- ChatGPT (OpenAI) translator with HTML preservation
+- Link protection to prevent URL corruption during translation
+- ActionText rich text support
+- HTML tag preservation
+- Extensible translator interface for multiple providers
+- Configuration system
+- Comprehensive test suite

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mykyta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,333 @@
+# ActionText Translate
+
+A Ruby gem for translating ActionText rich text content using ChatGPT (OpenAI) while perfectly preserving HTML structure, tags, and links.
+
+## Features
+
+- **High-Quality Translation**: Uses ChatGPT for natural, contextual translations
+- **HTML Preservation**: Maintains all HTML tags, attributes, and structure
+- **Smart Link Protection**: Prevents URL corruption during translation
+- **ActionText Support**: Seamless integration with Rails ActionText
+- **Extensible Architecture**: Easy to add additional translation providers
+- **Well Tested**: Comprehensive test suite with 33+ test cases
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'actiontext_translate'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install actiontext_translate
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+ActiontextTranslate.configure do |config|
+  config.provider = :chatgpt
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.model = 'gpt-4o-mini'      # Fast and cost-effective
+  config.temperature = 0.3          # Lower temperature for consistent translations
+  config.timeout = 30               # API timeout in seconds
+end
+```
+
+### Rails Configuration
+
+Create an initializer `config/initializers/actiontext_translate.rb`:
+
+```ruby
+# config/initializers/actiontext_translate.rb
+ActiontextTranslate.configure do |config|
+  config.provider = :chatgpt
+  config.api_key = ENV['OPENAI_API_KEY']
+  config.model = 'gpt-4o-mini'
+  config.temperature = 0.3
+end
+```
+
+### Get Your OpenAI API Key
+
+1. Visit https://platform.openai.com/api-keys
+2. Create a new API key
+3. Add it to your environment variables
+
+## Usage
+
+### Simple Text Translation
+
+```ruby
+# Basic translation
+ActiontextTranslate.translate("Привіт Світ", from: "uk", to: "en")
+# => "Hello World"
+
+# With custom translator instance
+translator = ActiontextTranslate::Translator.new
+translator.translate("Bonjour le monde", from: "fr", to: "en")
+# => "Hello world"
+```
+
+### HTML Translation
+
+```ruby
+html = '<p>Check <a href="https://example.com">this link</a> for more info.</p>'
+
+result = ActiontextTranslate.translate_html(html, from: "uk", to: "en")
+# => '<p>Check <a href="https://example.com">this link</a> for more info.</p>'
+# All HTML structure and link attributes are perfectly preserved!
+```
+
+### ActionText Translation
+
+```ruby
+# Translate ActionText rich text content
+article = Article.find(1)
+translated_html = ActiontextTranslate.translate_action_text(
+  article.body,
+  from: "uk",
+  to: "en"
+)
+
+# Set the translated content
+article.body_en = translated_html
+article.save
+```
+
+## Rails Integration
+
+### Background Job Example
+
+```ruby
+# app/jobs/translate_content_job.rb
+class TranslateContentJob < ApplicationJob
+  queue_as :default
+
+  def perform(model_class, model_id, from_locale, to_locale)
+    model = model_class.constantize.find_by(id: model_id)
+    return unless model
+
+    translator = ActiontextTranslate::Translator.new
+
+    # Translate ActionText body field
+    if model.respond_to?(:body) && model.body.present?
+      translated_html = translator.translate_action_text(
+        model.body,
+        from: from_locale,
+        to: to_locale
+      )
+      model.public_send("body_#{to_locale}=", translated_html)
+    end
+
+    # Translate regular text fields
+    if model.respond_to?(:title) && model.title.present?
+      translated_title = translator.translate(
+        model.title,
+        from: from_locale,
+        to: to_locale
+      )
+      model.public_send("title_#{to_locale}=", translated_title)
+    end
+
+    model.save!
+  rescue ActiontextTranslate::Translators::TranslationError => e
+    Rails.logger.error("Translation failed: #{e.message}")
+    raise
+  end
+end
+```
+
+### Rake Task Example
+
+```ruby
+# lib/tasks/translations.rake
+namespace :translations do
+  desc 'Translate content from Ukrainian to English'
+  task translate_articles: :environment do
+    Article.where(translated: false).find_each do |article|
+      puts "Translating Article ##{article.id}..."
+      TranslateContentJob.perform_later('Article', article.id, 'uk', 'en')
+    end
+  end
+end
+```
+
+### Model Integration
+
+```ruby
+# app/models/article.rb
+class Article < ApplicationRecord
+  has_rich_text :body
+  has_rich_text :body_en
+
+  after_create :enqueue_translation
+
+  private
+
+  def enqueue_translation
+    TranslateContentJob.perform_later(self.class.name, id, 'uk', 'en')
+  end
+end
+```
+
+## Advanced Features
+
+### Link Protection
+
+The gem automatically protects links during translation:
+
+```ruby
+html = '<p>Visit <a href="https://example.com">our website</a> or <a href="https://docs.com">https://docs.com</a></p>'
+
+result = ActiontextTranslate.translate_html(html, from: "uk", to: "en")
+# - Links with descriptive text: text gets translated, URL preserved
+# - Links where text = URL: kept unchanged
+# - All attributes (href, rel, target, class) are preserved
+```
+
+### HTML Structure Preservation
+
+```ruby
+html = <<~HTML
+  <div class="content">
+    <h1>Title</h1>
+    <p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
+    <ul>
+      <li>Item 1</li>
+      <li>Item 2</li>
+    </ul>
+  </div>
+HTML
+
+result = ActiontextTranslate.translate_html(html, from: "uk", to: "en")
+# All tags, classes, and structure are perfectly preserved
+```
+
+### Error Handling
+
+```ruby
+begin
+  translator = ActiontextTranslate::Translator.new
+  result = translator.translate("Text", from: "uk", to: "en")
+rescue ActiontextTranslate::Translators::TranslationError => e
+  Rails.logger.error("Translation failed: #{e.message}")
+  # Handle error (retry, fallback, notify, etc.)
+end
+```
+
+## Supported Languages
+
+The gem supports **all languages** supported by OpenAI's GPT models. Simply use the appropriate language code:
+
+```ruby
+# Ukrainian to English
+ActiontextTranslate.translate("Привіт", from: "uk", to: "en")
+
+# French to German
+ActiontextTranslate.translate("Bonjour", from: "fr", to: "de")
+
+# Any language combination
+ActiontextTranslate.translate(text, from: "source_lang", to: "target_lang")
+```
+
+## Cost Considerations
+
+Using ChatGPT (GPT-4o-mini) is very cost-effective:
+
+- **Input**: ~$0.15 per 1M tokens
+- **Output**: ~$0.60 per 1M tokens
+- **Average translation**: A typical blog post (1000 words) costs < $0.01
+
+Example monthly costs for 1000 translations:
+- ~$5-10/month for typical usage
+- Pay only for what you use
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `provider` | `:chatgpt` | Translation provider |
+| `api_key` | `nil` | OpenAI API key (required) |
+| `model` | `'gpt-4o-mini'` | OpenAI model to use |
+| `temperature` | `0.3` | Response randomness (0.0-2.0) |
+| `timeout` | `30` | API request timeout in seconds |
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Check code coverage (requires 90% minimum):
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+### Code Coverage
+
+The gem maintains **96%+ code coverage** with comprehensive tests:
+- 48 test cases covering all major features
+- Integration tests with realistic Trix/ActionText content
+- Edge case coverage for HTML preservation
+- Minimum coverage threshold: 90%
+
+View coverage report after running tests:
+```bash
+open coverage/index.html
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mykbren/actiontext_translate.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Roadmap
+
+Future enhancements planned:
+
+- [ ] Additional translation providers (Google Translate, DeepL, Azure)
+- [ ] Batch translation support for improved performance
+- [ ] Translation memory/caching to reduce costs
+- [ ] Automatic language detection
+- [ ] Rails generators for easy setup
+- [ ] Translation quality scoring
+- [ ] Custom prompt templates
+- [ ] Streaming support for large documents
+
+## Support
+
+For questions, issues, or feature requests:
+- Open an issue on GitHub
+- Review the test suite for examples
+- Check the documentation

data/lib/actiontext_translate/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiontextTranslate
+  class Configuration
+    attr_accessor :provider, :api_key, :timeout, :model, :temperature
+
+    def initialize
+      @provider = :chatgpt
+      @api_key = nil
+      @timeout = 30
+      @model = 'gpt-4o-mini' # Fast and cost-effective for translations
+      @temperature = 0.3 # Lower temperature for more consistent translations
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/actiontext_translate/html_processor.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'uri'
+require 'cgi'
+
+module ActiontextTranslate
+  # Handles HTML processing for translation, including link protection
+  class HtmlProcessor
+    # Protect links by replacing them with simple placeholders
+    # @param html [String] The HTML content to process
+    # @return [Array<String, Hash>] Protected HTML and link map
+    def self.protect_links(html)
+      doc = Nokogiri::HTML.fragment(html)
+      link_map = {}
+      counter = 0
+
+      doc.css('a').each do |link|
+        counter += 1
+        start_placeholder = "XLINKSTARTX#{counter}X"
+        end_placeholder = "XLINKENDX#{counter}X"
+
+        text = link.text.strip
+        href = link['href'].to_s
+
+        # Determine if link is translatable
+        # Links are not translatable if:
+        # 1. Text exactly matches URL
+        # 2. Text contains any URL (to avoid translator breaking URLs)
+        uri_regex = URI::DEFAULT_PARSER.make_regexp(%w[http https])
+        translatable = !(text == href || text.match?(uri_regex))
+
+        link_map[start_placeholder] = {
+          end_placeholder: end_placeholder,
+          attributes: link.attributes.transform_values(&:value),
+          text: text,
+          translatable: translatable
+        }
+
+        # Replace link with placeholders
+        protected_text = translatable ? text : ''
+        link.replace("#{start_placeholder}#{protected_text}#{end_placeholder}")
+      end
+
+      [doc.to_html, link_map]
+    end
+
+    # Restore links after translation
+    # @param html [String] The translated HTML with placeholders
+    # @param link_map [Hash] The link map from protect_links
+    # @return [String] HTML with restored links
+    def self.restore_links(html, link_map)
+      html = html.dup
+
+      link_map.each do |start_placeholder, data|
+        end_placeholder = data[:end_placeholder]
+
+        # Extract the inner text
+        inner_text = html[/#{Regexp.escape(start_placeholder)}(.*?)#{Regexp.escape(end_placeholder)}/m, 1].to_s.strip
+
+        # Use original text for non-translatable links
+        inner_text = data[:text] unless data[:translatable]
+
+        # Rebuild <a> tag with exact attributes
+        attrs = data[:attributes].map { |k, v| %(#{k}="#{CGI.escapeHTML(v)}") }.join(' ')
+        link_html = "<a #{attrs}>#{inner_text}</a>"
+
+        html.gsub!(/#{Regexp.escape(start_placeholder)}.*?#{Regexp.escape(end_placeholder)}/m, link_html)
+      end
+
+      html
+    end
+
+    # Protect ActionText attachments (images with captions) by replacing with placeholders
+    # @param html [String] The HTML content to process
+    # @return [Array<String, Hash>] Protected HTML and attachment map
+    def self.protect_attachments(html)
+      doc = Nokogiri::HTML.fragment(html)
+      attachment_map = {}
+      counter = 0
+
+      doc.css('action-text-attachment').each do |attachment|
+        counter += 1
+        start_placeholder = "XATTACHSTARTX#{counter}X"
+        end_placeholder = "XATTACHENDX#{counter}X"
+
+        # Extract all attributes
+        attributes = attachment.attributes.transform_values(&:value)
+
+        # Get inner HTML
+        inner_html = attachment.inner_html
+
+        # Check if there's translatable content (figcaption, img alt)
+        inner_doc = Nokogiri::HTML.fragment(inner_html)
+        figcaption = inner_doc.at_css('figcaption')
+        img = inner_doc.at_css('img')
+
+        caption_text = figcaption&.text&.strip
+        has_translatable_content = caption_text&.length.to_i.positive?
+        translatable_alt = img&.[]('alt')&.strip
+
+        # Keep alt text as-is in inner_html for translation
+        # We'll extract the translated alt text after translation
+
+        # Store attachment data
+        attachment_map[start_placeholder] = {
+          end_placeholder: end_placeholder,
+          tag_name: 'action-text-attachment',
+          attributes: attributes,
+          inner_html: inner_html,
+          translatable_alt: translatable_alt,
+          has_translatable_content: has_translatable_content
+        }
+
+        # Replace attachment with placeholder + inner content (so captions get translated)
+        attachment.replace("#{start_placeholder}#{inner_html}#{end_placeholder}")
+      end
+
+      [doc.to_html, attachment_map]
+    end
+
+    # Restore ActionText attachments after translation
+    # @param html [String] The translated HTML with placeholders
+    # @param attachment_map [Hash] The attachment map from protect_attachments
+    # @return [String] HTML with restored attachments
+    def self.restore_attachments(html, attachment_map)
+      html = html.dup
+
+      attachment_map.each do |start_placeholder, data|
+        end_placeholder = data[:end_placeholder]
+
+        # Extract the translated inner HTML
+        inner_html = html[/#{Regexp.escape(start_placeholder)}(.*?)#{Regexp.escape(end_placeholder)}/m, 1].to_s
+
+        # Alt text was kept in the HTML and should have been translated naturally
+        # No additional processing needed for alt text
+
+        # Rebuild action-text-attachment tag
+        attrs = data[:attributes].map { |k, v| %(#{k}="#{CGI.escapeHTML(v)}") }.join(' ')
+        attachment_html = "<#{data[:tag_name]} #{attrs}>#{inner_html}</#{data[:tag_name]}>"
+
+        # Replace placeholder with full attachment
+        html.gsub!(/#{Regexp.escape(start_placeholder)}.*?#{Regexp.escape(end_placeholder)}/m, attachment_html)
+      end
+
+      html
+    end
+
+    # Sanitize HTML by removing potentially problematic elements
+    # @param html [String] The HTML content
+    # @return [String] Sanitized HTML
+    def self.sanitize_for_translation(html)
+      # Remove script and style tags
+      doc = Nokogiri::HTML.fragment(html)
+      doc.css('script, style').remove
+      doc.to_html
+    end
+  end
+end

data/lib/actiontext_translate/translator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActiontextTranslate
+  # Main translator class that delegates to provider-specific translators
+  class Translator
+    attr_reader :provider
+
+    def initialize(provider = nil)
+      @provider = create_provider(provider || ActiontextTranslate.configuration.provider)
+    end
+
+    # Translate text
+    # @param text [String] Text to translate
+    # @param from [String] Source language code
+    # @param to [String] Target language code
+    # @param html_mode [Boolean] Whether to preserve HTML tags
+    # @return [String] Translated text
+    def translate(text, from:, to:, html_mode: false)
+      provider.translate(text, from: from, to: to, html_mode: html_mode)
+    end
+
+    # Translate HTML content with full link and tag preservation
+    # @param html [String] HTML content to translate
+    # @param from [String] Source language code
+    # @param to [String] Target language code
+    # @return [String] Translated HTML
+    def translate_html(html, from:, to:)
+      provider.translate_html(html, from: from, to: to)
+    end
+
+    # Translate ActionText rich text content
+    # @param rich_text [ActionText::RichText, String] Rich text to translate
+    # @param from [String] Source language code
+    # @param to [String] Target language code
+    # @return [String] Translated HTML suitable for ActionText
+    def translate_action_text(rich_text, from:, to:)
+      html = extract_html_from_rich_text(rich_text)
+      translate_html(html, from: from, to: to)
+    end
+
+    private
+
+    def create_provider(provider_name)
+      case provider_name.to_sym
+      when :chatgpt, :openai
+        require_relative 'translators/chatgpt'
+        Translators::Chatgpt.new
+      else
+        raise ArgumentError, "Unknown translation provider: #{provider_name}"
+      end
+    end
+
+    def extract_html_from_rich_text(rich_text)
+      if rich_text.respond_to?(:body)
+        rich_text.body.to_s
+      else
+        rich_text.to_s
+      end
+    end
+  end
+end

data/lib/actiontext_translate/translators/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiontextTranslate
+  module Translators
+    # Base translator interface
+    class Base
+      attr_reader :config
+
+      def initialize(config = nil)
+        @config = config || ActiontextTranslate.configuration
+      end
+
+      # Translate text from source language to target language
+      # @param text [String] The text to translate
+      # @param from [String] Source language code (e.g., 'uk', 'en')
+      # @param to [String] Target language code (e.g., 'en', 'uk')
+      # @param html_mode [Boolean] Whether to preserve HTML tags
+      # @return [String] Translated text
+      def translate(text, from:, to:, html_mode: false)
+        raise NotImplementedError, "#{self.class} must implement #translate"
+      end
+
+      # Translate with HTML preservation using the HTML processor
+      # @param html [String] The HTML content to translate
+      # @param from [String] Source language code
+      # @param to [String] Target language code
+      # @return [String] Translated HTML with preserved structure
+      def translate_html(html, from:, to:)
+        return html if blank?(html)
+
+        # Protect ActionText attachments first (images with captions)
+        protected_html, attachment_map = HtmlProcessor.protect_attachments(html)
+
+        # Protect links (in the exposed inner HTML of attachments)
+        protected_html, link_map = HtmlProcessor.protect_links(protected_html)
+
+        # Translate
+        translated_html = translate(protected_html, from: from, to: to, html_mode: true)
+
+        # Restore in reverse order: links first, then attachments
+        translated_html = HtmlProcessor.restore_links(translated_html, link_map)
+        HtmlProcessor.restore_attachments(translated_html, attachment_map)
+      end
+
+      # Check if value is blank (nil, empty, or whitespace)
+      # @param value [Object] Value to check
+      # @return [Boolean]
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) || (value.is_a?(String) && value.strip.empty?)
+      end
+
+      protected
+
+      # Normalize language code to a standard format
+      # @param code [String, Symbol] Language code
+      # @return [String] Normalized language code
+      def normalize_language_code(code)
+        code.to_s.downcase.split(/[-_]/).first
+      end
+    end
+  end
+end

data/lib/actiontext_translate/translators/chatgpt.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module ActiontextTranslate
+  module Translators
+    # ChatGPT (OpenAI) translator implementation
+    class Chatgpt < Base
+      API_ENDPOINT = 'https://api.openai.com/v1/chat/completions'
+
+      # Language code to name mapping for clearer ChatGPT prompts
+      # Only includes languages where the code doesn't obviously map to the name
+      # For unlisted languages, the code is capitalized (e.g., 'fr' -> 'Fr')
+      LANGUAGE_NAMES = {
+        'en' => 'English',
+        'uk' => 'Ukrainian',
+        'de' => 'German',
+        'fr' => 'French',
+        'es' => 'Spanish',
+        'it' => 'Italian',
+        'pl' => 'Polish',
+        'pt' => 'Portuguese'
+      }.freeze
+
+      def initialize(config = nil)
+        super
+        @api_key = config&.api_key || ActiontextTranslate.configuration.api_key
+        raise ArgumentError, 'API key is required for ChatGPT translator' if @api_key.nil?
+      end
+
+      # Translate text using ChatGPT
+      def translate(text, from:, to:, html_mode: false)
+        return text if blank?(text)
+
+        source_lang = language_name(from)
+        target_lang = language_name(to)
+
+        prompt = build_prompt(text, source_lang, target_lang, html_mode)
+
+        response = call_openai_api(prompt)
+        extract_translation(response)
+      end
+
+      private
+
+      def build_prompt(text, source_lang, target_lang, html_mode)
+        if html_mode
+          <<~PROMPT
+            Translate the following HTML content from #{source_lang} to #{target_lang}.
+
+            CRITICAL RULES:
+            1. Preserve ALL HTML tags, attributes, and structure EXACTLY as they are
+            2. Only translate the text content between tags
+            3. Do NOT translate URLs, link hrefs, or placeholder text like "XLINKSTARTX1X"
+            4. Do NOT add or remove any HTML tags
+            5. Maintain proper spacing and formatting
+            6. Return ONLY the translated HTML, no explanations
+
+            Content to translate:
+            #{text}
+          PROMPT
+        else
+          <<~PROMPT
+            Translate the following text from #{source_lang} to #{target_lang}.
+            Return ONLY the translation, no explanations or additional text.
+
+            Text to translate:
+            #{text}
+          PROMPT
+        end
+      end
+
+      def call_openai_api(prompt)
+        uri = URI(API_ENDPOINT)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = config.timeout
+
+        request = Net::HTTP::Post.new(uri.path)
+        request['Authorization'] = "Bearer #{@api_key}"
+        request['Content-Type'] = 'application/json'
+        request.body = {
+          model: config.model,
+          messages: [
+            {
+              role: 'system',
+              content: 'You are a professional translator. Translate accurately and naturally while ' \
+                       'preserving any HTML structure.'
+            },
+            {
+              role: 'user',
+              content: prompt
+            }
+          ],
+          temperature: config.temperature
+        }.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise TranslationError, "OpenAI API error: #{response.code} - #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise TranslationError, "Failed to parse OpenAI response: #{e.message}"
+      rescue StandardError => e
+        raise TranslationError, "OpenAI API request failed: #{e.message}"
+      end
+
+      def extract_translation(response)
+        response.dig('choices', 0, 'message', 'content')&.strip || ''
+      rescue StandardError => e
+        raise TranslationError, "Failed to extract translation from response: #{e.message}"
+      end
+
+      def language_name(code)
+        normalized = normalize_language_code(code)
+        LANGUAGE_NAMES[normalized] || normalized.capitalize
+      end
+    end
+
+    # Custom error class for translation errors
+    class TranslationError < StandardError; end
+  end
+end

data/lib/actiontext_translate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiontextTranslate
+  VERSION = '0.1.0'
+end

data/lib/actiontext_translate.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'actiontext_translate/version'
+require_relative 'actiontext_translate/configuration'
+require_relative 'actiontext_translate/html_processor'
+require_relative 'actiontext_translate/translators/base'
+require_relative 'actiontext_translate/translator'
+
+module ActiontextTranslate
+  class Error < StandardError; end
+
+  # Quick access method for translation
+  # @param text [String] Text to translate
+  # @param from [String] Source language code
+  # @param to [String] Target language code
+  # @param html_mode [Boolean] Whether to preserve HTML
+  # @return [String] Translated text
+  def self.translate(text, from:, to:, html_mode: false)
+    translator = Translator.new
+    translator.translate(text, from: from, to: to, html_mode: html_mode)
+  end
+
+  # Quick access method for HTML translation
+  # @param html [String] HTML to translate
+  # @param from [String] Source language code
+  # @param to [String] Target language code
+  # @return [String] Translated HTML
+  def self.translate_html(html, from:, to:)
+    translator = Translator.new
+    translator.translate_html(html, from: from, to: to)
+  end
+
+  # Quick access method for ActionText translation
+  # @param rich_text [ActionText::RichText, String] Rich text to translate
+  # @param from [String] Source language code
+  # @param to [String] Target language code
+  # @return [String] Translated HTML
+  def self.translate_action_text(rich_text, from:, to:)
+    translator = Translator.new
+    translator.translate_action_text(rich_text, from: from, to: to)
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: actiontext_translate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mykbren
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Ruby gem for translating ActionText rich text content using ChatGPT
+  while perfectly preserving HTML structure, tags, and links. Extensible architecture
+  allows adding additional translation providers.
+email:
+- myk.bren@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/actiontext_translate.rb
+- lib/actiontext_translate/configuration.rb
+- lib/actiontext_translate/html_processor.rb
+- lib/actiontext_translate/translator.rb
+- lib/actiontext_translate/translators/base.rb
+- lib/actiontext_translate/translators/chatgpt.rb
+- lib/actiontext_translate/version.rb
+homepage: https://github.com/mykbren/actiontext_translate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mykbren/actiontext_translate
+  source_code_uri: https://github.com/mykbren/actiontext_translate
+  changelog_uri: https://github.com/mykbren/actiontext_translate/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Translate ActionText content while preserving HTML tags using ChatGPT
+test_files: []