jekyll-l10n 1.7.1 → 2.0.0

data/lib/jekyll-l10n/jekyll/url_filter.rb

@@ -5,6 +5,7 @@ require_relative '../constants'
 require_relative '../utils/error_handler'
 require_relative '../utils/locale_name_resolver'
 require_relative '../utils/locale_url_formatter'
+require_relative '../utils/site_config_accessor'
 
 module Jekyll
   module L10n
@@ -192,29 +193,27 @@ module Jekyll
         return false if locale.nil? || locale.empty?
         return true if locale == 'en' # English is always valid
 
-        # Get configured locales from page or site config
         locales_config = configured_locales
 
-        # Normalize both the target locale and each configured locale to BCP 47 form
-        # before comparing, so 'es-ES' matches 'es_ES' and vice versa.
+        # Compare URL forms so 'es-ES' matches 'es_ES' and the other way round.
         url_locale = LocaleUrlFormatter.to_url_segment(locale)
         locales_config.any? { |l| LocaleUrlFormatter.to_url_segment(l) == url_locale }
       end
 
+      # Locales of the page being rendered. A Hash comes from Liquid and already
+      # has the site defaults merged in; a page object needs the same merge.
       def configured_locales
         page = @context.registers[:page]
 
-        # Try to get from page data first (most specific)
         if page
           locales = if page.is_a?(Hash)
                       page.dig('with_locales_data', 'locales')
                     else
-                      page.data&.dig('with_locales_data', 'locales')
+                      SiteConfigAccessor.page_locales_data(page)['locales']
                     end
           return locales if locales && !locales.empty?
         end
 
-        # Fallback to empty array if not configured
         []
       end
 

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

@@ -8,39 +8,23 @@ require_relative '../utils/logger_formatter'
 
 module Jekyll
   module L10n
-    # Loads and merges page-specific and compendium translations.
+    # Reads the translations one page needs for one locale.
     #
-    # 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
+    # It combines two PO files: the locale compendium (`es.po`) and the page's
+    # own file (`es/<page url>/index.html.po`). When both have a string, the
+    # page file wins. With the default `update_compendium: true` the page file
+    # no longer exists after extraction, so the compendium provides everything.
     #
     # @example
-    #   config = PageLocalesConfig.new(page.data)
-    #   translations = PageTranslationLoader.load(site, 'es', '/docs/index.html', config)
-    #   # Returns merged translations for that page in Spanish
+    #   config = PageLocalesConfig.new(SiteConfigAccessor.effective_page_data(page))
+    #   PageTranslationLoader.load(site, 'es', '/docs/index.html', config)
+    #   # => { "Welcome" => "Bienvenido", ... }
     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
+      # @param site [Jekyll::Site] The Jekyll site
+      # @param locale [String] Locale code, e.g. 'es'
+      # @param original_url [String] URL of the English page, e.g. '/docs/index.html'
+      # @param config [PageLocalesConfig] The page's settings (for `locales_dir`)
+      # @return [Hash] msgid => msgstr, without untranslated entries
       def self.load(site, locale, original_url, config)
         po_manager = PoFileManager.new(site, config.locales_dir)
         page_path = construct_po_page_path(original_url)

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../utils/page_locales_config'
+require_relative '../utils/site_config_accessor'
 require_relative '../utils/html_parser'
 require_relative '../utils/logger_formatter'
 require_relative '../utils/error_handler'
@@ -10,65 +11,38 @@ require_relative 'page_translation_loader'
 
 module Jekyll
   module L10n
-    # Translation Orchestrator - Applies PO file translations to localized pages
+    # Translates one localized page right after Jekyll renders it.
     #
-    # 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.
+    # A `:pages, :post_render` hook in lib/jekyll-l10n.rb calls it for every
+    # LocalizedPage. It loads the translations for the page's locale, replaces
+    # the English text and attributes in the rendered HTML, and applies the
+    # page's fallback mode to strings without a translation.
     #
-    # 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
+    # Settings come from the English page's merged `with_locales_data`, so a
+    # page can override, for example, `translation.fallback` for itself.
     #
-    # 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
+    # @example
+    #   Translator.new(localized_page).translate
     #
-    # 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
+    # @see HtmlTranslator changes the HTML
+    # @see PageTranslationLoader reads the PO files
     #
     class Translator
       # @!attribute [r] page
-      #   The Jekyll page being translated
-      #   @return [Jekyll::Page]
+      #   @return [Jekyll::Page] The page being translated
       attr_reader :page
 
-      # Initialize the translator
-      #
-      # @param page [Jekyll::Page] The page to translate (should be a LocalizedPage)
+      # @param page [Jekyll::Page] Usually 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.
+      # Replaces the page output with its translated HTML. Does nothing for
+      # pages without `locale` and `original_url`, pages whose English page
+      # cannot be found, or when there are no translations.
       #
       # @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?
 
@@ -79,21 +53,20 @@ module Jekyll
         original_page = find_and_log_original_page(original_url)
         return unless original_page
 
-        translations = load_and_log_translations(locale, original_url, original_page)
+        config = PageLocalesConfig.new(SiteConfigAccessor.effective_page_data(original_page))
+        translations = load_and_log_translations(locale, original_url, config)
         return if translations.nil? || translations.empty?
 
-        apply_translations_to_page(original_page, translations, locale, baseurl)
+        apply_translations_to_page(original_page, config, translations, locale, baseurl)
       end
 
       private
 
-      def load_translations_for_page(locale, original_url, original_page)
-        config = PageLocalesConfig.new(original_page.data)
+      def load_translations_for_page(locale, original_url, config)
         PageTranslationLoader.load(@site, locale, original_url, config)
       end
 
-      def apply_translations_to_page(original_page, translations, locale, baseurl)
-        config = PageLocalesConfig.new(original_page.data)
+      def apply_translations_to_page(original_page, config, translations, locale, baseurl)
         translator = HtmlTranslator.new(
           config.fallback_mode,
           config.translatable_attributes,
@@ -112,16 +85,11 @@ module Jekyll
         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
+      # @param translator [HtmlTranslator]
+      # @param translations [Hash] msgid => msgstr
+      # @param locale [String, nil] Target locale; nil means "en"
+      # @param baseurl [String] Site baseurl, used when rewriting links
+      # @return [String, nil] Translated HTML, or nil after logging an error
       def apply_translations(translator, translations, locale = nil, baseurl = '')
         if locale && locale != 'en'
           translator.translate(@page.output, translations, locale, baseurl)
@@ -169,8 +137,8 @@ module Jekyll
         original_page
       end
 
-      def load_and_log_translations(locale, original_url, original_page)
-        translations = load_translations_for_page(locale, original_url, original_page)
+      def load_and_log_translations(locale, original_url, config)
+        translations = load_translations_for_page(locale, original_url, config)
         LoggerFormatter.debug_if_enabled('Translator',
                                          "Loaded #{translations&.length || 0} translations")
         translations

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,