jekyll-l10n 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8edcdac30ed6d89b587d914f1b8038ffd3b10a95a0e15cc43965dd915e39f2
-  data.tar.gz: 513218e1e01c3814a2f7130f60a6b35463d0836659ee13d85ae3d7c9a0aaf6c5
+  metadata.gz: 21d081d43cd7503f98fb38d64526397eaf5ff3164e0eb3d6525aa8d88290b9d7
+  data.tar.gz: 382bb065f52fed1d762c2cd5110afc349de73a4780d564f813e8a7be4929373b
 SHA512:
-  metadata.gz: 24586cc374d7ad819cbda298c98d9dc70438b60bc7afafcc6d695190bb62dc6294ddfd4bb02fb4f04c57c3231cea3fe12047dc9bdf3eb0de5390c6e4fb7a0970
-  data.tar.gz: f5f5bb5755c8354794fd81090c74c0519f06fb15c216cc1b9ba748e5837dcef7b7a05c324d5f67feef8c544884e17a936d492c76132ac26cb7f0d6f0bafa22e6
+  metadata.gz: cab0e3382f953d8f88acc764be019ccdb02bf382e65a4f227f99206e7e6c4370e4a6b158da960cf7a762e28d84765f75917ee0f351cfcd2b434aecd8d8bb8969
+  data.tar.gz: f5dc58255fd89efe2014d63e9a916d9ff3ff04d20ebf67a0d863469fd082bee7d3b399586a1f32392f78b2e4f1e6cb7c26254986faacaf0b1208a6fe5ed0c3f6

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/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

data/lib/jekyll-l10n/po_file/fuzzy_matcher.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative '../constants'
+
+module Jekyll
+  module L10n
+    # Finds the closest matching old PO entry for a new msgid using normalized
+    # Levenshtein similarity. Mirrors GNU msgmerge fuzzy-matching behaviour.
+    #
+    # Key responsibilities:
+    # * Compute normalized edit-distance similarity between two strings
+    # * Select the best-scoring candidate from a pool of orphaned old entries
+    # * Return the matched old msgid and its msgstr for use as a fuzzy hint
+    class PoFuzzyMatcher
+      THRESHOLD = Constants::DEFAULT_FUZZY_THRESHOLD
+
+      # Extract msgstr from a PO entry that is either a plain String or a metadata Hash.
+      #
+      # @param entry [String, Hash] PO entry value
+      # @return [String]
+      def self.msgstr_from_entry(entry)
+        entry.is_a?(Hash) ? entry[:msgstr].to_s : entry.to_s
+      end
+
+      # Find the best fuzzy match for new_msgid among candidates.
+      #
+      # Skips new_msgid values longer than MAX_FUZZY_MSGID_LENGTH (long strings are
+      # unique HTML fragments with no useful near-duplicate and Levenshtein is O(n²)).
+      # Pre-filters candidates to the length range where similarity ≥ threshold is
+      # mathematically possible before invoking Levenshtein.
+      #
+      # @param new_msgid [String] the new source string to match
+      # @param candidates [Hash] { old_msgid => entry } where entry is either a
+      #   String msgstr or a Hash with :msgstr key
+      # @param threshold [Float] minimum similarity score to accept (0.0–1.0)
+      # @return [Hash, nil] { msgid: String, msgstr: String } or nil if no match
+      def self.find_match(new_msgid, candidates, threshold: THRESHOLD)
+        return nil if candidates.empty?
+        return nil if new_msgid.nil? || new_msgid.length > Constants::MAX_FUZZY_MSGID_LENGTH
+
+        len      = new_msgid.length
+        min_feas = (len * threshold).ceil
+        max_feas = threshold.positive? ? (len / threshold).floor : Float::INFINITY
+
+        best = best_candidate(new_msgid, candidates, min_feas, max_feas, threshold)
+        return nil unless best
+
+        { msgid: best[:msgid], msgstr: msgstr_from_entry(best[:entry]) }
+      end
+
+      def self.best_candidate(new_msgid, candidates, min_feas, max_feas, threshold)
+        best_msgid = best_entry = nil
+        best_score = 0.0
+
+        candidates.each do |old_msgid, entry|
+          ol = old_msgid.length
+          next if ol < min_feas || ol > max_feas
+
+          score = similarity(new_msgid, old_msgid)
+          next unless score > best_score && score >= threshold
+
+          best_score = score
+          best_msgid = old_msgid
+          best_entry = entry
+          break if best_score >= 1.0
+        end
+
+        best_msgid ? { msgid: best_msgid, entry: best_entry } : nil
+      end
+
+      # Normalized Levenshtein similarity between two strings.
+      #
+      # Returns 0.0 immediately when the length ratio falls below the threshold —
+      # the maximum achievable similarity is min_len/max_len, so Levenshtein cannot
+      # produce a useful result and the O(n²) computation is skipped.
+      #
+      # @param str_a [String]
+      # @param str_b [String]
+      # @return [Float] 0.0 (completely different) to 1.0 (identical)
+      def self.similarity(str_a, str_b)
+        return 1.0 if str_a == str_b
+        return 0.0 if str_a.empty? || str_b.empty?
+
+        max_len = [str_a.length, str_b.length].max
+        min_len = [str_a.length, str_b.length].min
+        return 0.0 if min_len.to_f / max_len < THRESHOLD
+
+        dist = levenshtein(str_a, str_b)
+        1.0 - (dist.to_f / max_len)
+      end
+
+      def self.levenshtein(str_a, str_b)
+        # Keep the shorter string as the row to minimise the dp array size.
+        str_a, str_b = str_b, str_a if str_a.length > str_b.length
+
+        a_chars = str_a.chars
+        b_chars = str_b.chars
+        m       = a_chars.length
+        n       = b_chars.length
+
+        curr = Array.new(m + 1) { |i| i }
+        prev = Array.new(m + 1, 0)
+
+        n.times do |j|
+          curr, prev = prev, curr # swap in place — no allocation
+          curr[0] = j + 1
+          m.times do |i|
+            cost        = a_chars[i] == b_chars[j] ? 0 : 1
+            curr[i + 1] = [curr[i] + 1, prev[i + 1] + 1, prev[i] + cost].min
+          end
+        end
+        curr[m]
+      end
+      private_class_method :levenshtein, :best_candidate
+    end
+  end
+end

data/lib/jekyll-l10n/po_file/loader.rb

@@ -3,6 +3,7 @@
 require_relative 'reader'
 require_relative 'manager'
 require_relative 'path_builder'
+require_relative '../utils/error_handler'
 
 module Jekyll
   module L10n
@@ -52,11 +53,11 @@ module Jekyll
       end
 
       def self.load_and_cache(cache_key, po_path)
-        translations = PoFileReader.parse(po_path)
+        translations = PoFileReader.parse_for_translation(po_path)
         PoFileManager.cache[cache_key] = translations
         translations
       rescue StandardError => e
-        Jekyll.logger.warn 'Localization', "Error loading PO file #{po_path}: #{e.message}"
+        ErrorHandler.log_warning("loading PO file #{po_path}", e)
         {}
       end
     end

data/lib/jekyll-l10n/po_file/manager.rb

@@ -7,6 +7,7 @@ require_relative 'path_builder'
 require_relative '../utils/site_config_accessor'
 require_relative '../utils/file_operations'
 require_relative '../utils/logger_formatter'
+require_relative '../utils/error_handler'
 
 module Jekyll
   module L10n
@@ -113,7 +114,7 @@ module Jekyll
         prepare_and_write_po_file(po_path, entries, locale, page_path: page_path,
                                                             skip_merge: skip_merge)
       rescue StandardError => e
-        Jekyll.logger.error 'Localization', "Error saving PO file #{po_path}: #{e.message}"
+        ErrorHandler.log_error("saving PO file #{po_path}", e)
         false
       end
 

data/lib/jekyll-l10n/po_file/merger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'reader'
+require_relative '../utils/error_handler'
 
 module Jekyll
   module L10n
@@ -73,7 +74,7 @@ module Jekyll
           merged[msgid] ||= entry
         end
       rescue StandardError => e
-        Jekyll.logger.warn 'Localization', "Error merging PO file #{po_file}: #{e.message}"
+        ErrorHandler.log_warning("merging PO file #{po_file}", e)
       end
     end
   end

data/lib/jekyll-l10n/po_file/reader.rb

@@ -89,6 +89,20 @@ module Jekyll
         process_po_lines_instance(content, :merge)
       end
 
+      # Parse a PO file for translation injection, excluding fuzzy entries.
+      #
+      # Parses with full merge metadata (including fuzzy flags), then strips fuzzy
+      # entries and returns a simple msgid → msgstr hash. Fuzzy entries are treated
+      # as untranslated per the GNU Gettext standard: msgfmt skips them by default
+      # and they should fall through to the active fallback mode.
+      #
+      # @return [Hash] Simple translation hash { msgid => msgstr }, fuzzy entries omitted
+      def parse_for_translation
+        parse_for_merge
+          .reject { |_msgid, v| v.is_a?(Hash) && v[:fuzzy] }
+          .transform_values { |v| v.is_a?(Hash) ? v[:msgstr] : v }
+      end
+
       # Parse a PO file (class method, for backward compatibility).
       #
       # @param po_path [String] Path to PO file
@@ -113,6 +127,14 @@ module Jekyll
         new(po_path).parse_for_merge
       end
 
+      # Parse a PO file for translation injection, excluding fuzzy entries (class method).
+      #
+      # @param po_path [String] Path to PO file
+      # @return [Hash] Simple translation hash { msgid => msgstr }, fuzzy entries omitted
+      def self.parse_for_translation(po_path)
+        new(po_path).parse_for_translation
+      end
+
       # Backward compatibility wrapper
       def self.process_po_lines(content)
         process_po_lines_internal(content, false)
@@ -149,7 +171,8 @@ module Jekyll
       # with_mode: false (default, simple format), true (with reference), :merge (with both)
       # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize, Metrics/PerceivedComplexity
       def self.process_msgid_msgstr_pair(lines, start_idx, translations,
-                                         reference: nil, fuzzy: nil, with_mode: false)
+                                         reference: nil, fuzzy: nil, previous_msgid: nil,
+                                         with_mode: false)
         # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize, Metrics/PerceivedComplexity
         # Handle nil sentinel values (from NO_REFERENCE constant)
         reference = nil if reference == NO_REFERENCE
@@ -168,7 +191,8 @@ module Jekyll
           with_metadata = with_mode == true || with_mode == :merge || !reference.nil? || !fuzzy.nil?
           store_translation(
             translations, msgid_value, msgstr_value,
-            reference: reference, fuzzy: fuzzy, with_metadata: with_metadata
+            reference: reference, fuzzy: fuzzy, previous_msgid: previous_msgid,
+            with_metadata: with_metadata
           )
         else
           i += 1
@@ -259,10 +283,10 @@ module Jekyll
             reference: reference, fuzzy: nil, with_mode: true
           )
         when :merge
-          reference, fuzzy = extract_reference_and_fuzzy_before_msgid(lines, idx)
+          reference, fuzzy, previous_msgid = extract_reference_and_fuzzy_before_msgid(lines, idx)
           process_msgid_msgstr_pair(
             lines, idx, translations,
-            reference: reference, fuzzy: fuzzy, with_mode: :merge
+            reference: reference, fuzzy: fuzzy, previous_msgid: previous_msgid, with_mode: :merge
           )
         else
           process_msgid_msgstr_pair(lines, idx, translations, reference: nil, fuzzy: nil,
@@ -270,29 +294,48 @@ module Jekyll
         end
       end
 
-      # Unified metadata extraction: extracts reference and optionally fuzzy flag
+      # Unified metadata extraction: extracts reference, fuzzy flag, and previous msgid.
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def self.extract_metadata_before_msgid(lines, msgid_idx, include_fuzzy: false)
-        reference = nil
-        fuzzy = false
-        comments_end = msgid_idx - 1
+        reference      = nil
+        fuzzy          = false
+        previous_msgid = nil
+        comments_end   = msgid_idx - 1
 
         while comments_end >= 0
           comment_line = lines[comments_end].strip
           break unless comment_line.start_with?('#') || comment_line.empty?
 
-          reference = extract_reference_from_line(comment_line) || reference
-          fuzzy = true if include_fuzzy && fuzzy_line?(comment_line)
+          reference      = extract_reference_from_line(comment_line) || reference
+          previous_msgid = extract_previous_msgid_from_line(comment_line) || previous_msgid if include_fuzzy
+          fuzzy          = true if include_fuzzy && fuzzy_line?(comment_line)
 
           comments_end -= 1
         end
 
-        include_fuzzy ? [reference, fuzzy] : reference
+        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?('#:')
       end
 
+      # Parse a #| msgid "..." previous-msgid comment line.
+      def self.extract_previous_msgid_from_line(comment_line)
+        return nil unless comment_line.start_with?('#|') && comment_line.include?('msgid')
+
+        raw = comment_line.sub(/^#\|\s*msgid\s*/, '').strip
+        # Strip surrounding quotes and unescape
+        if raw.start_with?('"') && raw.end_with?('"')
+          unescape_string(raw[1...-1], '"')
+        elsif raw.start_with?("'") && raw.end_with?("'")
+          unescape_string(raw[1...-1], "'")
+        else
+          raw
+        end
+      end
+
       def self.fuzzy_line?(comment_line)
         comment_line.start_with?('#,') && comment_line.include?('fuzzy')
       end
@@ -302,7 +345,7 @@ module Jekyll
         extract_metadata_before_msgid(lines, msgid_idx, include_fuzzy: false)
       end
 
-      # Backward compatibility wrapper
+      # Backward compatibility wrapper — now returns [reference, fuzzy, previous_msgid]
       def self.extract_reference_and_fuzzy_before_msgid(lines, msgid_idx)
         extract_metadata_before_msgid(lines, msgid_idx, include_fuzzy: true)
       end
@@ -404,24 +447,29 @@ module Jekyll
       # - Backward compatibility: Supports legacy calling conventions
       # rubocop:disable Metrics/ParameterLists
       def self.store_translation(translations, msgid, msgstr, reference: nil, fuzzy: nil,
-                                 with_metadata: false)
+                                 previous_msgid: nil, with_metadata: false)
         # rubocop:enable Metrics/ParameterLists
         return if msgid.nil? || msgstr.nil? || msgid.empty?
 
-        translations[msgid] = build_translation_entry(msgstr, reference, fuzzy, with_metadata)
+        translations[msgid] = build_translation_entry(msgstr, reference, fuzzy,
+                                                      previous_msgid, with_metadata: with_metadata)
       end
 
-      def self.build_translation_entry(msgstr, reference, fuzzy, with_metadata)
+      # rubocop:disable 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
-        return msgstr if !with_metadata && reference.nil? && fuzzy.nil?
+        return msgstr if !with_metadata && reference.nil? && fuzzy.nil? && previous_msgid.nil?
 
         # Build metadata hash based on what's provided
         entry = { msgstr: msgstr }
-        entry[:reference] = reference unless reference.nil?
-        entry[:fuzzy] = fuzzy unless fuzzy.nil?
-        entry[:comment] = nil if !fuzzy.nil? || !reference.nil?
+        entry[:reference]      = reference      unless reference.nil?
+        entry[:fuzzy]          = fuzzy          unless fuzzy.nil?
+        entry[:previous_msgid] = previous_msgid unless previous_msgid.nil?
+        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
@@ -499,9 +547,11 @@ module Jekyll
             self.class.process_msgid_msgstr_pair(lines, idx, translations, reference: reference,
                                                                            fuzzy: nil, with_mode: true)
           when :merge
-            reference, fuzzy = self.class.extract_reference_and_fuzzy_before_msgid(lines, idx)
+            reference, fuzzy, previous_msgid = self.class.extract_reference_and_fuzzy_before_msgid(lines, idx)
             self.class.process_msgid_msgstr_pair(lines, idx, translations, reference: reference,
-                                                                           fuzzy: fuzzy, with_mode: :merge)
+                                                                           fuzzy: fuzzy,
+                                                                           previous_msgid: previous_msgid,
+                                                                           with_mode: :merge)
           else
             self.class.process_msgid_msgstr_pair(lines, idx, translations, reference: nil,
                                                                            fuzzy: nil, with_mode: false)