jekyll-l10n 1.7.0 → 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/po_file/reader.rb

@@ -297,7 +297,7 @@ module Jekyll
       end
 
       # Unified metadata extraction: extracts reference, fuzzy flag, and previous msgid.
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def self.extract_metadata_before_msgid(lines, msgid_idx, include_fuzzy: false)
         reference      = nil
         fuzzy          = false
@@ -317,7 +317,6 @@ module Jekyll
 
         include_fuzzy ? [reference, fuzzy, previous_msgid] : reference
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def self.extract_reference_from_line(comment_line)
         comment_line.sub(/^#:\s*/, '').strip if comment_line.start_with?('#:')
@@ -457,7 +456,7 @@ module Jekyll
                                                       previous_msgid, with_metadata: with_metadata)
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def self.build_translation_entry(msgstr, reference, fuzzy, previous_msgid = nil,
                                        with_metadata: false)
         # Simple format when no metadata requested and none provided
@@ -471,7 +470,6 @@ module Jekyll
         entry[:comment]        = nil if !fuzzy.nil? || !reference.nil?
         entry
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Kept for backward compatibility with existing tests
       # Supports both positional and keyword argument calling styles

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