jekyll-l10n 1.7.0 → 2.0.0

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

@@ -4,51 +4,25 @@ require_relative '../constants'
 
 module Jekyll
   module L10n
-    # Configuration Parser - Extracts and validates localization settings from page front matter
+    # Wraps a `with_locales_data` hash and answers questions about it, filling in
+    # the defaults from Constants for anything not set.
     #
-    # 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.
+    # It raises InvalidConfigurationError right away for bad locale codes or bad
+    # LibreTranslate settings, so mistakes stop the build early.
     #
-    # 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)
+    # Build it from the right data:
+    # - For one page, use SiteConfigAccessor.effective_page_data(page), never raw
+    #   `page.data`; otherwise the page loses the site defaults.
+    # - For site-wide settings, use
+    #   `{ 'with_locales_data' => SiteConfigAccessor.extract_locales_data(site) }`.
     #
-    # Key responsibilities:
-    # - Parse `with_locales_data` from page front matter
-    # - Validate locale codes against ISO 639-1 (with optional ISO 3166-1 alpha-2 country) 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
-    #   ---
+    # @example
+    #   config = PageLocalesConfig.new(SiteConfigAccessor.effective_page_data(page))
+    #   config.locales       # => ["es", "fr"]
+    #   config.fallback_mode # => "english"
     #
     class PageLocalesConfig
-      # Delegate all constant definitions to Constants module
+      # Shortcuts to the defaults in Constants.
       LOCALE_PATTERN = Constants::LOCALE_PATTERN
       DEFAULT_LOCALES_DIR = Constants::DEFAULT_LOCALES_DIR
       DEFAULT_FALLBACK_MODE = Constants::DEFAULT_FALLBACK_MODE
@@ -63,18 +37,14 @@ module Jekyll
       DEFAULT_LIBRETRANSLATE_FORMAT = Constants::DEFAULT_LIBRETRANSLATE_FORMAT
 
       # @!attribute [r] data
-      #   The raw page data object this config was parsed from
+      #   The hash this config was built 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
+      # @param page_data [Hash] A hash with a `with_locales_data` key, and
+      #   optionally `path` (used in error messages)
+      # @raise [Jekyll::Errors::InvalidConfigurationError] If a locale code or a
+      #   LibreTranslate setting is invalid
       def initialize(page_data)
         @config = page_data['with_locales_data'] || {}
         @data = page_data
@@ -84,200 +54,156 @@ module Jekyll
         validate_libretranslate!
       end
 
-      # Get the list of locales configured for this page
+      # Locales to translate into. The constructor has already checked each code
+      # against LOCALE_PATTERN.
       #
-      # 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 format,
-      # optionally suffixed with an ISO 3166-1 alpha-2 country code.
-      #
-      # @return [Array<String>] BCP 47 locale codes (e.g., ['es', 'fr', 'pt_BR'])
+      # @return [Array<String>] Locale codes such as ["es", "pt_BR"], or []
       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
+      # @return [String] Directory for PO files, relative to the site source
       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
+      # @return [Boolean] false only when `extract_on_build` is false
       def extract_on_build?
         @config['extract_on_build'] != false
       end
 
-      # Check if compendium files should be updated during extraction
+      # Whether to merge page PO files into the locale compendium. A site-wide
+      # setting: read it from the site-wide config, not from a page.
       #
-      # @return [Boolean] true if compendium updates are enabled (default), false if
-      #   explicitly disabled
+      # @return [Boolean] false only when `update_compendium` is false
       def update_compendium?
         @config['update_compendium'] != false
       end
 
-      # Check if extraction statistics should be shown in logs
+      # Whether to print the extraction summary at the end of the build. A
+      # site-wide setting: Extractor reads it from the site-wide config.
       #
-      # @return [Boolean] true if statistics are enabled (default), false if explicitly disabled
+      # @return [Boolean] false only when `logging.show_statistics` is false
       def show_statistics?
         @config.dig('logging', 'show_statistics') != false
       end
 
-      # Check if debug-level logging is enabled
+      # Turns on HtmlTranslator's log of each translation lookup for this page.
       #
-      # @return [Boolean] true if debug logging is configured, false otherwise
+      # @return [Boolean] true when `logging.debug` is true
       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.
+      # Turns on per-entry LibreTranslate logging. Those lines go to Jekyll's
+      # debug level, so they show only with `jekyll build --verbose`.
       #
-      # @return [Boolean] true if trace logging is enabled or debug logging is enabled
+      # @return [Boolean] true when `logging.trace` or `logging.debug` is true
       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).
+      # What to show when a string has no translation: "english" (the original
+      # text), "marker" (the original text wrapped in markers), or "empty".
       #
-      # @return [String] The fallback mode ("english", "marker", or "empty")
+      # @return [String] The fallback mode
       def fallback_mode
         @config.dig('translation', 'fallback') || DEFAULT_FALLBACK_MODE
       end
 
-      # Get the list of HTML attributes to extract for translation
+      # HTML attributes whose values are extracted and translated. Defaults to
+      # DEFAULT_TRANSLATABLE_ATTRIBUTES.
       #
-      # 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
+      # @return [Array<String>] Attribute names
       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
+      # @return [Boolean] true when at least one locale is configured
       def enabled?
         !locales.empty?
       end
 
-      # Check if LibreTranslate automatic translation is enabled
+      # Whether to machine-translate with LibreTranslate. An explicit
+      # `libretranslate_enabled` always wins. Without it, only a
+      # `libretranslate_api_url` you set yourself turns it on; the default URL
+      # does not, so an unconfigured site never tries to reach a server.
       #
-      # 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
+      # @return [Boolean] true if LibreTranslate is enabled
       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?
+        url = libretranslate_config['libretranslate_api_url']
+        url.is_a?(String) && !url.strip.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')
+      # @return [String] Locale code of the original content. Defaults to
+      #   DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE.
       def libretranslate_source_locale
         libretranslate_setting('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.
+      # How strings are sent to LibreTranslate. "html" keeps inline markup intact.
       #
-      # @return [String] Either 'text' or 'html' (default: 'html')
+      # @return [String] "text" or "html". Defaults to DEFAULT_LIBRETRANSLATE_FORMAT.
       def libretranslate_format
         libretranslate_setting('libretranslate_format', DEFAULT_LIBRETRANSLATE_FORMAT)
       end
 
-      # Get the LibreTranslate API endpoint URL
+      # Base URL of the LibreTranslate server, without `/translate`, which
+      # LibreTranslator appends. Returning the default here does not turn
+      # LibreTranslate on; see {#libretranslate_enabled?}.
       #
-      # Example: "https://api.libretranslate.de" or "http://localhost:5000"
-      #
-      # @return [String] The API URL (default: "http://localhost:5000")
+      # @return [String] The URL. Defaults to Constants::DEFAULT_LIBRETRANSLATE_API_URL.
       def libretranslate_api_url
         libretranslate_setting('libretranslate_api_url', Constants::DEFAULT_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
+      # @return [String, nil] API key for servers that require one, or nil
       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)
+      # @return [Integer] Request timeout in seconds. Defaults to
+      #   DEFAULT_LIBRETRANSLATE_TIMEOUT.
       def libretranslate_timeout
         libretranslate_setting('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.
+      # Strings sent per request. Larger batches mean fewer requests but may
+      # exceed the server's size limit.
       #
-      # @return [Integer] Batch size (default: 50)
+      # @return [Integer] Defaults to DEFAULT_LIBRETRANSLATE_BATCH_SIZE.
       def libretranslate_batch_size
         libretranslate_setting('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)
+      # @return [Integer] Retries for a failed request. Defaults to
+      #   DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS.
       def libretranslate_retry_attempts
         libretranslate_setting('libretranslate_retry_attempts', DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS)
       end
 
-      # Get the delay (in seconds) between LibreTranslate retry attempts
-      #
-      # @return [Integer] Delay in seconds (default: 2)
+      # @return [Integer] Seconds to wait between retries. Defaults to
+      #   DEFAULT_LIBRETRANSLATE_RETRY_DELAY.
       def libretranslate_retry_delay
         libretranslate_setting('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.
+      # When true, the first API error stops machine translation. When false, the
+      # error is logged and the remaining entries are still translated.
       #
-      # @return [Boolean] true if errors should stop translation, false if
-      #   translation continues (default: false)
+      # @return [Boolean] Defaults to Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR.
       def libretranslate_stop_on_error?
         val = libretranslate_config['libretranslate_stop_on_error']
         val.nil? ? Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR : val != 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.
+      # Log progress after every this many translated entries; 0 turns it off.
       #
-      # @return [Integer] Number of entries between progress logs (default: 10)
+      # @return [Integer] Defaults to DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL.
       def libretranslate_progress_interval
         libretranslate_setting('libretranslate_progress_interval', DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL)
       end
@@ -323,19 +249,16 @@ module Jekyll
       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 is enabled but libretranslate_api_url is not configured'
         end
 
-        # Validate source locale format (ISO 639-1, optionally with ISO 3166-1 alpha-2 country)
         unless LOCALE_PATTERN.match?(libretranslate_source_locale)
           raise Jekyll::Errors::InvalidConfigurationError,
                 "Invalid libretranslate_source_locale: #{libretranslate_source_locale}"
         end
 
-        # Validate format
         return if %w[text html].include?(libretranslate_format)
 
         raise Jekyll::Errors::InvalidConfigurationError,

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

@@ -2,32 +2,29 @@
 
 module Jekyll
   module L10n
-    # Accesses Jekyll site configuration properties.
+    # Reads `with_locales_data` settings from the site and its pages.
     #
-    # 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.
+    # The plugin reads settings in two ways, and this class holds both:
+    # - Per-page settings: {.page_locales_data} merges the page's front matter
+    #   over the `_config.yml` defaults that match the page. Read page settings
+    #   through it (or {.effective_page_data}), never from `page.data` directly.
+    # - Site-wide settings: {.extract_locales_data} returns the first `defaults`
+    #   entry that has `with_locales_data`, whatever its scope.
     #
-    # Key responsibilities:
-    # * Extract localization data from site configuration
-    # * Compute the union of all configured locales across site and page front matter
-    # * Access site source directory
-    # * Access site destination directory
-    # * Handle both Jekyll site objects and hash-based doubles
+    # Methods that take a site also accept a Hash, so specs can pass a plain
+    # hash instead of a Jekyll::Site.
     #
     # @example
-    #   locales_data = SiteConfigAccessor.extract_locales_data(site)
-    #   all_locales  = SiteConfigAccessor.all_configured_locales(site)
-    #   source = SiteConfigAccessor.source(site)
-    #   dest = SiteConfigAccessor.dest(site)
+    #   SiteConfigAccessor.page_locales_data(page)['locales'] # => ["es", "fr"]
+    #   SiteConfigAccessor.extract_locales_data(site)['update_compendium']
     class SiteConfigAccessor
-      # Extract localization configuration from site.
+      # Site-wide `with_locales_data`: the value from the first `defaults` entry
+      # that has one, whatever pages it matches. Used for settings that apply
+      # to the whole build, such as `update_compendium` and
+      # `logging.show_statistics`.
       #
-      # Accesses the with_locales_data 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
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [Hash] The settings, or {} when no entry has them
       def self.extract_locales_data(site)
         config = site.is_a?(Hash) ? site['config'] : site.config
         defaults = config['defaults'] || []
@@ -35,20 +32,65 @@ module Jekyll
         entry&.dig('values', 'with_locales_data') || {}
       end
 
-      # Compute the union of all locales configured anywhere on the site.
+      # The page's `with_locales_data`, merged over the `_config.yml` defaults
+      # that match the page.
       #
-      # Combines locales from two sources:
-      # - The site-wide `with_locales_data.locales` default (from `_config.yml`)
-      # - Any page-level `with_locales_data.locales` front-matter override, since
-      #   a page-level override replaces the site default for that page rather than
-      #   inheriting it, so page scanning alone misses site-wide locales when few
-      #   or no ordinary pages are present.
+      # We need this because Jekyll's `page.data` fills in defaults one
+      # top-level key at a time: as soon as a page sets any `with_locales_data`
+      # key, `page.data` loses all the site defaults for it. This method gives
+      # the same result Liquid templates see. Nested hashes merge key by key;
+      # lists such as `locales` are replaced, not combined.
       #
-      # This lets callers discover locales that exist only as a page-level override,
-      # not declared in site config, while also retaining all site-wide locales.
+      # @param page [Jekyll::Page] The page. Any other object gets only its own value.
+      # @return [Hash] The page's settings
+      def self.page_locales_data(page)
+        own = page.data['with_locales_data']
+        own = {} unless own.is_a?(Hash)
+        deep_merge(defaults_locales_data_for(page), own)
+      end
+
+      # Like Jekyll::Utils.deep_merge_hashes: nested hashes merge, and any other
+      # value from `override` (lists included) wins. Returns a new hash.
+      def self.deep_merge(base, override)
+        base.merge(override) do |_key, base_value, override_value|
+          if base_value.is_a?(Hash) && override_value.is_a?(Hash)
+            deep_merge(base_value, override_value)
+          else
+            override_value
+          end
+        end
+      end
+      private_class_method :deep_merge
+
+      # The page's data with `with_locales_data` replaced by
+      # {.page_locales_data}. Pass this to PageLocalesConfig.new.
+      #
+      # @param page [Jekyll::Page] The page
+      # @return [Hash] Page data with merged `with_locales_data`
+      def self.effective_page_data(page)
+        page.data.merge('with_locales_data' => page_locales_data(page))
+      end
+
+      # `with_locales_data` from the defaults that match the page, or {} when
+      # the page has no site to look them up in (as in some specs).
+      def self.defaults_locales_data_for(page)
+        return {} unless page.is_a?(Jekyll::Page)
+
+        site = page.site
+        return {} unless site.respond_to?(:frontmatter_defaults)
+
+        value = site.frontmatter_defaults.all(page.relative_path, :pages)['with_locales_data']
+        value.is_a?(Hash) ? value : {}
+      end
+      private_class_method :defaults_locales_data_for
+
+      # Every locale the site uses: the site-wide list plus any list a page sets
+      # in its front matter. Extraction uses it to skip localized output
+      # folders, and the compendium steps use it to cover locales that only one
+      # page adds.
       #
-      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
-      # @return [Array<String>] Unique locale codes configured anywhere on the site
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [Array<String>] Unique locale codes
       def self.all_configured_locales(site)
         site_wide_locales = extract_locales_data(site)['locales'] || []
         pages = site.is_a?(Hash) ? site['pages'] : site.pages
@@ -56,18 +98,14 @@ module Jekyll
         (site_wide_locales + page_locales).uniq
       end
 
-      # Get the site source directory.
-      #
-      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
-      # @return [String] Path to site source directory
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [String] The 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
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [String] The site destination directory
       def self.dest(site)
         site.is_a?(Hash) ? site['dest'] : site.dest
       end

data/lib/jekyll-l10n/version.rb

@@ -6,6 +6,6 @@ module Jekyll
     # Regenerated alongside the gemspec on every `make jekyll-l10n.gemspec`
     # run (locally or in CI), so it always matches spec.version in the built
     # gem. Any hand edit is overwritten on the next run.
-    VERSION = '1.7.0'
+    VERSION = '2.0.0'
   end
 end