jekyll-l10n 1.0.5

data/lib/jekyll-l10n/translation/libre_translator.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # Translates compendium entries using the LibreTranslate API.
+    #
+    # LibreTranslator integrates with the LibreTranslate API to automatically
+    # translate untranslated entries in compendium PO files. It handles batching,
+    # retries with exponential backoff, progress logging, and API error handling.
+    # Translations are written directly to POEntry objects in-place.
+    #
+    # Key responsibilities:
+    # * Send translation requests to LibreTranslate API
+    # * Batch translations for efficiency
+    # * Handle API timeouts and failures with retries
+    # * Log translation progress at configurable intervals
+    # * Update POEntry msgstr with translated text
+    # * Parse JSON API responses
+    #
+    # @example
+    #   translator = LibreTranslator.new(config)
+    #   translator.translate_compendium(po_entries, 'es')
+    #   # po_entries now have msgstr filled from API translations
+    class LibreTranslator
+      TranslationError = Class.new(StandardError) unless defined?(TranslationError)
+
+      # Initialize a new LibreTranslator.
+      #
+      # @param config [PageLocalesConfig] Configuration with LibreTranslate settings:
+      #   - libretranslate_api_url [String] API endpoint URL
+      #   - libretranslate_api_key [String, nil] Optional API key
+      #   - libretranslate_timeout [Integer] Request timeout in seconds
+      #   - libretranslate_batch_size [Integer] Entries per batch request
+      #   - libretranslate_retry_attempts [Integer] Max retry attempts
+      #   - libretranslate_retry_delay [Integer] Delay between retries in seconds
+      #   - libretranslate_progress_interval [Integer] Log progress every N entries
+      def initialize(config)
+        @config = config
+      end
+
+      # Translate a compendium to a target locale.
+      #
+      # Identifies untranslated entries (empty msgstr) and sends them to LibreTranslate
+      # API for translation. Updates POEntry objects in-place with translated text.
+      # Handles batching, retries, and progress logging.
+      #
+      # @param po_entries [Array<GetText::POEntry>] Array of PO entries from compendium
+      # @param target_locale [String] Target locale code (e.g., 'es', 'fr')
+      # @return [void]
+      # @raise [TranslationError] If API request fails and stop_on_error is true
+      # @raise [TranslationError] If max retry attempts exceeded
+      def translate_compendium(po_entries, target_locale)
+        translatable_count, empty_entries = count_translatable_entries(po_entries)
+        return if empty_entries.empty?
+
+        log_translation_progress(empty_entries.length, translatable_count, target_locale)
+        start_time = Time.now
+        process_translation_batches(empty_entries, target_locale, start_time)
+        log_translation_complete(empty_entries.length, target_locale, start_time)
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def retry_with_backoff
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+        attempts = 0
+        begin
+          yield
+        rescue StandardError => e
+          attempts += 1
+
+          if attempts > @config.libretranslate_retry_attempts
+            raise TranslationError,
+                  "Max retry attempts reached"
+          end
+
+          raise TranslationError, e.message if @config.libretranslate_stop_on_error?
+
+          max_attempts = @config.libretranslate_retry_attempts
+
+          # === EXPONENTIAL BACKOFF WITH JITTER ===
+          # Calculate delay using exponential backoff: base_delay * (2 ^ (attempt - 1))
+          # Add jitter (random 0-1 seconds) to prevent thundering herd problem
+          # Cap maximum delay at 30 seconds to prevent extremely long waits
+          base_delay = @config.libretranslate_retry_delay
+          exponential_delay = base_delay * (2**(attempts - 1))
+          jitter = rand(0..1000) / 1000.0 # Random jitter between 0-1 second
+          delay = [exponential_delay + jitter, 30].min # Cap at 30 seconds max
+
+          delay_str = delay.round(2)
+          Jekyll.logger.warn(
+            "LibreTranslator",
+            "Retrying translation (attempt #{attempts}/#{max_attempts}) after #{delay_str}s: " \
+            "#{e.message}"
+          )
+          sleep(delay)
+          retry
+        end
+      end
+
+      def count_translatable_entries(po_entries)
+        translatable_count = po_entries.count { |e| !e.msgid.strip.empty? }
+        empty_count = po_entries.select { |entry| entry.msgstr.empty? && !entry.msgid.strip.empty? }
+        [translatable_count, empty_count]
+      end
+
+      def log_translation_progress(empty_count, _translatable_count, target_locale)
+        Jekyll.logger.info "Localization",
+                           "Translating #{empty_count} entries for #{target_locale}"
+      end
+
+      def log_periodic_progress(current_num, total_entries, target_locale, start_time)
+        elapsed = Time.now - start_time
+        percent = (current_num.to_f / total_entries * 100).round
+
+        Jekyll.logger.info "Localization",
+                           "[LibreTranslator] Progress: #{current_num}/#{total_entries} " \
+                           "(#{percent}%) translated for #{target_locale} [#{elapsed.round(1)}s]"
+      end
+
+      def log_translation_complete(entries_translated, target_locale, start_time)
+        elapsed = Time.now - start_time
+        throughput = entries_translated.positive? ? (entries_translated / elapsed).round(1) : 0
+
+        Jekyll.logger.info "Localization",
+                           "[LibreTranslator] Completed: #{entries_translated} entries " \
+                           "translated for #{target_locale} [#{elapsed.round(1)}s, " \
+                           "~#{throughput} entries/sec]"
+      end
+
+      def process_translation_batches(empty_entries, target_locale, start_time)
+        batch_size = @config.libretranslate_batch_size
+        progress_interval = @config.libretranslate_progress_interval
+
+        empty_entries.each_slice(batch_size).with_index do |batch, batch_num|
+          start_num = (batch_num * batch_size) + 1
+          retry_with_backoff do
+            translate_batch(batch, target_locale, start_num, empty_entries.length,
+                            start_time, progress_interval)
+          end
+        end
+      end
+
+      # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
+      def translate_batch(batch, target_locale, start_num, total_entries, start_time,
+                          progress_interval)
+        # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
+        batch.each_with_index do |entry, index|
+          current_num = start_num + index
+
+          # Log progress at intervals and at the end
+          if progress_interval.positive? &&
+              ((current_num % progress_interval).zero? || current_num == total_entries)
+            log_periodic_progress(current_num, total_entries, target_locale, start_time)
+          end
+
+          # Move per-entry logs to TRACE level for deep debugging
+          LoggerFormatter.trace_if_enabled(
+            @config, "LibreTranslator",
+            "Translating entry #{current_num}/#{total_entries}: #{entry.msgid[0..50]}"
+          )
+
+          texts = [entry.msgid]
+          translations = make_api_request(texts, target_locale)
+          entry.msgstr = translations[0] || ""
+        end
+      rescue StandardError => e
+        Jekyll.logger.error "LibreTranslator", "Error in translate_batch: #{e.class}: #{e.message}"
+        Jekyll.logger.error "LibreTranslator", e.backtrace.first(5).join("\n")
+        raise
+      end
+
+      def http_config
+        @http_config ||= begin
+          uri = URI(@config.libretranslate_api_url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.read_timeout = @config.libretranslate_timeout
+          http.open_timeout = @config.libretranslate_timeout
+          http
+        end
+      end
+
+      def api_headers
+        headers = { "Content-Type" => "application/json" }
+        if @config.libretranslate_api_key
+          headers["Authorization"] =
+            "Bearer #{@config.libretranslate_api_key}"
+        end
+        headers
+      end
+
+      def make_api_request(text, target_locale)
+        uri = URI("#{@config.libretranslate_api_url}/translate")
+        Jekyll.logger.debug "LibreTranslator", "Requesting #{uri}"
+        request = Net::HTTP::Post.new(uri, api_headers)
+        request.body = {
+          :q      => text,
+          :source => @config.libretranslate_source_locale,
+          :target => target_locale,
+          :format => @config.libretranslate_format,
+        }.to_json
+        response = http_config.request(request)
+        Jekyll.logger.debug "LibreTranslator", "Response code: #{response.code}"
+        handle_api_response(response)
+      rescue Net::ReadTimeout, Net::OpenTimeout => e
+        raise TranslationError, "API timeout: #{e.message}"
+      end
+
+      def handle_api_response(response)
+        response_data = JSON.parse(response.body)
+        translated = response_data["translatedText"]
+        translation_str = translated.is_a?(Array) ? translated.inspect : translated
+        Jekyll.logger.debug "LibreTranslator", "Parsed translation: #{translation_str}"
+        translated
+      rescue JSON::ParserError, NoMethodError => e
+        raise TranslationError, "Invalid API response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/translation/page_translation_loader.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../po_file/manager"
+require_relative "../utils/page_locales_config"
+require_relative "../utils/url_path_builder"
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # Loads and merges page-specific and compendium translations.
+    #
+    # PageTranslationLoader combines compendium (site-wide) translations with
+    # page-specific translations for a given locale and URL. It loads both
+    # translation sources from PO files, merges them (page-specific takes
+    # precedence), and returns the combined translation hash for use by
+    # HtmlTranslator.
+    #
+    # Key responsibilities:
+    # * Load compendium translations for a locale
+    # * Convert page URLs to PO file paths
+    # * Load page-specific translations
+    # * Merge compendium and page-specific translations
+    # * Filter empty translations (untranslated entries)
+    # * Log loading progress at debug level
+    #
+    # @example
+    #   config = PageLocalesConfig.new(page.data)
+    #   translations = PageTranslationLoader.load(site, 'es', '/docs/index.html', config)
+    #   # Returns merged translations for that page in Spanish
+    class PageTranslationLoader
+      # Load and merge translations for a page in a specific locale.
+      #
+      # Loads the compendium (site-wide) translations and page-specific translations,
+      # merges them (page-specific entries override compendium), and returns the
+      # combined hash. Filters out untranslated entries (empty msgstr).
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @param original_url [String] Original page URL (e.g., '/docs/index.html')
+      # @param config [PageLocalesConfig] Localization configuration for the page
+      # @return [Hash] Merged translation hash { msgid => msgstr }, filtered to only
+      #   include non-empty translations
+      def self.load(site, locale, original_url, config)
+        po_manager = PoFileManager.new(site, config.locales_dir)
+        page_path = construct_po_page_path(original_url)
+
+        compendium = po_manager.load_compendium(locale)
+        log_compendium_loaded(locale, compendium)
+
+        page_specific = po_manager.load_po_file(locale, page_path)
+        log_page_specific_loaded(page_path, page_specific)
+
+        translations = compendium.merge(page_specific)
+        log_translations_merged(translations)
+
+        translations.reject { |_msgid, msgstr| msgstr.empty? }
+      end
+
+      def self.construct_po_page_path(url)
+        UrlPathBuilder.url_to_po_page_path(url)
+      end
+
+      def self.log_compendium_loaded(locale, compendium)
+        message = format_compendium_message(locale, compendium.size)
+        LoggerFormatter.debug_if_enabled("PageTranslationLoader", message)
+      end
+
+      def self.log_page_specific_loaded(page_path, page_specific)
+        message = format_page_specific_message(page_path, page_specific.size)
+        LoggerFormatter.debug_if_enabled("PageTranslationLoader", message)
+      end
+
+      def self.log_translations_merged(translations)
+        message = format_merged_message(translations.size)
+        LoggerFormatter.debug_if_enabled("PageTranslationLoader", message)
+      end
+
+      def self.format_compendium_message(locale, size)
+        "[PageTranslationLoader] Loaded compendium for #{locale}: #{size} entries"
+      end
+
+      def self.format_page_specific_message(page_path, size)
+        "[PageTranslationLoader] Loaded page-specific for #{page_path}: #{size} entries"
+      end
+
+      def self.format_merged_message(size)
+        "[PageTranslationLoader] Merged translations: #{size} entries"
+      end
+
+      private_class_method :log_compendium_loaded,
+                           :log_page_specific_loaded,
+                           :log_translations_merged,
+                           :format_compendium_message,
+                           :format_page_specific_message,
+                           :format_merged_message
+    end
+  end
+end

data/lib/jekyll-l10n/translation/translator.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "../utils/page_locales_config"
+require_relative "../utils/html_parser"
+require_relative "../utils/logger_formatter"
+require_relative "../utils/external_link_icon_preserver"
+require_relative "html_translator"
+require_relative "page_translation_loader"
+
+module Jekyll
+  module L10n
+    # Translation Orchestrator - Applies PO file translations to localized pages
+    #
+    # The Translator is the main entry point for applying translations to pages. It's invoked
+    # during the post_render phase of the Jekyll build (via a Jekyll hook) for each localized
+    # page variant. The translator loads appropriate translations from PO files and applies
+    # them to the page's HTML content.
+    #
+    # The translation workflow:
+    # 1. Check if the page is localized and has required metadata
+    # 2. Load translations from PO files (page-specific and compendium)
+    # 3. Apply translations to text nodes and attributes in HTML
+    # 4. Handle missing translations with configured fallback modes
+    # 5. Preserve special elements like external link icons
+    #
+    # Key responsibilities:
+    # - Load translations for the page's locale
+    # - Apply translations to HTML with DOM manipulation
+    # - Handle fallback modes (english, marker, empty)
+    # - Preserve special formatting and elements (icons, badges, etc.)
+    # - Log translation progress and errors
+    #
+    # This runs in phase 3 of the Jekyll build pipeline (Post-Render Phase). See the
+    # "Build Pipeline" section in lib/jekyll-l10n.rb for the complete workflow.
+    #
+    # @example Usage (typically invoked via Jekyll hook)
+    #   # Automatically invoked for localized pages in post_render phase
+    #   translator = Translator.new(localized_page)
+    #   translator.translate
+    #
+    # @see Jekyll::L10n for Build Pipeline documentation
+    # @see Jekyll::L10n::HtmlTranslator for low-level DOM translation logic
+    # @see Jekyll::L10n::PageTranslationLoader for loading translations from PO files
+    #
+    class Translator
+      # @!attribute [r] page
+      #   The Jekyll page being translated
+      #   @return [Jekyll::Page]
+      attr_reader :page
+
+      # Initialize the translator
+      #
+      # @param page [Jekyll::Page] The page to translate (should be a LocalizedPage)
+      def initialize(page)
+        @page = page
+        @site = page.site
+      end
+
+      # Apply translations to the page
+      #
+      # Main entry point for translation. Checks if the page should be translated,
+      # loads the appropriate translations from PO files, applies them to the HTML,
+      # and updates the page's output.
+      #
+      # This method is called automatically by Jekyll's post_render hook for each
+      # LocalizedPage during the build process.
+      #
+      # @return [void]
+      # @note Only translates pages with localized: true and matching locale/original_url
+      # @note Gracefully handles missing translations with configured fallback mode
+      def translate
+        return unless should_translate?
+
+        locale = @page.data["locale"]
+        original_url = @page.data["original_url"]
+        baseurl = @site.config["baseurl"] || ""
+
+        original_page = find_and_log_original_page(original_url)
+        return unless original_page
+
+        translations = load_and_log_translations(locale, original_url, original_page)
+        return if translations.nil? || translations.empty?
+
+        apply_translations_to_page(original_page, translations, locale, baseurl)
+      end
+
+      private
+
+      def load_translations_for_page(locale, original_url, original_page)
+        config = PageLocalesConfig.new(original_page.data)
+        PageTranslationLoader.load(@site, locale, original_url, config)
+      end
+
+      def apply_translations_to_page(original_page, translations, locale, baseurl)
+        config = PageLocalesConfig.new(original_page.data)
+        translator = HtmlTranslator.new(
+          config.fallback_mode,
+          config.translatable_attributes,
+          :debug_logging => config.debug_logging?
+        )
+
+        translated_html = apply_translations(translator, translations, locale, baseurl)
+        if translated_html
+          # Preserve external link icons from the original page after translation
+          translated_html = preserve_external_link_icons(original_page.output, translated_html)
+          @page.output = translated_html
+        end
+      end
+
+      def preserve_external_link_icons(original_html, translated_html)
+        ExternalLinkIconPreserver.preserve(original_html, translated_html)
+      end
+
+      # Apply translations to page output
+      #
+      # Internal helper that uses HtmlTranslator to apply translations to the page's
+      # HTML output, with configurable locale and baseurl for URL transformation.
+      #
+      # @param translator [HtmlTranslator] The translator instance to use
+      # @param translations [Hash] Translation hash mapping text to translations
+      # @param locale [String, nil] Target locale code (defaults to nil). If nil, uses "en"
+      # @param baseurl [String] Base URL for relative URL transformation (defaults to "")
+      # @return [String, nil] Translated HTML string, or nil on error
+      def apply_translations(translator, translations, locale = nil, baseurl = "")
+        if locale && locale != "en"
+          translator.translate(@page.output, translations, locale, baseurl)
+        else
+          translator.translate(@page.output, translations)
+        end
+      rescue StandardError => e
+        Jekyll.logger.error "Localization", "Error translating #{@page.url}: #{e.message}"
+        nil
+      end
+
+      def should_translate?
+        has_data = @page.data
+        has_locale = has_data && @page.data["locale"]
+        has_original_url = has_data && @page.data["original_url"]
+        has_output = @page.output
+        output_not_empty = !@page.output&.empty?
+
+        msg = "should_translate? data=#{has_data}, locale=#{has_locale}, " \
+              "original_url=#{has_original_url}, output=#{has_output}, " \
+              "not_empty=#{output_not_empty}"
+        LoggerFormatter.debug_if_enabled("Translator", msg)
+
+        has_data && has_locale && has_original_url && has_output && output_not_empty
+      end
+
+      def find_original_page_by_url(url)
+        @site.pages.each do |page|
+          next if page.data["localized"] == true
+
+          return page if page.url == url
+        end
+        nil
+      end
+
+      def find_and_log_original_page(original_url)
+        LoggerFormatter.debug_if_enabled("Translator",
+                                         "Translating page: locale=#{@page.data["locale"]}, " \
+                                         "original_url=#{original_url}")
+        original_page = find_original_page_by_url(original_url)
+        if original_page
+          LoggerFormatter.debug_if_enabled("Translator",
+                                           "Original page found: #{original_page.url}")
+        end
+        original_page
+      end
+
+      def load_and_log_translations(locale, original_url, original_page)
+        translations = load_translations_for_page(locale, original_url, original_page)
+        LoggerFormatter.debug_if_enabled("Translator",
+                                         "Loaded #{translations&.length || 0} translations")
+        translations
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/debug_logger.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Jekyll
+  module L10n
+    # Logs detailed translation debug information.
+    #
+    # DebugLogger provides detailed logging of translation attempts for
+    # debugging normalization and matching issues. It logs when translations
+    # are found, when translations are missing, character-level differences,
+    # and similarity analysis for debugging.
+    #
+    # Key responsibilities:
+    # * Log translation match details
+    # * Log missing translations with similar key analysis
+    # * Log character-level differences for debugging
+    # * Provide context around matching failures
+    # * Support verbose translation debugging
+    #
+    # @see Jekyll::L10n::HtmlTranslator for translation workflow context
+    # @see Jekyll::L10n::TextNormalizer for text normalization logic
+    class DebugLogger
+      # Data structure for translation debugging information.
+      TranslationData = Struct.new(:text, :normalized_text, :translated, :translations,
+                                   :keyword_init => true)
+
+      # Log detailed translation information.
+      #
+      # Logs the text being translated, how it was normalized, whether a translation
+      # was found, and provides debugging information if no translation matched.
+      # Only logs if translator has debug_logging enabled.
+      #
+      # @param translator [HtmlTranslator] Translator with debug_logging setting
+      # @param translation_data [TranslationData] Translation details to log
+      # @return [void]
+      def self.log_translation_details(translator, translation_data)
+        return unless translator.debug_logging
+
+        threshold = Jekyll::L10n::Constants::LOG_THRESHOLD_SHORT
+        return if translation_data.translated.nil? && translation_data.text.length <= threshold
+
+        log_missing_translation(translation_data.text, translation_data.normalized_text,
+                                translation_data.translations)
+        log_alert_details(translation_data.text, translation_data.normalized_text,
+                          translation_data.translations)
+        log_found_translation(translation_data.text, translation_data.translated)
+      end
+
+      def self.log_missing_translation(text, normalized_text, translations)
+        return unless translations[normalized_text].nil?
+        return unless text.length > Jekyll::L10n::Constants::LOG_THRESHOLD_SHORT
+
+        similar_keys = translations.keys.select do |key|
+          key.start_with?(text[0..Jekyll::L10n::Constants::LOG_TRUNCATE_SHORT])
+        end
+        return unless similar_keys.any?
+
+        log_no_translation_found(text, normalized_text, similar_keys)
+      end
+
+      def self.log_alert_details(text, normalized_text, translations)
+        return unless text.include?("Alert component is an inline message box")
+
+        matching_keys = translations.keys.select { |key| key.include?("Alert component is") }
+        return unless matching_keys.any?
+
+        key_from_hash = matching_keys[0]
+        log_alert_comparison(text, normalized_text, key_from_hash)
+      end
+
+      def self.log_first_difference(normalized_text, key_from_hash)
+        (0...normalized_text.length).each do |i|
+          next unless normalized_text[i] != key_from_hash[i]
+
+          log_difference_at_position(normalized_text, key_from_hash, i)
+          log_context_strings(normalized_text, key_from_hash, i)
+          break
+        end
+
+        log_normalization_match
+      end
+
+      def self.log_found_translation(text, translated)
+        return unless translated && translated.length > Jekyll::L10n::Constants::LOG_THRESHOLD_SHORT
+
+        truncate_length = Jekyll::L10n::Constants::LOG_TRUNCATE_LONG
+        log_message(
+          "[HtmlTranslator] ✓ TRANSLATION FOUND: #{text[0..truncate_length]}... => " \
+          "#{translated[0..truncate_length]}..."
+        )
+      end
+
+      private
+
+      def self.log_no_translation_found(text, normalized_text, similar_keys)
+        truncate_length = Jekyll::L10n::Constants::LOG_TRUNCATE_LONG
+        log_message("[HtmlTranslator] ✗ NO TRANSLATION FOUND for: #{text[0..truncate_length]}...")
+        log_message("[HtmlTranslator]   Normalized length: #{normalized_text.length}")
+        log_message("[HtmlTranslator]   Similar keys found: #{similar_keys.length}")
+      end
+
+      def self.log_alert_comparison(text, normalized_text, key_from_hash)
+        log_message(
+          "[HtmlTranslator] LENGTH match: HTML=#{text.length} vs KEY=#{key_from_hash.length}"
+        )
+        log_message("[HtmlTranslator] EQUAL: #{text == key_from_hash}")
+        log_message("[HtmlTranslator] NORMALIZED match: #{normalized_text == key_from_hash}")
+      end
+
+      def self.log_difference_at_position(text1, text2, index)
+        char1 = text1[index]
+        char2 = text2[index]
+        log_message(
+          "[HtmlTranslator] DIFF at position #{index}: " \
+          "NORMALIZED=#{char1.inspect} (#{char1.ord}) vs KEY=#{char2.inspect} (#{char2.ord})"
+        )
+      end
+
+      def self.log_context_strings(normalized_text, key_from_hash, index)
+        normalized_context = context_string(normalized_text, index)
+        key_context = context_string(key_from_hash, index)
+
+        log_message("[HtmlTranslator] Context NORMALIZED: ...#{normalized_context.inspect}...")
+        log_message("[HtmlTranslator] Context KEY:        ...#{key_context.inspect}...")
+      end
+
+      def self.log_normalization_match
+        log_message(
+          "[HtmlTranslator] ✓ Text matches after normalization - translation will be applied"
+        )
+      end
+
+      def self.log_message(message)
+        Jekyll.logger.info "Localization", message
+      end
+
+      def self.context_string(text, index)
+        start_idx = [0, index - Jekyll::L10n::Constants::BACKTRACE_CONTEXT_LENGTH].max
+        end_idx = [index + Jekyll::L10n::Constants::BACKTRACE_CONTEXT_LENGTH, text.length - 1].min
+        text[start_idx..end_idx]
+      end
+
+      private_class_method :log_no_translation_found,
+                           :log_alert_comparison,
+                           :log_difference_at_position,
+                           :log_context_strings,
+                           :log_normalization_match,
+                           :log_message,
+                           :context_string
+    end
+  end
+end