jekyll-l10n 1.0.5

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Handles errors with graceful fallback and logging.
+    #
+    # ErrorHandler provides error handling utilities for gracefully managing
+    # exceptions, logging them with context, and providing default fallback values.
+    # This keeps the build process running even when individual operations fail.
+    #
+    # Key responsibilities:
+    # * Execute code with error catching
+    # * Log errors with context information
+    # * Provide fallback default values on error
+    # * Optional debug backtraces
+    #
+    # @example
+    #   result = ErrorHandler.handle_with_default('file loading', {}) do
+    #     load_file('config.yml')
+    #   end
+    #   # Returns loaded data or {} on error
+    class ErrorHandler
+      # Execute code with error catching and fallback logging.
+      #
+      # Executes the provided block and catches any StandardError, logging it
+      # with context and returning nil.
+      #
+      # @param context [String] Context describing what was being done
+      # @yield Code to execute
+      # @return [Object, nil] Result of block or nil on error
+      def self.handle_with_logging(context)
+        yield
+      rescue StandardError => e
+        log_error(context, e)
+        nil
+      end
+
+      # Execute code with error catching and fallback value.
+      #
+      # Executes the provided block and catches any StandardError, logging it
+      # with context and returning the default value.
+      #
+      # @param context [String] Context describing what was being done
+      # @param default_value [Object] Default value to return on error
+      # @yield Code to execute
+      # @return [Object] Result of block or default_value on error
+      def self.handle_with_default(context, default_value)
+        yield
+      rescue StandardError => e
+        log_error(context, e)
+        default_value
+      end
+
+      # Log an error with context.
+      #
+      # Logs error message and optionally backtrace if DEBUG environment variable is set.
+      #
+      # @param context [String] Context describing what was being done
+      # @param error [StandardError] The error that occurred
+      # @return [void]
+      def self.log_error(context, error)
+        Jekyll.logger.error "Localization", "Error in #{context}: #{error.message}"
+        Jekyll.logger.debug "Localization", error.backtrace.join("\n") if ENV["DEBUG"]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require_relative "html_parser"
+
+module Jekyll
+  module L10n
+    module ExternalLinkIconPreserver
+      # Preserves external link icons from original HTML in translated HTML
+      #
+      # External link icons (e.g., FontAwesome's fa-external-link) are often
+      # lost during translation because:
+      # 1. Block-level translation replaces entire element content
+      # 2. Empty icon tags are removed during text extraction
+      #
+      # This method restores icons by:
+      # 1. Finding all i.fa-external-link icons in the original HTML
+      # 2. Matching links by href attribute
+      # 3. Copying icons to the translated HTML
+      #
+      # @param original_html [String] Original HTML with icons
+      # @param translated_html [String] Translated HTML potentially missing icons
+      # @return [String] Translated HTML with icons restored
+      def self.preserve(original_html, translated_html)
+        # Use Nokogiri::HTML() instead of DocumentFragment.parse() to preserve the full
+        # HTML document structure including DOCTYPE, html, head, and body tags.
+        # DocumentFragment.parse() is appropriate for partial HTML only, and would strip
+        # document-level structure.
+        original_doc = Nokogiri::HTML(original_html)
+        translated_doc = Nokogiri::HTML(translated_html)
+
+        # Find all external link icons in original
+        original_icons = original_doc.css("i.fa-external-link")
+        return translated_html if original_icons.empty?
+
+        # Process each icon found in the original HTML
+        restore_icons_to_translated(original_icons, translated_doc)
+
+        result = translated_doc.to_html
+
+        # Remove the auto-inserted meta tag by libxml2 during HTML serialization
+        HtmlParser.remove_meta_charset(result)
+      rescue StandardError => e
+        Jekyll.logger.error "Localization", "Error preserving external link icons: #{e.message}"
+        translated_html
+      end
+
+      def self.restore_icons_to_translated(original_icons, translated_doc)
+        original_icons.each do |icon|
+          link = icon.parent
+          next unless link&.name == "a"
+
+          href = link["href"]
+          next unless href
+
+          # Find the same link in translated version
+          translated_link = translated_doc.css("a[href=\"#{href}\"]").first
+          next unless translated_link
+
+          # Check if icon already exists
+          next if translated_link.css("i.fa-external-link").any?
+
+          # Add icon to translated link
+          icon_copy = icon.dup
+          translated_link.add_child(icon_copy)
+        end
+      end
+
+      # Alternative method that preserves ALL inline elements, not just icons
+      # Useful for preserving SVG icons, badges, etc.
+      #
+      # @param original_html [String] Original HTML
+      # @param translated_html [String] Translated HTML
+      # @return [String] Translated HTML with all inline elements preserved
+      def self.preserve_all_inline_elements(original_html, translated_html)
+        original_doc = Nokogiri::HTML(original_html)
+        translated_doc = Nokogiri::HTML(translated_html)
+
+        # Find all links with child elements in original
+        original_links = original_doc.css("a[href]")
+        original_links.each do |original_link|
+          preserve_link_inline_elements(original_link, translated_doc)
+        end
+
+        result = translated_doc.to_html
+        HtmlParser.remove_meta_charset(result)
+      rescue StandardError => e
+        Jekyll.logger.error "Localization", "Error preserving inline elements: #{e.message}"
+        translated_html
+      end
+
+      def self.preserve_link_inline_elements(original_link, translated_doc)
+        href = original_link["href"]
+        return unless href
+
+        # Get all non-text children (i, svg, span, etc.)
+        inline_children = original_link.children.select(&:element?)
+        return if inline_children.empty?
+
+        # Find matching link in translated version
+        translated_link = translated_doc.css("a[href=\"#{href}\"]").first
+        return unless translated_link
+
+        # Append inline elements that don't already exist
+        inline_children.each do |child|
+          add_child_if_not_exists(child, translated_link)
+        end
+      end
+
+      def self.add_child_if_not_exists(child, translated_link)
+        child_class = child["class"] || ""
+        # Check if similar element already exists
+        existing = translated_link.css("#{child.name}.#{child_class.split.first}").first
+        return if existing
+
+        # Add the element
+        child_copy = child.dup
+        translated_link.add_child(child_copy)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Jekyll
+  module L10n
+    # File I/O operations with UTF-8 encoding.
+    #
+    # FileOperations provides centralized file reading/writing and directory
+    # creation with automatic UTF-8 encoding. All PO files, HTML files, and
+    # configuration files are handled with UTF-8 encoding for internationalization.
+    #
+    # Key responsibilities:
+    # * Read files with UTF-8 encoding
+    # * Write files with UTF-8 encoding
+    # * Create directory structures as needed
+    #
+    # @example
+    #   content = FileOperations.read_utf8('_locales/es.po')
+    #   FileOperations.write_utf8('output.po', content)
+    #   FileOperations.ensure_directory('output/path/file.po')
+    module FileOperations
+      ENCODING = "UTF-8"
+
+      # Read a file with UTF-8 encoding.
+      #
+      # @param path [String] Path to file to read
+      # @return [String] File contents as UTF-8 string
+      def self.read_utf8(path)
+        ::File.read(path, :encoding => ENCODING)
+      end
+
+      # Write content to a file with UTF-8 encoding.
+      #
+      # @param path [String] Path to file to write
+      # @param content [String] Content to write
+      # @return [Integer] Number of bytes written
+      def self.write_utf8(path, content)
+        ::File.write(path, content, :encoding => ENCODING)
+      end
+
+      # Ensure directory exists for a file path.
+      #
+      # Creates all parent directories as needed for the given file path.
+      # Does nothing if directory already exists.
+      #
+      # @param file_path [String] File path (directory is extracted from this)
+      # @return [void]
+      def self.ensure_directory(file_path)
+        dir = ::File.dirname(file_path)
+        ::FileUtils.mkdir_p(dir) unless ::Dir.exist?(dir)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Constants defining HTML element categories for extraction and translation.
+    #
+    # HtmlElements categorizes HTML elements by their semantic role:
+    # content elements contain translatable text, container elements provide
+    # structural grouping, and block elements are used for layout considerations
+    # during text extraction.
+    #
+    # Key responsibilities:
+    # * Define content elements (paragraphs, headings, lists, etc.)
+    # * Define container elements (div, section, article, etc.)
+    # * Define block elements (all layout-related elements)
+    module HtmlElements
+      # Content elements that contain translatable text
+      CONTENT_ELEMENTS = %w(
+        p h1 h2 h3 h4 h5 h6
+        li dd dt blockquote figcaption
+      ).freeze
+
+      # Container elements for structural grouping
+      CONTAINER_ELEMENTS = %w(div figure section article aside).freeze
+
+      # Block elements for layout
+      BLOCK_ELEMENTS = %w(
+        p div section article aside figure figcaption
+        blockquote pre ul ol li dl dt dd form table
+        header footer nav address
+      ).freeze
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Parses HTML content using Nokogiri.
+    #
+    # HtmlParser provides a unified interface for parsing HTML as either full
+    # documents (preserving DOCTYPE and structure) or as fragments (partial HTML).
+    # It also provides utilities for cleaning up auto-inserted meta tags that
+    # Nokogiri/libxml2 adds during serialization.
+    #
+    # Key responsibilities:
+    # * Parse full HTML documents with DOCTYPE preservation
+    # * Parse HTML fragments for partial content
+    # * Remove auto-inserted meta charset tags
+    class HtmlParser
+      # Parse HTML as a full document.
+      #
+      # Preserves DOCTYPE, html tag, and document structure. Use this for complete
+      # HTML documents. Auto-inserted meta tags can be removed with remove_meta_charset.
+      #
+      # @param html [String] HTML content to parse
+      # @return [Nokogiri::HTML::Document] Parsed HTML document
+      def self.parse_document(html)
+        Nokogiri::HTML(html)
+      end
+
+      # Parse HTML as a fragment.
+      #
+      # Parses partial HTML without wrapping in html/body tags. Use for
+      # extracting pieces of HTML content.
+      #
+      # @param html [String] HTML fragment to parse
+      # @return [Nokogiri::HTML::DocumentFragment] Parsed HTML fragment
+      def self.parse_fragment(html)
+        Nokogiri::HTML.fragment(html)
+      end
+
+      # Remove auto-inserted meta charset tag from serialized HTML.
+      #
+      # Nokogiri/libxml2 automatically inserts a meta charset tag during
+      # serialization. This removes that tag which was not in the original HTML.
+      #
+      # @param html_string [String] Serialized HTML
+      # @return [String] HTML with meta charset tag removed
+      def self.remove_meta_charset(html_string)
+        pattern = %r!<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\n?!
+        html_string.gsub(pattern, "")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "text_normalizer"
+require_relative "html_elements"
+require_relative "text_validator"
+
+module Jekyll
+  module L10n
+    # Utilities for extracting and manipulating HTML text content.
+    #
+    # HtmlTextUtils provides helpers for extracting text from HTML elements while
+    # preserving inline formatting, removing block-level elements, decoding HTML
+    # entities, and cleaning up icon tags. These utilities support the extraction
+    # and translation pipelines.
+    #
+    # Key responsibilities:
+    # * Extract text with inline HTML tags preserved
+    # * Remove block-level elements from cloned nodes
+    # * Remove empty icon tags
+    # * Decode HTML entities to plain text
+    # * Validate extracted text content
+    module HtmlTextUtils
+      # Extended content elements for text extraction (includes inline elements)
+      CONTENT_ELEMENTS = %w(
+        p h1 h2 h3 h4 h5 h6
+        li dd dt blockquote figcaption
+        button span a label
+      ).freeze
+
+      CONTAINER_ELEMENTS = HtmlElements::CONTAINER_ELEMENTS
+      ALL_BLOCK_ELEMENTS = (CONTENT_ELEMENTS + CONTAINER_ELEMENTS).freeze
+
+      # Decode HTML entities to plain text.
+      #
+      # Converts HTML entities (&, <, etc.) to their plain text equivalents.
+      # Uses CGI.unescape_html if available, falls back to manual replacement.
+      #
+      # @param text [String] Text with HTML entities
+      # @return [String] Text with entities decoded
+      def self.decode_html_entities(text)
+        require "cgi"
+        CGI.unescape_html(text)
+      rescue StandardError
+        text.gsub("&", "&")
+          .gsub("&lt;", "<")
+          .gsub("&gt;", ">")
+          .gsub("&quot;", '"')
+          .gsub("&#39;", "'")
+      end
+
+      # Remove block-level elements from a cloned node.
+      #
+      # Replaces block-level element nodes with their children (flattening structure).
+      # Used to extract text while preserving inline elements.
+      #
+      # @param node [Nokogiri::XML::Node] Node to process (modified in place)
+      # @return [void]
+      def self.remove_block_elements_from_node(node)
+        HtmlElements::BLOCK_ELEMENTS.each do |tag|
+          node.xpath(".//#{tag}").each do |elem|
+            elem.replace(elem.children)
+          end
+        end
+      end
+
+      # Remove block-level elements from a node.
+      #
+      # Alias for remove_block_elements_from_node for convenience.
+      #
+      # @param node [Nokogiri::XML::Node] Node to process
+      # @return [void]
+      def self.remove_block_elements(node)
+        remove_block_elements_from_node(node)
+      end
+
+      # Remove empty icon tags from a node.
+      #
+      # Removes all <i> (icon) elements that contain no text. Used to clean up
+      # external link icon markers before text extraction.
+      #
+      # @param node [Nokogiri::XML::Node] Node to process (modified in place)
+      # @return [void]
+      def self.remove_empty_icon_tags(node)
+        node.xpath(".//i").each do |elem|
+          elem.remove if elem.text.strip.empty?
+        end
+      end
+
+      # Extract text with inline tags preserved.
+      #
+      # Extracts text from an element, removes block elements and empty icons,
+      # normalizes whitespace, and decodes HTML entities. Returns plain text
+      # suitable for translation.
+      #
+      # @param node [Nokogiri::XML::Node] Element to extract from
+      # @return [String] Extracted and normalized text
+      def self.extract_with_inline_tags(node)
+        clone = node.dup
+        remove_block_elements_from_node(clone)
+        remove_empty_icon_tags(clone)
+
+        text = TextNormalizer.normalize(clone.inner_html)
+        text = text.strip unless text.nil?
+
+        decode_html_entities(text)
+      end
+
+      # Extract and validate text from a node.
+      #
+      # Extracts text from element if it's a content element, then validates it
+      # meets minimum length requirements.
+      #
+      # @param node [Nokogiri::XML::Node] Node to extract from
+      # @return [String, nil] Validated text, or nil if not extractable or invalid
+      def self.extract_and_validate_text(node)
+        return nil unless extractable?(node)
+
+        text = extract_with_inline_tags(node)
+        TextValidator.valid?(text) ? text : nil
+      end
+
+      # Check if a node is extractable (content element).
+      #
+      # @param node [Nokogiri::XML::Node] Node to check
+      # @return [Boolean] True if node is a content element
+      def self.extractable?(node)
+        node.element? && CONTENT_ELEMENTS.include?(node.name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Formats and conditionally logs messages with component prefixes.
+    #
+    # LoggerFormatter provides a consistent logging interface for the plugin,
+    # prefixing all messages with component names (e.g., "[HtmlTranslator]").
+    # It also handles conditional debug and trace logging based on Jekyll's
+    # log level and configuration.
+    #
+    # Key responsibilities:
+    # * Log messages with component prefixes
+    # * Conditionally log at debug level
+    # * Check debug and trace logging configuration
+    # * Support both Jekyll log levels and configuration-based trace mode
+    #
+    # @example
+    #   LoggerFormatter.info("HtmlTranslator", "Starting translation")
+    #   LoggerFormatter.debug_if_enabled("Extractor", "Extracting from file")
+    module LoggerFormatter
+      # Log an info message with component prefix.
+      #
+      # @param component [String] Component name (e.g., 'HtmlTranslator')
+      # @param message [String] Message to log
+      # @return [void]
+      def self.info(component, message)
+        Jekyll.logger.info "Localization", "[#{component}] #{message}"
+      end
+
+      # Log a debug message with component prefix.
+      #
+      # @param component [String] Component name
+      # @param message [String] Message to log
+      # @return [void]
+      def self.debug(component, message)
+        Jekyll.logger.debug "Localization", "[#{component}] #{message}"
+      end
+
+      # Log a warning message with component prefix.
+      #
+      # @param component [String] Component name
+      # @param message [String] Message to log
+      # @return [void]
+      def self.warn(component, message)
+        Jekyll.logger.warn "Localization", "[#{component}] #{message}"
+      end
+
+      # Log an error message with component prefix.
+      #
+      # @param component [String] Component name
+      # @param message [String] Message to log
+      # @return [void]
+      def self.error(component, message)
+        Jekyll.logger.error "Localization", "[#{component}] #{message}"
+      end
+
+      # Check if debug logging is enabled.
+      #
+      # Returns true if JEKYLL_LOG_LEVEL is set to debug or lower (trace).
+      #
+      # @return [Boolean] True if debug logging is enabled
+      def self.debug?
+        level = Jekyll.logger.level
+        # Handle both numeric and symbol log levels
+        return [:debug, :trace].include?(level) if level.is_a?(Symbol)
+
+        level <= 0 # DEBUG = 0
+      end
+
+      # Check if trace logging is enabled in configuration.
+      #
+      # Accepts both PageLocalesConfig objects and hash-based configurations.
+      # Returns true if trace mode is explicitly enabled.
+      #
+      # @param config [PageLocalesConfig, Hash, nil] Configuration object or hash
+      # @return [Boolean] True if trace logging is enabled
+      def self.trace?(config)
+        return false if config.nil?
+
+        # Try to call trace_logging? method (for PageLocalesConfig objects)
+        return config.trace_logging? if config.respond_to?(:trace_logging?)
+
+        # Fall back to checking hash structure (for hash-based configs)
+        config.dig("logging", "trace") == true
+      rescue StandardError
+        false
+      end
+
+      # Conditionally log at debug level if debug is enabled.
+      #
+      # Only logs if debug logging is enabled via Jekyll log level.
+      #
+      # @param component [String] Component name
+      # @param message [String] Message to log
+      # @return [void]
+      def self.debug_if_enabled(component, message)
+        debug(component, message) if debug?
+      end
+
+      # Conditionally log at debug level if trace mode is enabled.
+      #
+      # Only logs if trace mode is enabled in configuration.
+      #
+      # @param config [PageLocalesConfig, Hash, nil] Configuration
+      # @param component [String] Component name
+      # @param message [String] Message to log
+      # @return [void]
+      def self.trace_if_enabled(config, component, message)
+        debug(component, message) if trace?(config)
+      end
+    end
+  end
+end