jekyll-l10n 1.0.5

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

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Jekyll
+  module L10n
+    # Configuration Parser - Extracts and validates localization settings from page front matter
+    #
+    # PageLocalesConfig parses the `with_locales_data` front matter field in Jekyll pages and
+    # provides a type-safe interface to localization configuration. It validates all values
+    # against expected types and ranges, raising clear errors for invalid configurations.
+    #
+    # Configuration can be specified in page front matter at multiple levels:
+    # - Translation settings (fallback modes, LibreTranslate API)
+    # - Extraction settings (which attributes to extract, directories)
+    # - Logging settings (debug output, statistics)
+    #
+    # Key responsibilities:
+    # - Parse `with_locales_data` from page front matter
+    # - Validate locale codes against ISO 639-1/2 format
+    # - Validate LibreTranslate configuration when enabled
+    # - Provide getter methods with sensible defaults
+    # - Raise detailed validation errors for invalid configurations
+    #
+    # @example Minimal configuration
+    #   ---
+    #   with_locales: true
+    #   with_locales_data:
+    #     locales: [es, fr, pt]
+    #   ---
+    #
+    # @example Full configuration with LibreTranslate
+    #   ---
+    #   with_locales: true
+    #   with_locales_data:
+    #     locales: [es, fr, pt_BR]
+    #     extract_on_build: true
+    #     update_compendium: true
+    #     extraction:
+    #       translatable_attributes: [title, alt, aria-label]
+    #     translation:
+    #       fallback: english
+    #       libretranslate_enabled: true
+    #       libretranslate_api_url: "http://localhost:5000/translate"
+    #       libretranslate_timeout: 300
+    #     logging:
+    #       debug: true
+    #   ---
+    #
+    class PageLocalesConfig
+      # Delegate all constant definitions to Constants module
+      LOCALE_PATTERN = Constants::LOCALE_PATTERN
+      DEFAULT_LOCALES_DIR = Constants::DEFAULT_LOCALES_DIR
+      DEFAULT_FALLBACK_MODE = Constants::DEFAULT_FALLBACK_MODE
+      DEFAULT_TRANSLATABLE_ATTRIBUTES = Constants::DEFAULT_TRANSLATABLE_ATTRIBUTES
+      DEFAULT_LIBRETRANSLATE_TIMEOUT = Constants::DEFAULT_LIBRETRANSLATE_TIMEOUT
+      DEFAULT_LIBRETRANSLATE_BATCH_SIZE = Constants::DEFAULT_LIBRETRANSLATE_BATCH_SIZE
+      DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS = Constants::DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS
+      DEFAULT_LIBRETRANSLATE_RETRY_DELAY = Constants::DEFAULT_LIBRETRANSLATE_RETRY_DELAY
+      DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR = Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR
+      DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL = Constants::DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL
+      DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE = Constants::DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE
+      DEFAULT_LIBRETRANSLATE_FORMAT = Constants::DEFAULT_LIBRETRANSLATE_FORMAT
+
+      # @!attribute [r] data
+      #   The raw page data object this config was parsed from
+      #   @return [Hash]
+      attr_reader :data
+
+      # Initialize configuration from page front matter
+      #
+      # Parses the `with_locales_data` section from page front matter and validates
+      # all configuration values. Raises detailed errors if any values are invalid.
+      #
+      # @param page_data [Hash] The Jekyll page data/front matter object
+      # @raise [Jekyll::Errors::InvalidConfigurationError] If locale codes are invalid
+      # @raise [Jekyll::Errors::InvalidConfigurationError] If LibreTranslate config is invalid
+      def initialize(page_data)
+        @config = page_data["with_locales_data"] || {}
+        @data = page_data
+        @page_path = page_data["path"] || "unknown"
+
+        validate_locales!
+        validate_libretranslate!
+      end
+
+      # Get the list of locales configured for this page
+      #
+      # Returns the locales specified in `with_locales_data.locales`, or an empty array
+      # if not configured. All returned locales are guaranteed to match ISO 639-1/2 format.
+      #
+      # @return [Array<String>] BCP 47 locale codes (e.g., ['es', 'fr', 'pt_BR'])
+      def locales
+        @config["locales"] || []
+      end
+
+      # Get the directory where PO files are stored for this page
+      #
+      # Returns the directory specified in `with_locales_data.locales_dir`,
+      # or the default "_locales" if not configured.
+      #
+      # @return [String] The directory path relative to site root
+      def locales_dir
+        @config["locales_dir"] || DEFAULT_LOCALES_DIR
+      end
+
+      # Check if string extraction should run during Jekyll build
+      #
+      # @return [Boolean] true if extraction is enabled (default), false if explicitly disabled
+      def extract_on_build?
+        @config["extract_on_build"] != false
+      end
+
+      # Check if compendium files should be updated during extraction
+      #
+      # @return [Boolean] true if compendium updates are enabled (default), false if
+      #   explicitly disabled
+      def update_compendium?
+        @config["update_compendium"] != false
+      end
+
+      # Check if extraction statistics should be shown in logs
+      #
+      # @return [Boolean] true if statistics are enabled (default), false if explicitly disabled
+      def show_statistics?
+        @config.dig("logging", "show_statistics") != false
+      end
+
+      # Check if debug-level logging is enabled
+      #
+      # @return [Boolean] true if debug logging is configured, false otherwise
+      def debug_logging?
+        @config.dig("logging", "debug") == true
+      end
+
+      # Check if trace-level logging is enabled
+      #
+      # Trace logging includes detailed per-entry logs for extraction and translation operations.
+      # This is automatically enabled if debug_logging? is true.
+      #
+      # @return [Boolean] true if trace logging is enabled or debug logging is enabled
+      def trace_logging?
+        @config.dig("logging", "trace") == true || debug_logging?
+      end
+
+      # Get the fallback mode for missing translations
+      #
+      # Determines how to handle translations that are not found in PO files.
+      # Valid modes: "english" (use original text), "marker" (wrap with markers),
+      # "empty" (leave blank).
+      #
+      # @return [String] The fallback mode ("english", "marker", or "empty")
+      def fallback_mode
+        @config.dig("translation", "fallback") || DEFAULT_FALLBACK_MODE
+      end
+
+      # Get the list of HTML attributes to extract for translation
+      #
+      # Returns attributes specified in `with_locales_data.extraction.translatable_attributes`,
+      # or the default list if not configured (title, alt, aria-label, placeholder,
+      # aria-description).
+      #
+      # @return [Array<String>] List of attribute names to extract
+      def translatable_attributes
+        @config.dig("extraction", "translatable_attributes") || DEFAULT_TRANSLATABLE_ATTRIBUTES
+      end
+
+      # Check if localization is enabled for this page
+      #
+      # A page is considered to have localization enabled if at least one locale is configured.
+      #
+      # @return [Boolean] true if locales list is not empty, false otherwise
+      def enabled?
+        !locales.empty?
+      end
+
+      # Check if LibreTranslate automatic translation is enabled
+      #
+      # Returns true if `libretranslate_enabled` is explicitly set to true,
+      # or if a `libretranslate_api_url` is configured (backward compatibility).
+      #
+      # @return [Boolean] true if LibreTranslate is enabled and configured
+      def libretranslate_enabled?
+        # Priority 1: Explicit flag (when set)
+        if libretranslate_config.key?("libretranslate_enabled")
+          return libretranslate_config["libretranslate_enabled"] == true
+        end
+
+        # Priority 2: Backward compatibility - URL presence (when flag not set)
+        !libretranslate_api_url.nil? && !libretranslate_api_url.empty?
+      end
+
+      # Get the source locale for LibreTranslate translation
+      #
+      # The source locale is the language of the original content being translated.
+      # Defaults to "en" (English) if not specified.
+      #
+      # @return [String] BCP 47 locale code (e.g., 'en', 'fr')
+      def libretranslate_source_locale
+        libretranslate_config["libretranslate_source_locale"] ||
+          DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE
+      end
+
+      # Get the text format for LibreTranslate translation
+      #
+      # Determines how text is passed to LibreTranslate API. Valid values: 'text' or 'html'.
+      # HTML format preserves markup and performs better with structured content.
+      #
+      # @return [String] Either 'text' or 'html' (default: 'html')
+      def libretranslate_format
+        libretranslate_config["libretranslate_format"] || DEFAULT_LIBRETRANSLATE_FORMAT
+      end
+
+      # Get the LibreTranslate API endpoint URL
+      #
+      # Example: "https://api.libretranslate.de" or "http://localhost:5000"
+      #
+      # @return [String, nil] The API URL, or nil if not configured
+      def libretranslate_api_url
+        libretranslate_config["libretranslate_api_url"]
+      end
+
+      # Get the LibreTranslate API key (if required)
+      #
+      # Some LibreTranslate instances require authentication via API key.
+      #
+      # @return [String, nil] The API key, or nil if not configured
+      def libretranslate_api_key
+        libretranslate_config["libretranslate_api_key"]
+      end
+
+      # Get the timeout (in seconds) for LibreTranslate API requests
+      #
+      # @return [Integer] Timeout in seconds (default: 300)
+      def libretranslate_timeout
+        libretranslate_config["libretranslate_timeout"] || DEFAULT_LIBRETRANSLATE_TIMEOUT
+      end
+
+      # Get the batch size for LibreTranslate translations
+      #
+      # Controls how many strings are sent to LibreTranslate in a single API request.
+      # Larger batches are more efficient but may hit size limits.
+      #
+      # @return [Integer] Batch size (default: 50)
+      def libretranslate_batch_size
+        libretranslate_config["libretranslate_batch_size"] || DEFAULT_LIBRETRANSLATE_BATCH_SIZE
+      end
+
+      # Get the number of retry attempts for failed LibreTranslate requests
+      #
+      # @return [Integer] Number of retry attempts (default: 3)
+      def libretranslate_retry_attempts
+        libretranslate_config["libretranslate_retry_attempts"] ||
+          DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS
+      end
+
+      # Get the delay (in seconds) between LibreTranslate retry attempts
+      #
+      # @return [Integer] Delay in seconds (default: 2)
+      def libretranslate_retry_delay
+        libretranslate_config["libretranslate_retry_delay"] ||
+          DEFAULT_LIBRETRANSLATE_RETRY_DELAY
+      end
+
+      # Check if translation should stop on LibreTranslate errors
+      #
+      # If true, any API error will halt the translation process. If false, errors are logged
+      # but translation continues with other entries.
+      #
+      # @return [Boolean] true if errors should stop translation (default), false if
+      #   translation continues
+      def libretranslate_stop_on_error?
+        libretranslate_config["libretranslate_stop_on_error"] != false
+      end
+
+      # Get the interval for logging LibreTranslate translation progress
+      #
+      # Translation progress is logged every N entries translated. Set to 0 to disable
+      # progress logging.
+      #
+      # @return [Integer] Number of entries between progress logs (default: 10)
+      def libretranslate_progress_interval
+        libretranslate_config["libretranslate_progress_interval"] ||
+          DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL
+      end
+
+      private
+
+      def libretranslate_config
+        @config["translation"] || {}
+      end
+
+      def validate_locales!
+        invalid = locales.grep_v(LOCALE_PATTERN)
+
+        return if invalid.empty?
+
+        error_msg = build_validation_error_message(invalid)
+
+        Jekyll.logger.error("Localization Config", error_msg)
+
+        raise Jekyll::Errors::InvalidConfigurationError, error_msg
+      end
+
+      def build_validation_error_message(invalid_codes)
+        <<~ERROR
+          Invalid locale codes in #{@page_path}: #{invalid_codes.join(", ")}
+
+          Expected ISO 639-1/2 format (e.g., 'es', 'fr', 'pt_BR')
+          Valid pattern: ^[a-z]{2}(_[A-Z]{2})?$
+
+          Common mistakes:
+          - Use lowercase language code: 'es' not 'ES' or 'ESP'
+          - Use underscore for country: 'pt_BR' not 'pt-BR'
+          - Use ISO codes: 'es' not 'español'
+          - Minimum 2 characters: 'es' not 'e'
+          - Country code uppercase: 'pt_BR' not 'pt_br'
+        ERROR
+      end
+
+      def validate_libretranslate!
+        return unless libretranslate_enabled?
+
+        # Require URL when enabled
+        if libretranslate_api_url.nil? || libretranslate_api_url.empty?
+          raise Jekyll::Errors::InvalidConfigurationError,
+                "libretranslate_enabled is true but libretranslate_api_url is not configured"
+        end
+
+        # Validate source locale format (ISO 639-1/2)
+        unless LOCALE_PATTERN.match?(libretranslate_source_locale)
+          raise Jekyll::Errors::InvalidConfigurationError,
+                "Invalid libretranslate_source_locale: #{libretranslate_source_locale}"
+        end
+
+        # Validate format
+        unless %w(text html).include?(libretranslate_format)
+          raise Jekyll::Errors::InvalidConfigurationError,
+                "Invalid libretranslate_format: #{libretranslate_format} (must be 'text' or 'html')"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "gettext/po"
+
+module Jekyll
+  module L10n
+    # Converts between translation hash and GetText POEntry formats.
+    #
+    # PoEntryConverter handles bidirectional conversion between simple translation
+    # hashes and GetText::POEntry objects used by the ruby-gettext gem. It preserves
+    # msgstr values, reference comments, and fuzzy flags during conversion.
+    #
+    # Key responsibilities:
+    # * Convert translation hashes to POEntry objects
+    # * Convert POEntry objects back to hash format
+    # * Preserve metadata (references, fuzzy flags) during conversion
+    # * Handle both hash and array return formats
+    #
+    # @example
+    #   hash = { "Hello" => { msgstr: "Hola", reference: "file.html:10" } }
+    #   entries = PoEntryConverter.hash_to_po_entry_array(hash)
+    #   # entries is array of GetText::POEntry objects
+    class PoEntryConverter
+      # Convert translation hash to POEntry hash.
+      #
+      # Converts simple translation hash { msgid => msgstr } or metadata format
+      # { msgid => { msgstr: "...", reference: "...", fuzzy: false } } to a
+      # hash of GetText::POEntry objects keyed by msgid.
+      #
+      # @param hash [Hash] Translation hash
+      # @return [Hash] Hash of { msgid => POEntry }
+      def self.hash_to_po_entries(hash)
+        return {} if hash.nil? || hash.empty?
+
+        hash.each_with_object({}) do |(key, value), result|
+          entry = ::GetText::POEntry.new(:normal)
+          entry.msgid = key
+
+          if value.is_a?(Hash)
+            entry.msgstr = value[:msgstr]
+            entry.add_comment(value[:reference]) if value[:reference]
+            entry.flag = "fuzzy" if value[:fuzzy]
+          else
+            entry.msgstr = value
+          end
+
+          result[key] = entry
+        end
+      end
+
+      # Convert translation hash to array of POEntry objects.
+      #
+      # Converts hash format to array of GetText::POEntry objects, preserving
+      # references and fuzzy flags.
+      #
+      # @param hash [Hash] Translation hash
+      # @return [Array<GetText::POEntry>] Array of POEntry objects
+      def self.hash_to_po_entry_array(hash)
+        return [] if hash.nil? || hash.empty?
+
+        hash.map do |msgid, data|
+          entry = ::GetText::POEntry.new(:normal)
+          entry.msgid = msgid
+
+          if data.is_a?(Hash)
+            entry.msgstr = data[:msgstr]
+            entry.add_comment(data[:reference]) if data[:reference]
+            entry.flag = "fuzzy" if data[:fuzzy]
+          else
+            entry.msgstr = data
+          end
+
+          entry
+        end
+      end
+
+      # Convert POEntry objects to translation hash.
+      #
+      # @param entries [Array<GetText::POEntry>] Array of POEntry objects
+      # @return [Hash] Hash of { msgid => { msgstr: "...", reference: "..." } }
+      def self.po_entries_to_hash(entries)
+        return {} if entries.nil? || entries.empty?
+
+        entries.each_with_object({}) do |entry, hash|
+          hash[entry.msgid] = {
+            :msgstr    => entry.msgstr.to_s,
+            :reference => entry.extracted_comment,
+          }
+        end
+      end
+
+      # Convert POEntry objects to array of hashes.
+      #
+      # Each entry becomes a hash with :msgid and :msgstr (and optional :reference).
+      #
+      # @param entries [Array<GetText::POEntry>] Array of POEntry objects
+      # @return [Array<Hash>] Array of { msgid: "...", msgstr: "...", reference: "..." }
+      def self.po_entries_to_array_of_hashes(entries)
+        return [] if entries.nil? || entries.empty?
+
+        entries.map do |entry|
+          hash = { :msgid => entry.msgid, :msgstr => entry.msgstr }
+          if entry.extracted_comment && !entry.extracted_comment.empty?
+            hash[:reference] = entry.extracted_comment
+          end
+          hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Accesses Jekyll site configuration properties.
+    #
+    # SiteConfigAccessor provides a unified interface for accessing Jekyll site
+    # properties, handling both normal Jekyll site objects and test doubles (hashes).
+    # This enables easier testing and more flexible configuration handling.
+    #
+    # Key responsibilities:
+    # * Extract localization data from site configuration
+    # * Access site source directory
+    # * Access site destination directory
+    # * Handle both Jekyll site objects and hash-based doubles
+    #
+    # @example
+    #   locales_data = SiteConfigAccessor.extract_locales_data(site)
+    #   source = SiteConfigAccessor.source(site)
+    #   dest = SiteConfigAccessor.dest(site)
+    class SiteConfigAccessor
+      # Extract localization configuration from site.
+      #
+      # Accesses the localization_gettext configuration which contains the
+      # locales, extraction settings, and other localization options.
+      #
+      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
+      # @return [Hash] Localization configuration hash or empty hash if not found
+      def self.extract_locales_data(site)
+        config = site.is_a?(Hash) ? site["config"] : site.config
+        config.dig("defaults", 0, "values", "with_locales_data") || {}
+      end
+
+      # Get the site source directory.
+      #
+      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
+      # @return [String] Path to site source directory
+      def self.source(site)
+        site.is_a?(Hash) ? site["source"] : site.source
+      end
+
+      # Get the site destination directory.
+      #
+      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
+      # @return [String] Path to site destination directory
+      def self.dest(site)
+        site.is_a?(Hash) ? site["dest"] : site.dest
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Normalizes whitespace in text for consistent matching.
+    #
+    # TextNormalizer converts multiple whitespace characters (newlines, tabs,
+    # carriage returns) to single spaces and collapses consecutive spaces into
+    # a single space. Used during extraction and translation to ensure consistent
+    # text matching regardless of HTML formatting.
+    #
+    # Key responsibilities:
+    # * Replace newlines, tabs, carriage returns with spaces
+    # * Collapse consecutive spaces to single space
+    module TextNormalizer
+      extend self
+
+      # Normalize whitespace in text for consistent translation matching.
+      #
+      # === Why Normalization Is Critical ===
+      # HTML rendering treats whitespace differently than source code:
+      # - Multiple spaces render as one space
+      # - Newlines become spaces (unless in <pre> tags)
+      # - Tabs become spaces
+      #
+      # Without normalization, matching fails:
+      #   Source HTML: "<p>Hello  world</p>"  (two spaces)
+      #   Rendered: "Hello world" (one space)
+      #   PO entry msgid: "Hello world" (one space)
+      #   Without normalization: "Hello  world" ≠ "Hello world" (NO MATCH!)
+      #   With normalization: "Hello world" == "Hello world" (MATCH!)
+      #
+      # === Process ===
+      # 1. Replace all newlines, tabs, carriage returns with spaces
+      # 2. Collapse consecutive spaces into single space
+      # This ensures text from DOM matches extracted msgid exactly.
+      #
+      # @param text [String, nil] Text to normalize
+      # @return [String, nil] Normalized text or nil
+      def normalize(text)
+        return nil if text.nil?
+
+        text.gsub(%r![\n\t\r]+!, " ").gsub(%r!\s+!, " ")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Jekyll
+  module L10n
+    # Validates text for extraction and translation.
+    #
+    # TextValidator checks if text meets minimum length requirements for
+    # extraction. Very short strings (< 3 characters) are typically skipped
+    # to focus on meaningful translatable content.
+    #
+    # Key responsibilities:
+    # * Check minimum text length requirement
+    # * Validate text is not nil
+    #
+    # @example
+    #   TextValidator.valid?("Hello")  # => true
+    #   TextValidator.valid?("Hi")     # => false (< 3 chars)
+    class TextValidator
+      # Check if text is valid for extraction.
+      #
+      # Text is valid if it's non-nil and meets the minimum length
+      # requirement (MIN_TRANSLATABLE_LENGTH, typically 3 characters).
+      #
+      # @param text [String, nil] Text to validate
+      # @return [Boolean] True if text meets requirements
+      def self.valid?(text)
+        return false if text.nil?
+
+        text.length >= Jekyll::L10n::Constants::MIN_TRANSLATABLE_LENGTH
+      end
+    end
+  end
+end