jekyll-l10n 1.7.1 → 3.0.0

data/lib/jekyll-l10n/instrumentation.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'jekyll'
+
 module Jekyll
   module L10n
     # OpenTelemetry instrumentation facade for jekyll-l10n.
@@ -7,7 +9,7 @@ module Jekyll
     # All tracing is configured centrally in TRACED_METHODS — no span code lives
     # in business logic classes. To add a span: append one entry. To rename a
     # method: update the one entry. When a method is removed from its class the
-    # stale entry raises NoMethodError in tests, signalling the entry to delete.
+    # stale entry fails the TRACED_METHODS spec, signalling the entry to delete.
     #
     # Requires opentelemetry-api at runtime; falls back to a no-op if absent.
     # Users opt in to real tracing by adding opentelemetry-sdk and
@@ -18,6 +20,161 @@ module Jekyll
     module Instrumentation
       TRACER_NAME = 'jekyll-l10n'
 
+      # -- Entry point -------------------------------------------------------
+
+      # Returns true when OTel is requested via standard environment variables.
+      #
+      # install! guards on this so the prepend wrappers are only applied when
+      # a real exporter is configured. In CI and local tests (no OTel env vars)
+      # business logic classes are untouched, keeping allow_any_instance_of stubs
+      # and other RSpec mechanics fully functional.
+      def self.enabled?
+        ENV.key?('OTEL_EXPORTER_OTLP_ENDPOINT') || ENV.key?('OTEL_SERVICE_NAME')
+      end
+
+      # Installs wrappers on all classes listed in TRACED_METHODS using Module#prepend.
+      #
+      # Called once at plugin load time (end of jekyll-l10n.rb, after all requires),
+      # but only when enabled? returns true. Use OTEL_EXPORTER_OTLP_ENDPOINT or
+      # OTEL_SERVICE_NAME to activate tracing.
+      def self.install!
+        return if @installed
+
+        @installed = true
+        setup_sdk!
+        TRACED_METHODS.group_by { |e| e[0] }.each do |class_name, entries|
+          prepend_wrappers(resolve_class(class_name), entries)
+        end
+      end
+
+      # -- Install phase -----------------------------------------------------
+
+      # Configures the OTel SDK from standard env vars if the SDK gem is available.
+      #
+      # Called from install! so that spans are exported to the configured backend
+      # without requiring sites to add a separate initializer. Silently no-ops when
+      # opentelemetry-sdk or opentelemetry-exporter-otlp is not installed.
+      #
+      # Uses BatchSpanProcessor, which exports from a background thread, so the
+      # build never waits on the collector while a span ends (SimpleSpanProcessor
+      # exports synchronously, inside every traced call — costly here, where each
+      # localized page produces several spans). Spans still reach the collector
+      # before Jekyll exits: the post_write hook below runs after every
+      # :low-or-higher post_write hook, this plugin's :high one included, and
+      # force-flushes the batch; at_exit shuts the provider down, exporting
+      # anything left (e.g. between serve rebuilds).
+      #
+      # jekyll-theme-centos loads several instrumented plugins in one process,
+      # and OpenTelemetry::SDK.configure unconditionally overwrites the global
+      # tracer_provider on every call — so only the first plugin to reach this
+      # method (see sdk_already_configured?) actually configures the SDK; every
+      # later plugin's call becomes a no-op and reuses that provider. The
+      # at_exit and post_write hooks below are therefore registered once, by
+      # whichever plugin wins, and cover every plugin's spans, not just this one's.
+      def self.setup_sdk!
+        return if sdk_already_configured?
+
+        # :nocov:
+        require 'opentelemetry/sdk'
+        require 'opentelemetry/exporter/otlp'
+        exporter  = OpenTelemetry::Exporter::OTLP::Exporter.new
+        processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+        OpenTelemetry::SDK.configure { |c| c.add_span_processor(processor) }
+
+        at_exit { OpenTelemetry.tracer_provider&.shutdown }
+        Jekyll::Hooks.register(:site, :post_write, priority: 0) { OpenTelemetry.tracer_provider&.force_flush }
+      rescue LoadError
+        nil
+        # :nocov:
+      end
+
+      # True when some plugin (this one or another) already installed a real
+      # SDK-backed tracer_provider, in which case setup_sdk! must not run again.
+      def self.sdk_already_configured?
+        defined?(OpenTelemetry::SDK::Trace::TracerProvider) &&
+          OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+      end
+
+      # Resolves a dot-separated class name to a constant; returns nil on NameError.
+      # Public, unlike the other install! helpers, so specs can check TRACED_METHODS entries.
+      def self.resolve_class(name)
+        name.split('::').reduce(Object) { |m, c| m.const_get(c) }
+      rescue NameError
+        nil
+      end
+
+      # Applies instance and class-method wrappers to klass; skips if klass is nil.
+      def self.prepend_wrappers(klass, entries)
+        return unless klass
+
+        class_entries, instance_entries = entries.partition { |e| e[1] == :class }
+        klass.prepend(build_wrapper_module(instance_entries)) unless instance_entries.empty?
+        klass.singleton_class.prepend(build_wrapper_module(class_entries)) unless class_entries.empty?
+      end
+
+      # Builds an anonymous module that wraps each listed method in a span.
+      def self.build_wrapper_module(entries)
+        Module.new do
+          entries.each do |_class_name, method_type, method_name, span_name, attr_proc|
+            define_method(method_name) do |*args, **kwargs, &blk|
+              Instrumentation.instrument(span_name) do |span|
+                result = super(*args, **kwargs, &blk)
+                attr_proc&.call(span, self, args, result)
+                result
+              rescue StandardError => e
+                span.record_exception(e)
+                raise
+              end
+            end
+            private method_name if method_type == :private
+          end
+        end
+      end
+
+      private_class_method :build_wrapper_module, :prepend_wrappers, :setup_sdk!, :sdk_already_configured?
+
+      # -- Runtime API -------------------------------------------------------
+
+      # Returns the active OTel tracer, or a no-op tracer if opentelemetry-api is absent.
+      def self.tracer
+        @tracer ||=
+          if defined?(OpenTelemetry)
+            # :nocov:
+            OpenTelemetry.tracer_provider.tracer(TRACER_NAME, Jekyll::L10n::VERSION)
+            # :nocov:
+          else
+            NoopTracer.new
+          end
+      end
+
+      # Wraps a block in an OTel span.
+      #
+      # @param span_name [String] Dot-separated span name (e.g. 'l10n.extract_page')
+      # @param attributes [Hash] Initial span attributes
+      # @yieldparam span [OpenTelemetry::Trace::Span, NoopSpan] Active span
+      # @return [Object] The return value of the block
+      def self.instrument(span_name, attributes: {}, &block)
+        tracer.in_span(span_name, attributes: attributes, &block)
+      end
+
+      # Thread.new that keeps the caller's trace context, so spans created in
+      # the thread nest under the span that started it. OTel tracks the
+      # current span per thread, and a plain Thread.new starts without one.
+      def self.traced_thread(&block)
+        return Thread.new(&block) unless defined?(OpenTelemetry::Context)
+
+        context = OpenTelemetry::Context.current
+        Thread.new { OpenTelemetry::Context.with_current(context, &block) }
+      end
+
+      # Resets the cached tracer and installation flag. Call in tests after changing OTel configuration.
+      def self.reset!
+        @tracer    = nil
+        @installed = false
+      end
+
+      # -- Registry ----------------------------------------------------------
+
       # Central instrumentation registry.
       #
       # Each row: [class_name, method_type, method_name, span_name, attribute_proc]
@@ -48,7 +205,7 @@ module Jekyll
       end
 
       TRACED_METHODS = [
-        # ── Jekyll integration ────────────────────────────────────────────────
+        # -- Jekyll integration -----------------------------------------------
         ['Jekyll::L10n::Generator', :instance, :generate, 'l10n.generate',
          lambda { |span, _this, args, _result|
            span.set_attribute('l10n.site_page_count', args[0]&.pages&.size || 0)
@@ -64,7 +221,7 @@ module Jekyll
            span.set_attribute('l10n.page_url', this.page.url.to_s)
          }],
 
-        # ── Extraction pipeline ───────────────────────────────────────────────
+        # -- Extraction pipeline ----------------------------------------------
         ['Jekyll::L10n::Extractor', :instance, :extract_site, 'l10n.extract_site',
          lambda { |span, _this, _args, result|
            span.set_attribute('l10n.file_count', Instrumentation.hash_val(result, :files_processed))
@@ -102,7 +259,7 @@ module Jekyll
            span.set_attribute('l10n.locale_count', config.locales.size) if config.respond_to?(:locales)
          }],
 
-        # ── Translation pipeline ──────────────────────────────────────────────
+        # -- Translation pipeline ---------------------------------------------
         ['Jekyll::L10n::PostWriteHtmlReprocessor', :instance, :reprocess_localized_pages,
          'l10n.reprocess_localized_pages', nil],
 
@@ -134,7 +291,7 @@ module Jekyll
            span.set_attribute('l10n.batch_size', args[0].is_a?(Array) ? args[0].size : 1)
          }],
 
-        # ── Utilities ─────────────────────────────────────────────────────────
+        # -- Utilities --------------------------------------------------------
         ['Jekyll::L10n::HtmlParser', :class, :parse_document, 'l10n.html_parse',
          lambda { |span, _this, args, _result|
            span.set_attribute('l10n.html_size_bytes', args[0].bytesize)
@@ -151,7 +308,16 @@ module Jekyll
         ['Jekyll::L10n::ExternalLinkIconPreserver', :class, :preserve,
          'l10n.icon_preserve', nil],
 
-        # ── PO file operations ────────────────────────────────────────────────
+        # reject_invalid runs once per PO file load; valid? runs per entry, too often to trace
+        ['Jekyll::L10n::MsgstrValidator', :class, :reject_invalid, 'l10n.msgstr_validate',
+         lambda { |span, _this, args, result|
+           entry_count = Instrumentation.hash_size(args[0])
+           span.set_attribute('l10n.file_path', args[1].to_s)
+           span.set_attribute('l10n.entry_count', entry_count)
+           span.set_attribute('l10n.invalid_count', entry_count - Instrumentation.hash_size(result))
+         }],
+
+        # -- PO file operations -----------------------------------------------
         ['Jekyll::L10n::PoFileReader', :instance, :parse_for_translation,
          'l10n.po_file_read',
          lambda { |span, this, _args, result|
@@ -167,139 +333,6 @@ module Jekyll
       ].freeze
       # :nocov:
 
-      # Returns the active OTel tracer, or a no-op tracer if opentelemetry-api is absent.
-      def self.tracer
-        @tracer ||=
-          if defined?(OpenTelemetry)
-            # :nocov:
-            OpenTelemetry.tracer_provider.tracer(TRACER_NAME, Jekyll::L10n::VERSION)
-            # :nocov:
-          else
-            NoopTracer.new
-          end
-      end
-
-      # Wraps a block in an OTel span.
-      #
-      # @param span_name [String] Dot-separated span name (e.g. 'l10n.extract_page')
-      # @param attributes [Hash] Initial span attributes
-      # @yieldparam span [OpenTelemetry::Trace::Span, NoopSpan] Active span
-      # @return [Object] The return value of the block
-      def self.instrument(span_name, attributes: {}, &block)
-        tracer.in_span(span_name, attributes: attributes, &block)
-      end
-
-      # Resets the cached tracer and installation flag. Call in tests after changing OTel configuration.
-      def self.reset!
-        @tracer    = nil
-        @installed = false
-      end
-
-      # Returns true when OTel is requested via standard environment variables.
-      #
-      # install! guards on this so the prepend wrappers are only applied when
-      # a real exporter is configured. In CI and local tests (no OTel env vars)
-      # business logic classes are untouched, keeping allow_any_instance_of stubs
-      # and other RSpec mechanics fully functional.
-      def self.enabled?
-        ENV.key?('OTEL_EXPORTER_OTLP_ENDPOINT') || ENV.key?('OTEL_SERVICE_NAME')
-      end
-
-      # Installs wrappers on all classes listed in TRACED_METHODS using Module#prepend.
-      #
-      # Called once at plugin load time (end of jekyll-l10n.rb, after all requires),
-      # but only when enabled? returns true. Use OTEL_EXPORTER_OTLP_ENDPOINT or
-      # OTEL_SERVICE_NAME to activate tracing.
-      def self.install!
-        return if @installed
-
-        @installed = true
-        setup_sdk!
-        TRACED_METHODS.group_by { |e| e[0] }.each do |class_name, entries|
-          prepend_wrappers(resolve_class(class_name), entries)
-        end
-      end
-
-      # Configures the OTel SDK from standard env vars if the SDK gem is available.
-      #
-      # Called from install! so that spans are exported to the configured backend
-      # without requiring sites to add a separate initializer. Silently no-ops when
-      # opentelemetry-sdk or opentelemetry-exporter-otlp is not installed.
-      #
-      # SimpleSpanProcessor is used instead of the SDK default (BatchSpanProcessor)
-      # because Jekyll is a short-lived CLI process. BatchSpanProcessor exports on a
-      # 5-second schedule; outer spans that close last (post_write, generate) are
-      # silently dropped when the process exits before the next flush. Simple exports
-      # each span synchronously the moment it closes, guaranteeing no span loss.
-      #
-      # jekyll-theme-centos loads several instrumented plugins in one process,
-      # and OpenTelemetry::SDK.configure unconditionally overwrites the global
-      # tracer_provider on every call — so only the first plugin to reach this
-      # method (see sdk_already_configured?) actually configures the SDK; every
-      # later plugin's call becomes a no-op and reuses that provider. The
-      # at_exit and post_write hooks below are therefore registered once, by
-      # whichever plugin wins, and cover every plugin's spans, not just this one's.
-      def self.setup_sdk!
-        return if sdk_already_configured?
-
-        # :nocov:
-        require 'opentelemetry/sdk'
-        require 'opentelemetry/exporter/otlp'
-        exporter  = OpenTelemetry::Exporter::OTLP::Exporter.new
-        processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter)
-        OpenTelemetry::SDK.configure { |c| c.add_span_processor(processor) }
-
-        at_exit { OpenTelemetry.tracer_provider&.shutdown }
-        Jekyll::Hooks.register(:site, :post_write, priority: 0) { OpenTelemetry.tracer_provider&.force_flush }
-      rescue LoadError
-        nil
-        # :nocov:
-      end
-
-      # True when some plugin (this one or another) already installed a real
-      # SDK-backed tracer_provider, in which case setup_sdk! must not run again.
-      def self.sdk_already_configured?
-        defined?(OpenTelemetry::SDK::Trace::TracerProvider) &&
-          OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
-      end
-
-      # Resolves a dot-separated class name to a constant; returns nil on NameError.
-      def self.resolve_class(name)
-        name.split('::').reduce(Object) { |m, c| m.const_get(c) }
-      rescue NameError
-        nil
-      end
-
-      # Applies instance and class-method wrappers to klass; skips if klass is nil.
-      def self.prepend_wrappers(klass, entries)
-        return unless klass
-
-        class_entries, instance_entries = entries.partition { |e| e[1] == :class }
-        klass.prepend(build_wrapper_module(instance_entries)) unless instance_entries.empty?
-        klass.singleton_class.prepend(build_wrapper_module(class_entries)) unless class_entries.empty?
-      end
-
-      # Builds an anonymous module that wraps each listed method in a span.
-      def self.build_wrapper_module(entries)
-        Module.new do
-          entries.each do |_class_name, method_type, method_name, span_name, attr_proc|
-            define_method(method_name) do |*args, **kwargs, &blk|
-              Instrumentation.instrument(span_name) do |span|
-                result = super(*args, **kwargs, &blk)
-                attr_proc&.call(span, self, args, result)
-                result
-              rescue StandardError => e
-                span.record_exception(e)
-                raise
-              end
-            end
-            private method_name if method_type == :private
-          end
-        end
-      end
-
-      private_class_method :build_wrapper_module, :prepend_wrappers, :setup_sdk!, :sdk_already_configured?
-
       # No-op tracer used when opentelemetry-api is not loaded.
       class NoopTracer
         def in_span(_name, **_opts)

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

@@ -1,58 +1,46 @@
 # frozen_string_literal: true
 
+require_relative '../configuration'
 require_relative '../constants'
 require_relative 'regeneration_checker'
 require_relative '../utils/locale_url_formatter'
+require_relative '../utils/page_locales_config'
+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.
-      #
-      # Returns early with no output if no pages are marked for localization.
+      # Jekyll calls this once per build. It does nothing when no page has
+      # `with_locales: true`.
       #
-      # @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)
 
-        Jekyll.logger.info 'Localization', 'Generating localized pages...'
+        Jekyll.logger.info Constants::LOG_PREFIX, 'Generating localized pages...'
         generate_localized_pages(site)
       end
 
@@ -61,6 +49,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)
@@ -68,48 +58,54 @@ module Jekyll
           locales = get_page_locales(page)
 
           locales.each do |locale|
-            next unless valid_locale_code?(locale)
-
             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
+        return false unless Configuration.localizable?(page)
 
-        # 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',
+          Jekyll.logger.debug Constants::LOG_PREFIX,
                               "Skipping non-HTML: #{page.path} (ext: #{page.output_ext})"
         elsif !is_not_asset
-          Jekyll.logger.debug 'Localization', "Skipping asset: #{page.path}"
+          Jekyll.logger.debug Constants::LOG_PREFIX, "Skipping asset: #{page.path}"
         end
 
         is_html && is_not_asset
       end
 
+      # Configuration::Schema has already dropped bad locale codes, with a
+      # warning, so the page is built for its other locales.
       def get_page_locales(page)
-        data = page.data['with_locales_data']
-
-        locales = if data.is_a?(Hash)
-                    data['locales'] || []
-                  else
-                    []
-                  end
-
-        locales.select { |l| valid_locale_code?(l) }
+        PageLocalesConfig.new(SiteConfigAccessor.effective_page_data(page)).locales
       end
 
       def create_localized_page(site, page, locale)
@@ -118,18 +114,8 @@ module Jekyll
                           locale: locale)
       end
 
-      def valid_locale_code?(locale)
-        return false unless locale.is_a?(String)
-
-        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 }
+        site.pages.any? { |page| Configuration.localizable?(page) }
       end
     end
   end

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

@@ -39,7 +39,13 @@ module Jekyll
       # @!attribute [rw] original_url
       #   The URL of the source page before locale prefix was added
       #   @return [String]
-      attr_accessor :locale, :lang, :original_page, :original_url
+      # @!attribute [rw] translations_digest
+      #   Digest of the translations hash the page was rendered with. Set by
+      #   Translator after a successful translation; read by PostWriteHtmlReprocessor
+      #   to skip pages whose translations have not changed since the render pass.
+      #   Instance attribute only — must not leak into Liquid.
+      #   @return [Integer, nil]
+      attr_accessor :locale, :lang, :original_page, :original_url, :translations_digest
 
       # Initialize a new localized page variant
       #
@@ -81,62 +87,34 @@ module Jekyll
         setup_localized_data(page, locale)
       end
 
-      # Get the URL placeholder substitutions for this localized page
-      #
-      # Overrides Jekyll::Page's url_placeholders to include the locale prefix in path generation.
-      # The locale segment is converted to BCP 47 hyphenated form for use in URLs.
-      # This ensures that Jekyll's permalink logic respects the locale prefix.
-      #
-      # @return [Hash<Symbol, String>] Hash of placeholders with locale-prefixed path
-      def url_placeholders
-        placeholders = super
-        if placeholders[:path]
-          url_locale = LocaleUrlFormatter.to_url_segment(@locale)
-          placeholders[:path] = "/#{url_locale}#{placeholders[:path]}"
-        end
-        placeholders
-      end
-
       # Get the full URL for this localized page
       #
-      # Returns the page's URL with a locale prefix in BCP 47 hyphenated form.
-      # For example, if the source page URL is '/path/to/page/', this returns
-      # '/es-ES/path/to/page/' for locale 'es_ES'.
-      # For HTML pages, URLs end with a trailing slash. For assets, the file extension is preserved.
+      # The English page's URL with the locale segment (BCP 47 hyphenated form)
+      # in front, and nothing else changed: the page's permalink decides the
+      # URL's shape, so '/about', '/about/' and '/about.html' become
+      # '/es-es/about', '/es-es/about/' and '/es-es/about.html' for 'es_ES'.
+      # Jekyll::Page#destination then writes the page where that URL says, by
+      # the same rule as the English page.
       #
-      # @return [String] The locale-prefixed URL with optional trailing slash
-      #   (e.g., '/es-ES/path/to/page/' or '/es-ES/assets/style.css')
+      # @return [String] The locale-prefixed URL
       def url
-        url_locale = LocaleUrlFormatter.to_url_segment(@locale)
-        url = "/#{url_locale}#{@original_url}"
-        # Only add trailing slash for directory URLs (no file extension)
-        url += '/' unless url.end_with?('/') || url =~ /\.[a-zA-Z0-9]+$/
-        url
+        "/#{LocaleUrlFormatter.to_url_segment(@locale)}#{@original_url}"
       end
 
-      # Get the destination file path for this localized page
+      # Write the page, replacing the empty directory an earlier release left
+      # at its path.
       #
-      # Computes the full file system path where this page's content will be written.
-      # For HTML pages with URL '/es-ES/path/to/page/', this returns
-      # 'dest/es-ES/path/to/page/index.html'.
-      # For assets with URL '/es-ES/assets/style.css', this returns
-      # 'dest/es-ES/assets/style.css'.
+      # Earlier releases wrote a page whose URL ends in a file name to a
+      # directory of that name (es/nav.html/index.html). Jekyll's cleanup
+      # removes the old file but keeps the directory, because the new file
+      # has the same path.
       #
-      # @param dest [String, nil] The destination directory (defaults to nil, which uses
-      #   site config destination)
-      # @return [String] The full file system path for the output file
-      def destination(dest = nil)
-        dest ||= @site.config['destination']
-        url_path = url
-
-        # Only use index.html for HTML pages
-        if @output_ext == '.html'
-          url_path += '/' unless url_path.end_with?('/')
-          "#{dest}#{url_path}index.html"
-        else
-          # For assets, preserve the file extension
-          "#{dest}#{url_path}"
-        end
+      # @param dest [String] The destination directory
+      # @return [void]
+      def write(dest)
+        path = destination(dest)
+        Dir.rmdir(path) if File.directory?(path) && Dir.empty?(path)
+        super
       end
 
       # Convert this localized page to Liquid template data