jekyll-l10n 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8edcdac30ed6d89b587d914f1b8038ffd3b10a95a0e15cc43965dd915e39f2
-  data.tar.gz: 513218e1e01c3814a2f7130f60a6b35463d0836659ee13d85ae3d7c9a0aaf6c5
+  metadata.gz: a3b778612621ba8532ed88057a833cebfb615d4e7dfeb09befb9f58249896a5b
+  data.tar.gz: 399997d1222baaeeea243b1cc61638b169e797d72da8cc543c3949f8b63b5f4b
 SHA512:
-  metadata.gz: 24586cc374d7ad819cbda298c98d9dc70438b60bc7afafcc6d695190bb62dc6294ddfd4bb02fb4f04c57c3231cea3fe12047dc9bdf3eb0de5390c6e4fb7a0970
-  data.tar.gz: f5f5bb5755c8354794fd81090c74c0519f06fb15c216cc1b9ba748e5837dcef7b7a05c324d5f67feef8c544884e17a936d492c76132ac26cb7f0d6f0bafa22e6
+  metadata.gz: 122a6388d40c31898704cf3f91b96ef226d30fd9a8b706e7a68d0639bab07042d2707809ecd5076b2d84c79384824cca7964582bd4f931f4a26c95cedd4c567f
+  data.tar.gz: 6de61435ff7b179e62e1c7b3dbf705f6a8059a8b5b3f7158f9e2542145ddf3f391493b0a3e2dcff729c142d500658a0ce98815f514449aa27edfbcde4fe73566

data/lib/jekyll-l10n/constants.rb

@@ -24,6 +24,13 @@ module Jekyll
       # @return [Regexp]
       LOCALE_PATTERN = /^[a-z]{2}(_[A-Z]{2})?$/.freeze
 
+      # Regex fragment for matching locale codes in URL path segments.
+      # Accepts both underscore ('pt_BR') and hyphen ('zh-CN') subtag separators,
+      # unlike LOCALE_PATTERN which only accepts underscore (strict validation form).
+      # Compose into full path patterns rather than using standalone.
+      # @return [String]
+      LOCALE_CODE_SEGMENT = '[a-z]{2}(?:[_-][A-Z]{2})?'
+
       # ## Translation Fallback Modes
 
       # Fallback mode: use original English text if translation not found
@@ -44,6 +51,16 @@ module Jekyll
       # @return [String] "[UNTRANSLATED]"
       UNTRANSLATED_MARKER = '[UNTRANSLATED]'
 
+      # Minimum similarity score (0.0–1.0) for fuzzy matching old translations to
+      # changed msgids. Mirrors GNU msgmerge default. Set to 1.0 to disable.
+      # @return [Float] 0.6
+      DEFAULT_FUZZY_THRESHOLD = 0.6
+
+      # Maximum msgid character length above which fuzzy matching is skipped.
+      # Long strings are typically unique HTML fragments; Levenshtein cost is O(n²).
+      # @return [Integer] 400
+      MAX_FUZZY_MSGID_LENGTH = 400
+
       # ## PO File Formatting (GNU Gettext Standard)
 
       # Line length threshold below which strings are rendered on a single line
@@ -99,6 +116,12 @@ module Jekyll
       # @return [Array<String>] ["title", "alt", "aria-label", "placeholder", "aria-description"]
       DEFAULT_TRANSLATABLE_ATTRIBUTES = %w[title alt aria-label placeholder aria-description].freeze
 
+      # Structural/styling attributes restored from the source DOM at render time.
+      # These are never read from msgstr — always sourced from original HTML.
+      # Prevents MT-corrupted class strings from reaching the rendered page.
+      # @return [Array<String>]
+      STRUCTURAL_PASSTHROUGH_ATTRS = %w[class style id target rel tabindex aria-hidden].freeze
+
       # ## LibreTranslate Integration Defaults
 
       # Default LibreTranslate API endpoint URL

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require_relative '../po_file/manager'
+require_relative '../po_file/fuzzy_matcher'
 require_relative '../utils/page_locales_config'
 require_relative '../utils/site_config_accessor'
 
@@ -84,10 +86,11 @@ module Jekyll
         end
       end
 
-      # Load existing compendium translations or return empty hash if not found
+      # Load existing compendium translations or return empty hash if not found.
+      # Uses parse_for_merge to preserve fuzzy flags from previous runs.
       def load_existing_compendium(compendium_path)
         if File.exist?(compendium_path)
-          PoFileReader.parse_with_references(compendium_path)
+          PoFileReader.parse_for_merge(compendium_path)
         else
           {}
         end
@@ -102,24 +105,54 @@ module Jekyll
         combined
       end
 
-      # Normalize entry format to ensure consistent hash structure with :msgstr and :reference keys
+      # Normalize entry format to ensure consistent hash structure with :msgstr and :reference keys.
+      # Fuzzy metadata is preserved when present so it survives subsequent compendium reads.
       def normalize_compendium_entry(data)
         if data.is_a?(Hash)
-          { msgstr: data[:msgstr], reference: data[:reference] }
+          entry = { msgstr: data[:msgstr], reference: data[:reference] }
+          entry[:fuzzy] = data[:fuzzy] if data[:fuzzy]
+          entry[:previous_msgid] = data[:previous_msgid] if data[:previous_msgid]
+          entry
         else
           { msgstr: data, reference: nil }
         end
       end
 
-      # Merge newly found translations into combined hash, preserving existing translations
+      # Merge newly found translations into combined hash, preserving existing translations.
+      # Applies Levenshtein fuzzy matching for changed msgids: when a new msgid closely
+      # resembles an old compendium entry, the old entry is replaced by a fuzzy-marked new
+      # entry carrying the old translation as a hint. Old entries without a new fuzzy match
+      # stay in the combined hash (they may belong to pages not extracted in this build).
       def merge_into_combined(combined, merged)
+        new_msgids = merged.keys.to_set
+        fuzzy_candidates = compendium_fuzzy_candidates(combined, new_msgids)
+        matched_old_msgids = []
+
         merged.each do |msgid, entry|
           if combined[msgid]
             update_entry_reference(combined[msgid], entry)
           else
-            combined[msgid] = create_new_entry(entry)
+            resolve_new_entry(combined, msgid, entry, fuzzy_candidates, matched_old_msgids)
           end
         end
+
+        matched_old_msgids.each { |old_msgid| combined.delete(old_msgid) }
+      end
+
+      def compendium_fuzzy_candidates(combined, new_msgids)
+        combined.reject do |msgid, entry|
+          new_msgids.include?(msgid) || PoFuzzyMatcher.msgstr_from_entry(entry).empty?
+        end
+      end
+
+      def resolve_new_entry(combined, msgid, entry, fuzzy_candidates, matched_old_msgids)
+        match = PoFuzzyMatcher.find_match(msgid, fuzzy_candidates)
+        if match
+          combined[msgid] = create_fuzzy_entry(entry, match)
+          matched_old_msgids << match[:msgid]
+        else
+          combined[msgid] = create_new_entry(entry)
+        end
       end
 
       # Update reference for existing entry if new reference is available
@@ -138,11 +171,24 @@ module Jekyll
         end
       end
 
-      # Convert combined hash to array of entries suitable for PO file writing
+      # Create a fuzzy entry for a changed msgid, carrying the old translation as a hint
+      def create_fuzzy_entry(entry, match)
+        {
+          msgstr: match[:msgstr],
+          reference: entry.is_a?(Hash) ? entry[:reference] : nil,
+          fuzzy: true,
+          previous_msgid: match[:msgid]
+        }
+      end
+
+      # Convert combined hash to array of entries suitable for PO file writing.
+      # Fuzzy metadata is included so PoFileWriter can serialize #, fuzzy and #| msgid.
       def format_compendium_entries(combined)
         combined.map do |msgid, data|
           entry = { msgid: msgid, msgstr: data[:msgstr] }
-          entry[:reference] = data[:reference] if data[:reference]
+          entry[:reference]     = data[:reference]     if data[:reference]
+          entry[:fuzzy]         = data[:fuzzy]         if data[:fuzzy]
+          entry[:previous_msgid] = data[:previous_msgid] if data[:previous_msgid]
           entry
         end
       end
@@ -156,8 +202,9 @@ module Jekyll
 
       private :process_locale, :compendium_unchanged?, :load_existing_compendium,
               :build_combined_hash, :normalize_compendium_entry, :merge_into_combined,
-              :update_entry_reference, :create_new_entry, :format_compendium_entries,
-              :cleanup_locale_directory
+              :compendium_fuzzy_candidates, :resolve_new_entry,
+              :update_entry_reference, :create_new_entry, :create_fuzzy_entry,
+              :format_compendium_entries, :cleanup_locale_directory
     end
   end
 end

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

@@ -72,7 +72,7 @@ module Jekyll
                                          "Processing compendium file: #{compendium_path}")
         return unless File.exist?(compendium_path)
 
-        entries = PoFileReader.parse_with_references(compendium_path)
+        entries = PoFileReader.parse_for_merge(compendium_path)
         po_entries = PoEntryConverter.hash_to_po_entry_array(entries)
 
         log_compendium_stats(locale, po_entries, compendium_path)

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

@@ -52,11 +52,12 @@ module Jekyll
       end
 
       def extractable?(node)
-        node.element? && HtmlTextUtils::CONTENT_ELEMENTS.include?(node.name)
+        HtmlTextUtils.extractable?(node)
       end
 
       def extract_block_text(node)
         return nil if only_contains_block_elements?(node)
+        return nil if HtmlTextUtils.layout_block_children?(node)
 
         text = HtmlTextUtils.extract_with_inline_tags(node)
         TextValidator.valid?(text) ? text : nil

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

@@ -75,6 +75,7 @@ module Jekyll
         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)
         stats

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../utils/error_handler'
+
 module Jekyll
   module L10n
     # Logs extraction process errors and summary statistics.
@@ -22,7 +24,7 @@ module Jekyll
       # @param error [StandardError] The error that occurred
       # @return [void]
       def self.log_error(file_path, error)
-        Jekyll.logger.error 'Localization', "Error extracting from #{file_path}: #{error.message}"
+        ErrorHandler.log_error("extracting from #{file_path}", error)
       end
 
       # Log extraction completion summary.

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

@@ -63,6 +63,19 @@ module Jekyll
         }
       end
 
+      # Merge all page-specific PO files into compendia after all pages are extracted.
+      #
+      # Called once per build (from Extractor.extract_site) rather than per page,
+      # reducing disk I/O and fuzzy-matching passes from O(pages) to O(1).
+      #
+      # @return [void]
+      def finalize_compendia
+        return unless @site_config.update_compendium?
+
+        po_manager = PoFileManager.new(@site, @site_config.locales_dir)
+        CompendiumMerger.new(@site).merge_compendia(po_manager, @site_config)
+      end
+
       # Translate compendia using LibreTranslate.
       #
       # If LibreTranslate is enabled in config, translates all empty entries in
@@ -84,8 +97,6 @@ module Jekyll
           po_files_created += 1 if po_manager.save_po_file(locale, entries, page_path: page_path)
         end
 
-        CompendiumMerger.new(@site).merge_compendia(po_manager, config) if config.update_compendium?
-
         po_files_created
       end
 

data/lib/jekyll-l10n/instrumentation.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # OpenTelemetry instrumentation facade for jekyll-l10n.
+    #
+    # 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.
+    #
+    # Requires opentelemetry-api at runtime; falls back to a no-op if absent.
+    # Users opt in to real tracing by adding opentelemetry-sdk and
+    # opentelemetry-exporter-otlp to their site Gemfile and exporting:
+    #
+    #   OTEL_SERVICE_NAME=jekyll-l10n
+    #   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+    module Instrumentation
+      TRACER_NAME = 'jekyll-l10n'
+
+      # Central instrumentation registry.
+      #
+      # Each row: [class_name, method_type, method_name, span_name, attribute_proc]
+      #
+      # method_type:
+      #   :instance  — public instance method
+      #   :private   — private instance method (visibility is preserved on the wrapper)
+      #   :class     — class / module method (prepended on the singleton class)
+      #
+      # attribute_proc: ->(span, this, args, result) or nil
+      #   span   — OTel span (or NoopSpan); call span.set_attribute after super returns
+      #   this   — receiver object (instance or nil for class methods)
+      #   args   — positional args array as passed to the method
+      #   result — return value of the original method
+      # :nocov: — attribute procs are configuration data; coverage comes from integration tests
+
+      # Helpers for common attribute patterns used inside TRACED_METHODS procs.
+      def self.hash_val(hash, key)
+        hash.is_a?(Hash) ? hash[key].to_i : 0
+      end
+
+      def self.hash_size(hash)
+        hash.is_a?(Hash) ? hash.size : 0
+      end
+
+      def self.array_size(val)
+        val.is_a?(Array) ? val.size : 0
+      end
+
+      TRACED_METHODS = [
+        # ── 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)
+         }],
+
+        ['Jekyll::L10n::PostWriteProcessor', :instance, :process_localizations,
+         'l10n.post_write', nil],
+
+        # translate is the post_render hook entry point — one span per localized page
+        ['Jekyll::L10n::Translator', :instance, :translate, 'l10n.translate_render',
+         lambda { |span, this, _args, _result|
+           span.set_attribute('l10n.locale', this.page.data['locale'].to_s)
+           span.set_attribute('l10n.page_url', this.page.url.to_s)
+         }],
+
+        # ── 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))
+         }],
+
+        # process_file is the per-page body called from the html_files loop
+        ['Jekyll::L10n::Extractor', :private, :process_file, 'l10n.extract_page',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.page_path', args[0].to_s)
+           span.set_attribute('l10n.strings_extracted',
+                              Instrumentation.hash_val(result, :strings_extracted))
+         }],
+
+        ['Jekyll::L10n::HtmlStringExtractor', :instance, :extract, 'l10n.html_extract',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.html_size_bytes', args[0].bytesize)
+           span.set_attribute('l10n.extracted_count', Instrumentation.array_size(result))
+         }],
+
+        ['Jekyll::L10n::ExtractionResultSaver', :instance, :save_results, 'l10n.po_file_write',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.page_path', args[2].to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.array_size(args[1]))
+           span.set_attribute('l10n.po_files_created',
+                              Instrumentation.hash_val(result, :po_files_created))
+         }],
+
+        ['Jekyll::L10n::CompendiumMerger', :instance, :merge_compendia,
+         'l10n.compendium_merge', nil],
+
+        ['Jekyll::L10n::CompendiumTranslator', :instance, :translate_compendia,
+         'l10n.translate_compendia',
+         lambda { |span, _this, args, _result|
+           config = args[0]
+           span.set_attribute('l10n.locale_count', config.locales.size) if config.respond_to?(:locales)
+         }],
+
+        # ── Translation pipeline ──────────────────────────────────────────────
+        ['Jekyll::L10n::PostWriteHtmlReprocessor', :instance, :reprocess_localized_pages,
+         'l10n.reprocess_localized_pages', nil],
+
+        # translate_html_file is the per-page body called from the localized_files loop
+        ['Jekyll::L10n::PostWriteHtmlReprocessor', :private, :translate_html_file,
+         'l10n.translate_page',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.page_path', args[0].to_s)
+           span.set_attribute('l10n.locale', args[1].to_s)
+         }],
+
+        ['Jekyll::L10n::PageTranslationLoader', :class, :load, 'l10n.translation_load',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           span.set_attribute('l10n.page_path', args[2].to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.hash_size(result))
+         }],
+
+        ['Jekyll::L10n::HtmlTranslator', :instance, :translate, 'l10n.dom_translate',
+         lambda { |span, this, args, _result|
+           span.set_attribute('l10n.locale', (args[2] || 'en').to_s)
+           span.set_attribute('l10n.fallback_mode', this.fallback_mode.to_s)
+         }],
+
+        ['Jekyll::L10n::LibreTranslator', :private, :make_api_request,
+         'l10n.libretranslate_batch',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           span.set_attribute('l10n.batch_size', args[0].is_a?(Array) ? args[0].size : 1)
+         }],
+
+        # ── 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)
+         }],
+
+        ['Jekyll::L10n::UrlTransformer', :class, :transform_document, 'l10n.url_transform',
+         lambda { |span, _this, args, _result|
+           span.set_attribute('l10n.locale', args[1].to_s)
+           doc = args[0]
+           span.set_attribute('l10n.href_count',
+                              doc.respond_to?(:css) ? doc.css('a[href]').size : 0)
+         }],
+
+        ['Jekyll::L10n::ExternalLinkIconPreserver', :class, :preserve,
+         'l10n.icon_preserve', nil],
+
+        # ── PO file operations ────────────────────────────────────────────────
+        ['Jekyll::L10n::PoFileReader', :instance, :parse_for_translation,
+         'l10n.po_file_read',
+         lambda { |span, this, _args, result|
+           span.set_attribute('l10n.file_path', this.po_path.to_s)
+           span.set_attribute('l10n.entry_count', Instrumentation.hash_size(result))
+         }],
+
+        ['Jekyll::L10n::PoFileMerger', :class, :merge_for_locale, 'l10n.po_merge',
+         lambda { |span, _this, args, result|
+           span.set_attribute('l10n.locale', args[2].to_s)
+           span.set_attribute('l10n.merged_count', Instrumentation.hash_size(result))
+         }]
+      ].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.
+      def self.setup_sdk!
+        # :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 do |c|
+          c.add_span_processor(processor)
+        end
+      rescue LoadError
+        nil
+        # :nocov:
+      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!
+
+      # No-op tracer used when opentelemetry-api is not loaded.
+      class NoopTracer
+        def in_span(_name, **_opts)
+          yield NoopSpan.new
+        end
+      end
+
+      # No-op span that silently accepts all attribute and event calls.
+      class NoopSpan
+        def set_attribute(*)
+          self
+        end
+
+        def record_exception(*)
+          self
+        end
+
+        def status=(*); end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../constants'
 require_relative 'regeneration_checker'
 
 module Jekyll
@@ -119,7 +120,7 @@ module Jekyll
       def valid_locale_code?(locale)
         return false unless locale.is_a?(String)
 
-        locale.match?(/^[a-z]{2}(_[A-Z]{2})?$/)
+        locale.match?(Constants::LOCALE_PATTERN)
       end
 
       # Check if any pages in the site are marked for localization

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'liquid'
+require_relative '../constants'
+require_relative '../utils/error_handler'
 
 module Jekyll
   module L10n
@@ -99,7 +101,7 @@ module Jekyll
           page&.data&.[]('locale')
         end
       rescue StandardError => e
-        Jekyll.logger.warn 'Localization', "Error retrieving current locale: #{e.message}"
+        ErrorHandler.log_warning('retrieving current locale', e)
         nil
       end
 
@@ -124,7 +126,7 @@ module Jekyll
       end
 
       def already_localized?(url_str)
-        %r!^/[a-z]{2}(?:[_-][A-Z]{2})?(?=/|\?)!.match?(url_str)
+        %r{^/#{Constants::LOCALE_CODE_SEGMENT}(?=/|\?)}o.match?(url_str)
       end
 
       def external_url?(url_str)
@@ -192,7 +194,7 @@ module Jekyll
 
       def strip_locale_from_url(url)
         # Strip leading locale prefix like /es/, /fr/, /pt_BR/, /zh-CN/
-        url.sub(%r!^/([a-z]{2}(?:[_-][A-Z]{2})?)(?=/|$)!, '')
+        url.sub(%r{^/(#{Constants::LOCALE_CODE_SEGMENT})(?=/|$)}o, '')
       end
     end
   end