jekyll-l10n 1.7.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6934d1bf9c34ff4b1806a1b3dde6c19398ee10d261a7a3aa7925716e63f556f
-  data.tar.gz: fde2a5801b9558384d7d6b0f9854526af3d5759d567cddce5aaa94c9f0873c78
+  metadata.gz: 9fb15328cbef2fac51cff8993c0f7e2eb36487de5471531fbb8fa2b0278bb6a1
+  data.tar.gz: a0600bbcb9b82c6b60ca47d0d73dccc23d90807bbcc5e2134e5ddda53a864dea
 SHA512:
-  metadata.gz: 5fd0cf1f00fdd2a0b986540f4c8aeefd2cff50fac3122b6285a92a9f45b317042b28d8f72d6eadadbdc90e1c283ad792b18edd681000799541b53a75dbdbef92
-  data.tar.gz: ec515247b53374ca812d0195815150276ce39c078356383f667a926ef313ec50fa909b316c90e03f85c3a1ede8b753f399c63542e290b3eda12035cf9b56973a
+  metadata.gz: b80419f2e724e61082cc72e39550d5bcefba0205cb659a3887eb7fb0f1d22ffa90dd3f20570fc90233f32b83cca5347d506098b62651aa86be96fd186f32ec7a
+  data.tar.gz: 8b8700a04de094d68752a6a70c1a20328c6e55ad7a1c70764f8756195b461703598cbf4d58e048224af2ac16df256ad219c8103f5b6112c81b2a3ebfb2f55a3d

data/README.md

@@ -13,4 +13,4 @@ For complete documentation, configuration options, and examples, visit the
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License - see [LICENSE](LICENSE) file for details.

data/lib/jekyll-l10n/extraction/config_loader.rb

@@ -6,19 +6,12 @@ require_relative '../utils/site_config_accessor'
 
 module Jekyll
   module L10n
-    # Loads and validates extraction configuration for files during build.
+    # Finds the settings for a built HTML file during extraction.
     #
-    # ExtractionConfigLoader finds extraction configuration for generated HTML
-    # files by matching them against Jekyll site pages. It validates whether
-    # extraction is enabled and configured for a file, loads page-specific
-    # settings, and identifies files to skip (localized page variants).
-    #
-    # Key responsibilities:
-    # * Match generated HTML files to Jekyll site pages
-    # * Validate that extraction is enabled for a file
-    # * Load page-specific extraction configuration
-    # * Identify localized page variants to skip
-    # * Extract CSS selectors for element exclusion
+    # Extraction works on output files, but settings belong to pages. This
+    # class matches an output file back to its source page and returns that
+    # page's merged settings. It also tells the Extractor which files to skip:
+    # the localized copies under locale folders such as `es/`.
     #
     # @example
     #   loader = ExtractionConfigLoader.new(site, '_site')
@@ -26,22 +19,16 @@ module Jekyll
     #     config = loader.load_page_config(file_path)
     #   end
     class ExtractionConfigLoader
-      # Initialize a new ExtractionConfigLoader.
-      #
-      # @param site [Jekyll::Site] Jekyll site object
-      # @param dest [String] Destination build directory
+      # @param site [Jekyll::Site] The Jekyll site
+      # @param dest [String] The site destination directory
       def initialize(site, dest)
         @site = site
         @dest = dest
       end
 
-      # Check if a file is valid for extraction.
-      #
-      # Matches the file to a Jekyll page and verifies extraction is enabled
-      # for that page in the configuration.
-      #
-      # @param file_path [String] Path to file to check
-      # @return [Boolean] True if file matches a page with extraction enabled
+      # @param file_path [String] Path of a built HTML file
+      # @return [Boolean] true if the file comes from a localized page with at
+      #   least one locale and `extract_on_build` not set to false
       def valid_for_extraction?(file_path)
         page_config = find_page_config_for_file(file_path)
         return false unless page_config
@@ -50,25 +37,18 @@ module Jekyll
         config.enabled? && config.extract_on_build?
       end
 
-      # Load extraction configuration for a file.
-      #
-      # Finds the Jekyll page matching this file and returns its localization
-      # configuration wrapped in PageLocalesConfig.
-      #
-      # @param file_path [String] Path to file
-      # @return [PageLocalesConfig] Localization configuration for the page
+      # @param file_path [String] Path of a built HTML file
+      # @return [PageLocalesConfig] Settings of the page that produced the file
       def load_page_config(file_path)
         page_config = find_page_config_for_file(file_path)
         PageLocalesConfig.new(page_config)
       end
 
-      # Find page configuration for a file.
-      #
-      # Matches a generated file path to a Jekyll page with extraction enabled.
-      # Returns the page's front matter data, or nil if no match found.
+      # Finds the localized page whose output is this file and returns its data
+      # with merged `with_locales_data` (see SiteConfigAccessor.effective_page_data).
       #
-      # @param file_path [String] Path to generated file
-      # @return [Hash, nil] Page front matter data if found, nil otherwise
+      # @param file_path [String] Path of a built HTML file
+      # @return [Hash, nil] The page data, or nil when no localized page matches
       def find_page_config_for_file(file_path)
         @site.pages.each do |page|
           next unless page.data['with_locales'] == true
@@ -76,24 +56,18 @@ module Jekyll
           page_output = page.output_ext ? page.destination('') : page.destination('/')
           next unless file_path.end_with?(page_output.sub(%r{/$}, '/index.html'))
 
-          return page.data
+          return SiteConfigAccessor.effective_page_data(page)
         end
 
         nil
       end
 
-      # Check if a file is a localized page variant that should be skipped.
-      #
-      # Localized pages are generated copies in locale subdirectories that
-      # shouldn't be re-extracted (extraction happens on original pages only).
-      # Since commit 3d2d4cd, country-subtag locales (e.g. es_ES) are written
-      # to BCP 47 hyphenated, lowercased URL directories (e.g. es-es/). Each
-      # configured locale is normalized through LocaleUrlFormatter.to_url_segment
-      # before comparison so both language-only (es) and country-subtag
-      # (es_ES → es-es) locales are correctly recognized.
+      # Localized copies are built from the English pages, so we extract only
+      # from the English files. Locale folders use the URL form of the locale
+      # code (es_ES becomes es-es), so compare against that form.
       #
-      # @param file_path [String] Path to file to check
-      # @return [Boolean] True if file is in a locale subdirectory
+      # @param file_path [String] Path of a built HTML file
+      # @return [Boolean] true if the file is inside a locale folder
       def skip_localized_page?(file_path)
         relative_path = file_path.sub(@dest, '')
 
@@ -101,13 +75,9 @@ module Jekyll
         all_locales.any? { |locale| relative_path.start_with?("/#{LocaleUrlFormatter.to_url_segment(locale)}/") }
       end
 
-      # Extract CSS selectors for element exclusion from configuration.
-      #
-      # Returns CSS selectors of elements to exclude from extraction (e.g.,
-      # script, style, code blocks). Defaults to sensible defaults if not configured.
-      #
-      # @param config [Hash] Page front matter data
-      # @return [Array<String>] CSS selectors for excluded elements
+      # @param config [PageLocalesConfig] The page's settings
+      # @return [Array<String>] CSS selectors of elements to leave out of
+      #   extraction, from `extraction.exclude_selectors` or the defaults below
       def extract_exclude_selectors(config)
         config.data.dig('with_locales_data', 'extraction', 'exclude_selectors') ||
           ['script', 'style', 'code.language-plaintext', 'pre code']

data/lib/jekyll-l10n/extraction/extractor.rb

@@ -10,46 +10,33 @@ require_relative '../utils/error_handler'
 
 module Jekyll
   module L10n
-    # String Extraction Orchestrator - Finds translatable strings in generated HTML
+    # Collects translatable strings from the built site into PO files.
     #
-    # The Extractor is the main entry point for the string extraction workflow. It scans all
-    # generated HTML files after Jekyll's build, identifies translatable content (text nodes
-    # and configurable HTML attributes), and creates or updates GNU Gettext PO files with
-    # the extracted strings.
+    # PostWriteProcessor runs it after Jekyll writes the site. Each build it:
+    # 1. Reads every English HTML file in the destination. It skips locale
+    #    folders such as `es/`.
+    # 2. Writes one PO file per page with the page's text and translatable
+    #    attributes.
+    # 3. Merges those files into one compendium per locale (unless
+    #    `update_compendium` is false). The merge deletes the page files.
+    # 4. Machine-translates the compendia when LibreTranslate is on.
+    # 5. Prints a summary unless `logging.show_statistics` is false.
     #
-    # The extraction workflow:
-    # 1. Scans all HTML files in Jekyll output directory (_site/)
-    # 2. For each HTML file, extracts translatable text and attributes
-    # 3. Normalizes text for consistent matching across builds
-    # 4. Creates or updates page-specific PO files in _locales/ directory
-    # 5. Optionally applies automatic translations via LibreTranslate API
+    # It always processes the whole site. Incremental mode does not affect it.
     #
-    # Key responsibilities:
-    # - Load and validate extraction configuration from pages
-    # - Extract text and attributes from HTML with file location references
-    # - Create and update PO files with extracted strings
-    # - Log extraction statistics and progress
-    # - Coordinate with LibreTranslate for automatic translation
-    #
-    # @example Usage (typically invoked by PostWriteProcessor)
-    #   extractor = Extractor.new(site)
-    #   result = extractor.extract_site
+    # @example
+    #   Extractor.new(site).extract_site
     #   # => { files_processed: 42, strings_extracted: 237, po_files_created: 3 }
     #
-    # @see Jekyll::L10n::ExtractionResultSaver for PO file creation and updates
-    # @see Jekyll::L10n::HtmlStringExtractor for text and attribute extraction
+    # @see ExtractionResultSaver writes and merges the PO files
+    # @see HtmlStringExtractor finds strings in one HTML file
     #
     class Extractor
       # @!attribute [r] site
-      #   The Jekyll site object with generated pages
       #   @return [Jekyll::Site]
       attr_reader :site
 
-      # Initialize the string extractor
-      #
-      # Sets up configuration and result saving infrastructure for extraction.
-      #
-      # @param site [Jekyll::Site] The Jekyll site object
+      # @param site [Jekyll::Site] A site that Jekyll has already written
       def initialize(site)
         @site = site
         @source = SiteConfigAccessor.source(@site)
@@ -58,26 +45,17 @@ module Jekyll
         @result_saver = ExtractionResultSaver.new(@site)
       end
 
-      # Extract all translatable strings from the generated site
+      # Runs all the steps in the class description.
       #
-      # Main entry point for extraction. Scans all HTML files in the build output,
-      # extracts translatable strings and attributes, creates/updates PO files,
-      # and optionally translates strings via LibreTranslate API.
-      #
-      # @return [Hash<Symbol, Integer>] Statistics hash with keys:
-      #   - :files_processed - Number of HTML files processed
-      #   - :strings_extracted - Total strings extracted
-      #   - :po_files_created - Number of PO files created/updated
-      # @example
-      #   result = extractor.extract_site
-      #   puts "Processed #{result[:files_processed]} files"
+      # @return [Hash<Symbol, Integer>] Counts under :files_processed,
+      #   :strings_extracted, and :po_files_created (files created or updated)
       def extract_site
         Jekyll.logger.info 'Localization', 'Extracting translatable strings...'
         start_time = Time.now
         stats = process_all_html_files
         @result_saver.finalize_compendia
         translate_all_compendia
-        ExtractionLogger.log_summary(stats, Time.now - start_time)
+        ExtractionLogger.log_summary(stats, Time.now - start_time) if show_statistics?
         stats
       end
 
@@ -134,6 +112,8 @@ module Jekyll
         extractor.extract(html, @dest, file_path)
       end
 
+      # Machine translation uses the settings of the first localized page that
+      # turns LibreTranslate on, including that page's `locales`.
       def find_libretranslate_config
         return nil unless @site.respond_to?(:pages)
 
@@ -149,6 +129,13 @@ module Jekyll
 
       private
 
+      # The summary covers the whole site, so read the site-wide setting, not a
+      # page's.
+      def show_statistics?
+        site_data = SiteConfigAccessor.extract_locales_data(@site)
+        PageLocalesConfig.new('with_locales_data' => site_data).show_statistics?
+      end
+
       def construct_page_path(file_path)
         file_path.sub("#{@dest}/", '')
       end

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

@@ -3,52 +3,38 @@
 require_relative '../constants'
 require_relative 'regeneration_checker'
 require_relative '../utils/locale_url_formatter'
+require_relative '../utils/site_config_accessor'
 
 module Jekyll
   module L10n
-    # Localized Page Generator - Creates locale-prefixed copies of pages during Jekyll build
+    # Adds a copy of each localizable page for every configured locale.
     #
-    # This is the main Jekyll integration point for the localization plugin. It runs as a
-    # low-priority generator during the Jekyll build process, creating duplicate pages for each
-    # configured locale. Each localized page inherits content and metadata from the source page
-    # but includes locale-prefixed URLs.
+    # This is where the plugin starts in a Jekyll build. For each page with
+    # `with_locales: true`, it reads the page's merged `with_locales_data` (site
+    # defaults plus front matter, see SiteConfigAccessor.page_locales_data) and
+    # adds one LocalizedPage per locale, served under a locale prefix such as
+    # `/es/`. Translation happens later, when Jekyll renders those pages.
     #
-    # Key responsibilities:
-    # - Identify pages marked for localization (with_locales: true)
-    # - Extract configured locales from page front matter
-    # - Create LocalizedPage instances for each locale variant
-    # - Optimize regeneration by skipping unchanged pages
+    # With incremental mode on (`jekyll_l10n.incremental`), RegenerationChecker
+    # decides which copies to rebuild; the Generator protects the output of the
+    # skipped ones from Jekyll's cleanup step.
     #
-    # The generator respects Jekyll's incremental build mode and only regenerates pages when
-    # the source page or configuration has changed, improving rebuild performance.
-    #
-    # @example Usage in Jekyll site configuration
-    #   # _config.yml
-    #   plugins:
-    #     - jekyll-l10n
-    #
-    # @example Marking pages for localization
-    #   # src/page.md
+    # @example Front matter that localizes a page into two locales
     #   ---
     #   with_locales: true
     #   with_locales_data:
-    #     locales: [es, fr, pt, de]
+    #     locales: [es, fr]
     #   ---
     #
     class Generator < Jekyll::Generator
       priority :low
 
-      # Generate localized pages for all marked pages in the Jekyll site
-      #
-      # This method is automatically called by Jekyll during the generate phase.
-      # It iterates through all pages in the site, identifies those marked for localization,
-      # and creates locale-specific variants.
+      # Jekyll calls this once per build. It does nothing when no page has
+      # `with_locales: true`.
       #
-      # Returns early with no output if no pages are marked for localization.
-      #
-      # @param site [Jekyll::Site] The Jekyll site object containing pages to process
+      # @param site [Jekyll::Site] The Jekyll site
       # @return [void]
-      # @see LocalizedPage for details on page structure
+      # @see LocalizedPage
       def generate(site)
         return unless any_pages_to_localize?(site)
 
@@ -61,6 +47,8 @@ module Jekyll
       def generate_localized_pages(site)
         original_pages = site.pages.dup
         checker = Jekyll::L10n::RegenerationChecker.new(site)
+        checker.warn_legacy_config
+        skipped_outputs = []
 
         original_pages.each do |page|
           next unless should_localize_page?(page)
@@ -73,23 +61,37 @@ module Jekyll
             if checker.should_regenerate?(page, locale)
               localized_page = create_localized_page(site, page, locale)
               site.pages << localized_page
+            else
+              skipped_outputs << checker.relative_dest_path(page, locale)
             end
           end
         end
+
+        keep_skipped_outputs(site, skipped_outputs)
+      end
+
+      # Jekyll's cleanup step deletes any output file that no page produced in
+      # this build, which includes skipped localized pages. Listing their output
+      # in site.keep_files keeps it.
+      #
+      # `jekyll serve` reuses the site and this generator between builds, so we
+      # first drop the entries added last time; otherwise they would stay kept
+      # after their page is rebuilt or deleted. We assign a new array because
+      # Jekyll shares the old one with site.config['keep_files'].
+      def keep_skipped_outputs(site, skipped_outputs)
+        previous = @kept_outputs || []
+        site.keep_files = (Array(site.keep_files) - previous) | skipped_outputs
+        @kept_outputs = skipped_outputs
       end
 
       def should_localize_page?(page)
         return false if page.data['localized'] == true
         return false unless page.data['with_locales'] == true
 
-        # Only localize HTML pages - exclude static assets
-        # Check multiple conditions to be safe:
-        # 1. output_ext must be .html
-        # 2. path must not contain common asset directories
+        # Localize HTML pages only, never CSS, JavaScript, or other assets.
         is_html = page.output_ext == '.html'
         is_not_asset = !page.path.match?(%r{/(assets|vendor|node_modules|\..*)/}i)
 
-        # Debug: Log which pages are being skipped
         if !is_html
           Jekyll.logger.debug 'Localization',
                               "Skipping non-HTML: #{page.path} (ext: #{page.output_ext})"
@@ -101,7 +103,7 @@ module Jekyll
       end
 
       def get_page_locales(page)
-        data = page.data['with_locales_data']
+        data = SiteConfigAccessor.page_locales_data(page)
 
         locales = if data.is_a?(Hash)
                     data['locales'] || []
@@ -124,10 +126,6 @@ module Jekyll
         locale.match?(Constants::LOCALE_PATTERN)
       end
 
-      # Check if any pages in the site are marked for localization
-      #
-      # @param site [Jekyll::Site] The Jekyll site object
-      # @return [Boolean] True if at least one page has with_locales set to true
       def any_pages_to_localize?(site)
         site.pages.any? { |page| page.data['with_locales'] == true }
       end

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

@@ -9,43 +9,31 @@ require_relative '../utils/external_link_icon_preserver'
 
 module Jekyll
   module L10n
-    # Applies translations to localized HTML pages after Jekyll build.
+    # Translates the localized HTML files again after extraction.
     #
-    # PostWriteHtmlReprocessor finds all localized HTML pages generated by the
-    # Generator, loads appropriate translations, applies them using HtmlTranslator,
-    # and rewrites the HTML files. It processes pages after Jekyll's standard
-    # build completes, during the post-write phase.
+    # Localized pages are first translated while Jekyll renders them, using the
+    # PO files as they were at the start of the build. Extraction then runs and
+    # may add translations, for example on the first build or through machine
+    # translation. PostWriteProcessor calls this class when extraction wrote PO
+    # files, so this build's output already uses the new translations.
     #
-    # Key responsibilities:
-    # * Find localized HTML pages in the build output
-    # * Load page translations (compendium + page-specific)
-    # * Create HtmlTranslator with proper configuration
-    # * Apply translations to HTML documents
-    # * Preserve external link icons from original HTML
-    # * Write translated HTML back to files
-    # * Handle errors gracefully with logging
+    # It only covers localized pages in `site.pages`. Pages that incremental
+    # mode skipped are not there; they pick up the new translations on the
+    # next build.
     #
     # @example
-    #   reprocessor = PostWriteHtmlReprocessor.new(site)
-    #   reprocessor.reprocess_localized_pages
-    #   # Reads localized HTML, translates, preserves icons, writes back
+    #   PostWriteHtmlReprocessor.new(site).reprocess_localized_pages
     class PostWriteHtmlReprocessor
       attr_reader :site
 
-      # Initialize a new PostWriteHtmlReprocessor.
-      #
-      # @param site [Jekyll::Site] Jekyll site object
+      # @param site [Jekyll::Site] A site that Jekyll has already written
       def initialize(site)
         @site = site
         @dest = SiteConfigAccessor.dest(@site)
       end
 
-      # Reprocess all localized pages with translations.
-      #
-      # Finds all localized HTML pages that were written during the Jekyll build,
-      # loads their translations, applies translations to text and attributes,
-      # preserves external link icon styling from the original HTML, and writes
-      # the translated HTML back to disk.
+      # Reads each localized file, translates it, keeps the external link icons
+      # of the English page, and writes it back.
       #
       # @return [void]
       def reprocess_localized_pages
@@ -86,7 +74,7 @@ module Jekyll
 
         return unless original_page
 
-        config = PageLocalesConfig.new(original_page.data)
+        config = PageLocalesConfig.new(SiteConfigAccessor.effective_page_data(original_page))
         translations = PageTranslationLoader.load(@site, locale, original_url, config)
 
         return if translations.nil? || translations.empty?

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

@@ -3,25 +3,27 @@
 require_relative '../utils/site_config_accessor'
 require_relative '../po_file/path_builder'
 require_relative '../utils/locale_url_formatter'
+require_relative '../utils/url_path_builder'
+require_relative '../utils/logger_formatter'
 
 module Jekyll
   module L10n
-    # Regeneration Checker - Optimizes incremental builds by skipping unchanged pages
+    # Decides whether a localized page needs rebuilding when incremental mode is on.
     #
-    # This class implements incremental build optimization for localized pages. When Jekyll's
-    # incremental build mode is enabled, it checks whether a specific locale variant of a page
-    # needs to be regenerated based on source modification times.
+    # Incremental mode is the plugin's own `jekyll_l10n.incremental` setting, not
+    # `jekyll build --incremental`. When it is on, the checker compares the
+    # previous output file with the files the page depends on, and asks for a
+    # rebuild when any of them is newer: the source page, the page PO file, the
+    # locale compendium, or `_config.yml`.
     #
-    # The checker compares modification times of:
-    # - Source page file
-    # - Page-specific PO translation file
-    # - Compendium (shared translations) PO file
-    # - Jekyll configuration (_config.yml)
+    # Limits to know about:
+    # - It compares modification times, not file contents.
+    # - It looks for PO files under the directory passed to {#initialize}. The
+    #   Generator passes nothing, so a custom `locales_dir` is never checked.
+    # - The page PO file exists only when `update_compendium` is false; the
+    #   compendium merge deletes it otherwise.
     #
-    # If any of these are newer than the output HTML, the page is regenerated.
-    # This significantly speeds up rebuilds when only a few files have changed.
-    #
-    # @example Usage
+    # @example
     #   checker = RegenerationChecker.new(site)
     #   if checker.should_regenerate?(page, 'es')
     #     # Create localized_page and add to site.pages
@@ -31,11 +33,9 @@ module Jekyll
       # @!visibility private
       DEFAULT_LOCALES_DIR = '_locales'
 
-      # Initialize the regeneration checker
-      #
-      # @param site [Jekyll::Site] The Jekyll site object
-      # @param locales_dir [String] Directory containing PO files (defaults to
-      #   DEFAULT_LOCALES_DIR = "_locales")
+      # @param site [Jekyll::Site] The Jekyll site
+      # @param locales_dir [String] Directory, relative to the site source, that
+      #   holds the PO files. Defaults to DEFAULT_LOCALES_DIR.
       def initialize(site, locales_dir = DEFAULT_LOCALES_DIR)
         @site = site
         @locales_dir = locales_dir
@@ -43,20 +43,12 @@ module Jekyll
         @destination = @site&.config&.dig('destination') || ''
       end
 
-      # Determine if a localized page variant should be regenerated
-      #
-      # Returns true if:
-      # - Incremental builds are disabled (always regenerate)
-      # - Output file doesn't exist yet
-      # - Source page has been modified since output was generated
-      # - PO translation files have been modified since output was generated
-      # - Jekyll configuration has been modified since output was generated
-      #
-      # Returns false if incremental builds are enabled and output is up-to-date.
+      # Returns true when incremental mode is off, when the page has no previous
+      # output, or when a file the page depends on is newer than that output.
       #
-      # @param page [Jekyll::Page] The source page to check
-      # @param locale [String] The locale code for the variant (e.g., 'es', 'fr')
-      # @return [Boolean] true if the page should be regenerated, false if output is current
+      # @param page [Jekyll::Page] The source (English) page
+      # @param locale [String] Locale code, e.g. 'es' or 'pt_BR'
+      # @return [Boolean] true if the localized page must be rebuilt
       def should_regenerate?(page, locale)
         return true unless incremental_enabled?
         return true unless dest_path_exists?(page, locale)
@@ -68,16 +60,39 @@ module Jekyll
           config_modified?(dest_mtime)
       end
 
+      # Logs a warning when `_config.yml` still has the old `localization_gettext`
+      # key. The plugin ignores that key, so without the warning a site would
+      # lose incremental mode silently. Call it once per build, not per page.
+      #
+      # @return [void]
+      def warn_legacy_config
+        return unless @site&.config.is_a?(Hash) && @site.config.key?('localization_gettext')
+
+        LoggerFormatter.warn('RegenerationChecker',
+                             'The `localization_gettext` key in _config.yml is ignored. ' \
+                             'Set `jekyll_l10n.incremental` instead.')
+      end
+
+      # Output file of a localized page, relative to the site destination. The
+      # Generator adds it to `site.keep_files` for skipped pages, so Jekyll's
+      # cleanup step does not delete their previous output.
+      #
+      # This must produce the same path as LocalizedPage#destination.
+      #
+      # @param page [Jekyll::Page] The source (English) page
+      # @param locale [String] Locale code, e.g. 'es' or 'pt_BR'
+      # @return [String] Path such as "es/about/index.html" (no leading slash)
+      def relative_dest_path(page, locale)
+        url_locale = LocaleUrlFormatter.to_url_segment(locale)
+        "#{url_locale}#{page.url.chomp('/')}/index.html"
+      end
+
       private
 
       def incremental_enabled?
         return false if @site&.config.nil?
 
-        localization_config = @site.config.dig('localization_gettext', 'with_locales_data',
-                                               'incremental') ||
-                              @site.config.dig('localization_gettext', 'incremental') ||
-                              false
-        localization_config == true
+        @site.config.dig('jekyll_l10n', 'incremental') == true
       end
 
       def dest_path_exists?(page, locale)
@@ -85,26 +100,25 @@ module Jekyll
       end
 
       def dest_path(page, locale)
-        # Replicate LocalizedPage destination logic without instantiation.
-        # Uses BCP 47 hyphenated locale segment to match LocalizedPage#destination output.
-        url_locale = LocaleUrlFormatter.to_url_segment(locale)
-        url = "/#{url_locale}#{page.url.chomp('/')}/"
-        "#{@destination}#{url}index.html"
+        "#{@destination}/#{relative_dest_path(page, locale)}"
       end
 
       def source_modified?(page, dest_mtime)
-        page_mtime = File.mtime(page.path)
+        # Jekyll 4 gives Page#path relative to the site source. Resolve it there,
+        # not against the current directory. An absolute path stays unchanged.
+        page_mtime = File.mtime(File.expand_path(page.path, @source))
         page_mtime > dest_mtime
       rescue StandardError
         true
       end
 
       def po_files_modified?(page, locale, dest_mtime)
-        # Check page-specific PO file
-        page_po_path = PoPathBuilder.build(@source, @locales_dir, locale, page.path)
+        # Use the same page PO path PageTranslationLoader reads, which comes
+        # from the page URL, not from the source file name.
+        po_page_path = UrlPathBuilder.url_to_po_page_path(page.url)
+        page_po_path = PoPathBuilder.build(@source, @locales_dir, locale, po_page_path)
         return true if file_modified?(page_po_path, dest_mtime)
 
-        # Check compendium PO file
         compendium_po_path = PoPathBuilder.build(@source, @locales_dir, locale, nil)
         file_modified?(compendium_po_path, dest_mtime)
       end