jekyll-l10n 2.0.0 → 3.0.0

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../configuration'
+require_relative '../constants'
 require_relative '../utils/site_config_accessor'
 require_relative '../po_file/path_builder'
 require_relative '../utils/locale_url_formatter'
@@ -30,13 +32,10 @@ module Jekyll
     #   end
     #
     class RegenerationChecker
-      # @!visibility private
-      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)
+      #   holds the PO files. Defaults to Constants::DEFAULT_LOCALES_DIR.
+      def initialize(site, locales_dir = Constants::DEFAULT_LOCALES_DIR)
         @site = site
         @locales_dir = locales_dir
         @source = SiteConfigAccessor.source(@site)
@@ -79,12 +78,17 @@ module Jekyll
       #
       # This must produce the same path as LocalizedPage#destination.
       #
+      # It is the English page's own output path, as Jekyll computes it, under
+      # the locale segment, since the localized page's URL is the English URL
+      # with that segment in front (LocalizedPage#url).
+      #
       # @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)
+      # @return [String] Path such as "es/about/index.html" or "es/about.html"
+      #   (no leading slash)
       def relative_dest_path(page, locale)
-        url_locale = LocaleUrlFormatter.to_url_segment(locale)
-        "#{url_locale}#{page.url.chomp('/')}/index.html"
+        output_path = page.destination(@destination).delete_prefix(@destination)
+        "#{LocaleUrlFormatter.to_url_segment(locale)}#{output_path}"
       end
 
       private
@@ -92,11 +96,13 @@ module Jekyll
       def incremental_enabled?
         return false if @site&.config.nil?
 
-        @site.config.dig('jekyll_l10n', 'incremental') == true
+        SiteConfigAccessor.site_settings(@site)['incremental'] == true
       end
 
+      # A directory at the path is the layout of an earlier release
+      # (es/nav.html/index.html), so the page is written again.
       def dest_path_exists?(page, locale)
-        File.exist?(dest_path(page, locale))
+        File.file?(dest_path(page, locale))
       end
 
       def dest_path(page, locale)

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'liquid'
+require_relative '../configuration'
 require_relative '../constants'
 require_relative '../utils/error_handler'
 require_relative '../utils/locale_name_resolver'
@@ -27,7 +28,7 @@ module Jekyll
     # @example Usage in Jekyll Liquid templates
     #   <!-- Add locale prefix to URL -->
     #   <a href="{{ '/about/' | locale_url: 'es_ES' }}">Acerca de</a>
-    #   <!-- Produces: /es-ES/about/ -->
+    #   <!-- Produces: /es-es/about/ -->
     #
     #   <!-- Switch to different locale variant -->
     #   <a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
@@ -41,7 +42,7 @@ module Jekyll
       # Generate a locale-prefixed URL for the given URL and locale
       #
       # Adds a locale prefix in BCP 47 hyphenated form to the given URL. For example,
-      # '/about/' becomes '/es-ES/about/' for locale 'es_ES'. The filter handles
+      # '/about/' becomes '/es-es/about/' for locale 'es_ES'. The filter handles
       # various edge cases and only applies the prefix when appropriate.
       #
       # The method performs several checks to determine if prefixing is appropriate:
@@ -56,7 +57,7 @@ module Jekyll
       #   prefixing is not appropriate
       # @example
       #   <!-- Explicit underscore locale converted to hyphen in URL -->
-      #   {{ '/about/' | locale_url: 'es_ES' }}  # => '/es-ES/about/'
+      #   {{ '/about/' | locale_url: 'es_ES' }}  # => '/es-es/about/'
       #
       #   <!-- Current page's locale -->
       #   {{ '/about/' | locale_url }}  # => '/es/about/' (if page locale is 'es')
@@ -71,7 +72,7 @@ module Jekyll
       # Generate a URL for the given locale variant of the current page
       #
       # Switches the current URL to a different locale variant. For example, if the current
-      # page is '/es-ES/about/', calling this with 'fr' returns '/fr/about/'. This is useful
+      # page is '/es-es/about/', calling this with 'fr' returns '/fr/about/'. This is useful
       # for building language switcher menus.
       #
       # This filter first extracts the base URL (without locale prefix) from the given URL,
@@ -81,7 +82,7 @@ module Jekyll
       # @param target_locale [String] The target locale code (e.g., 'es_ES', 'fr', 'pt_BR')
       # @return [String] The URL for the target locale, or original URL if locale is invalid
       # @example
-      #   <!-- Current page is /es-ES/about/, switch to French -->
+      #   <!-- Current page is /es-es/about/, switch to French -->
       #   {{ page.url | switch_locale_url: 'fr' }}  # => '/fr/about/'
       #
       #   <!-- Build a language switcher -->
@@ -117,7 +118,7 @@ module Jekyll
       # @example
       #   {{ page.url | locale_menu }}
       #   # => [{"code"=>"en","name"=>"English","url"=>"/about/","current"=>false},
-      #   #     {"code"=>"es_ES","name"=>"Spanish (Spain)","url"=>"/es-ES/about/","current"=>true}]
+      #   #     {"code"=>"es_ES","name"=>"Spanish (Spain)","url"=>"/es-es/about/","current"=>true}]
       def locale_menu(url)
         menu_locales.map do |locale|
           {
@@ -207,7 +208,7 @@ module Jekyll
 
         if page
           locales = if page.is_a?(Hash)
-                      page.dig('with_locales_data', 'locales')
+                      Configuration::Schema.normalize(page[Configuration::PAGE_DATA_KEY], source: nil)['locales']
                     else
                       SiteConfigAccessor.page_locales_data(page)['locales']
                     end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Parses the text of a GNU Gettext PO file into a translation hash.
+    #
+    # Each entry is read in three steps, in this order:
+    # 1. The comment lines above `msgid`: reference (`#:`), fuzzy flag (`#,`)
+    #    and previous msgid (`#|`).
+    # 2. The `msgid` and `msgstr` fields, each with its continuation lines.
+    # 3. The stored value, whose shape depends on the mode.
+    #
+    # Modes and the value stored for each msgid:
+    # * :simple — the msgstr String
+    # * :references — { msgstr:, reference: } (reference only when present)
+    # * :merge — { msgstr:, reference:, fuzzy:, previous_msgid: }
+    #
+    # Entries with an empty msgid (the header) are skipped.
+    #
+    # @example
+    #   PoEntryParser.parse(%(msgid "Hello"\nmsgstr "Hola"\n), :simple)
+    #   # => { "Hello" => "Hola" }
+    class PoEntryParser
+      MODES = %i[simple references merge].freeze
+      MSGID_PATTERN = /^msgid ['"](.*)['"] *$/.freeze
+      MSGSTR_PATTERN = /^msgstr ['"](.*)['"] *$/.freeze
+
+      # @param content [String] PO file text
+      # @param mode [Symbol] One of MODES
+      # @return [Hash] Translations keyed by msgid
+      def self.parse(content, mode)
+        raise ArgumentError, "unknown PO parse mode: #{mode.inspect}" unless MODES.include?(mode)
+
+        new(content.to_s.split("\n"), mode).parse
+      end
+
+      def initialize(lines, mode)
+        @lines = lines
+        @mode = mode
+      end
+
+      # @return [Hash] Translations keyed by msgid
+      def parse
+        translations = {}
+        idx = 0
+        idx = parse_line(idx, translations) while idx < @lines.length
+        translations
+      end
+
+      private
+
+      # Parses the entry that starts at idx, if any, and returns the next line
+      # to read.
+      def parse_line(idx, translations)
+        return idx + 1 unless @lines[idx].strip.start_with?('msgid ')
+
+        metadata = @mode == :simple ? {} : read_comments(idx)
+        parse_entry(idx, translations, metadata)
+      end
+
+      # --- Step 1: comment lines above msgid ---
+
+      # Reads the comment and blank lines above msgid_idx, nearest first. When a
+      # kind of comment appears more than once, the topmost one wins.
+      def read_comments(msgid_idx)
+        metadata = { reference: nil, fuzzy: false, previous_msgid: nil }
+        (msgid_idx - 1).downto(0) do |idx|
+          line = @lines[idx].strip
+          break unless line.empty? || line.start_with?('#')
+
+          read_comment(line, metadata)
+        end
+        @mode == :merge ? metadata : { reference: metadata[:reference] }
+      end
+
+      def read_comment(line, metadata)
+        if line.start_with?('#:')
+          metadata[:reference] = line.sub(/^#:\s*/, '').strip
+        elsif line.start_with?('#,') && line.include?('fuzzy')
+          metadata[:fuzzy] = true
+        elsif line.start_with?('#|') && line.include?('msgid')
+          metadata[:previous_msgid] = previous_msgid(line)
+        end
+      end
+
+      def previous_msgid(line)
+        raw = line.sub(/^#\|\s*msgid\s*/, '').strip
+        quote = raw[0]
+        return raw unless ['"', "'"].include?(quote) && raw.end_with?(quote)
+
+        unescape(raw[1...-1], quote)
+      end
+
+      # --- Step 2: msgid and msgstr fields ---
+
+      # Reads msgid and the msgstr right after it. A msgid with no msgstr on the
+      # next line is dropped, and that next line is skipped too.
+      def parse_entry(idx, translations, metadata)
+        msgid, idx = read_field(idx, MSGID_PATTERN)
+        return idx + 1 unless idx < @lines.length && @lines[idx].strip.start_with?('msgstr ')
+
+        msgstr, idx = read_field(idx, MSGSTR_PATTERN)
+        store(translations, msgid, msgstr, metadata)
+        idx
+      end
+
+      # @return [Array(String, Integer)] The field's value and the next line
+      def read_field(idx, pattern)
+        line = @lines[idx].strip
+        match = line.match(pattern)
+        quote = match ? line[match.begin(1) - 1] : '"'
+        values = match ? [unescape(match[1], quote)] : []
+        read_continuations(idx + 1, values, quote)
+      end
+
+      # Appends the quoted lines that follow a field to values.
+      #
+      # @return [Array(String, Integer)] The joined value and the next line
+      def read_continuations(idx, values, quote)
+        while idx < @lines.length && continuation?(@lines[idx].strip)
+          values << unescape(@lines[idx].strip[1...-1], quote)
+          idx += 1
+        end
+        [values.join, idx]
+      end
+
+      def continuation?(line)
+        return false if line.empty? || line.start_with?('#', 'msgid', 'msgstr')
+
+        (line.start_with?('"') && line.end_with?('"')) ||
+          (line.start_with?("'") && line.end_with?("'"))
+      end
+
+      # Unescapes a quoted PO value. Escaped quotes are replaced before escaped
+      # backslashes: the other order would read `\\"` as an escaped quote.
+      def unescape(str, quote)
+        str.gsub("\\#{quote}", quote).gsub('\\\\', '\\')
+      end
+
+      # --- Step 3: the stored value ---
+
+      def store(translations, msgid, msgstr, metadata)
+        return if msgid.empty?
+
+        translations[msgid] = @mode == :simple ? msgstr : entry(msgstr, metadata)
+      end
+
+      def entry(msgstr, metadata)
+        entry = { msgstr: msgstr }.merge(metadata.compact)
+        entry[:comment] = nil if @mode == :merge || metadata[:reference]
+        entry
+      end
+    end
+  end
+end

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

@@ -26,92 +26,106 @@ module Jekyll
       #
       # 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.
+      # Only candidates whose length allows a similarity ≥ threshold are scored, and
+      # each one stops being scored as soon as its edit distance is too large.
       #
       # @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)
+      # @param scores [Hash, nil] cache of scores by [new_msgid, old_msgid], shared
+      #   between calls that use the same threshold, such as the locales of one
+      #   compendium merge. Without it, every call scores its candidates again.
       # @return [Hash, nil] { msgid: String, msgstr: String } or nil if no match
-      def self.find_match(new_msgid, candidates, threshold: THRESHOLD)
+      def self.find_match(new_msgid, candidates, threshold: THRESHOLD, scores: nil)
         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]) }
+        best = best_candidate(new_msgid, candidates, threshold, scores)
+        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
+      def self.best_candidate(new_msgid, candidates, threshold, scores)
+        lengths = feasible_lengths(new_msgid.length, threshold)
+        best = nil
         best_score = 0.0
 
         candidates.each do |old_msgid, entry|
-          ol = old_msgid.length
-          next if ol < min_feas || ol > max_feas
+          next unless lengths.cover?(old_msgid.length)
 
-          score = similarity(new_msgid, old_msgid)
+          score = cached_score(new_msgid, old_msgid, threshold, scores)
           next unless score > best_score && score >= threshold
 
           best_score = score
-          best_msgid = old_msgid
-          best_entry = entry
+          best = { msgid: old_msgid, entry: entry }
           break if best_score >= 1.0
         end
+        best
+      end
 
-        best_msgid ? { msgid: best_msgid, entry: best_entry } : nil
+      # Candidate lengths for which a similarity ≥ threshold is possible.
+      def self.feasible_lengths(length, threshold)
+        max = threshold.positive? ? (length / threshold).floor : Float::INFINITY
+        (length * threshold).ceil..max
       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)
+      def self.cached_score(new_msgid, old_msgid, threshold, scores)
+        return bounded_similarity(new_msgid, old_msgid, threshold) unless scores
+
+        scores.fetch([new_msgid, old_msgid]) do |key|
+          scores[key] = bounded_similarity(new_msgid, old_msgid, threshold)
+        end
+      end
+
+      # Normalized Levenshtein similarity (0.0 to 1.0), or 0.0 as soon as the
+      # score is certain to be below threshold, without finishing the edit
+      # distance.
+      def self.bounded_similarity(str_a, str_b, threshold)
         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
+        # Rounded up so a pair exactly at the threshold is never cut off.
+        limit = (max_len * (1 - threshold)).ceil
+        return 0.0 if char_count_distance(str_a, str_b) > limit
 
-        dist = levenshtein(str_a, str_b)
-        1.0 - (dist.to_f / max_len)
+        distance = bounded_distance(str_a, str_b, limit)
+        distance > limit ? 0.0 : 1.0 - (distance.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 lower bound on the Levenshtein distance, from character counts alone:
+      # each edit changes the counts by at most one on each side.
+      def self.char_count_distance(str_a, str_b)
+        diff = str_a.each_char.tally
+        str_b.each_char { |char| diff[char] = diff.fetch(char, 0) - 1 }
+        surplus, deficit = diff.values.partition(&:positive?)
+        [surplus.sum, -deficit.sum].max
+      end
 
+      # Levenshtein distance, or any value above limit once every way to finish
+      # the comparison already costs more than limit.
+      def self.bounded_distance(str_a, str_b, limit)
+        # Keep the shorter string as the row to minimise the row 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
+        row = (0..a_chars.length).to_a
+
+        str_b.each_char.with_index(1) do |b_char, row_number|
+          row = next_row(row, a_chars, b_char, row_number)
+          return limit + 1 if row.min > limit
+        end
+        row.last
+      end
+
+      def self.next_row(prev, a_chars, b_char, row_number)
+        curr = [row_number]
+        a_chars.each_with_index do |a_char, i|
+          cost = a_char == b_char ? 0 : 1
+          curr << [curr[i] + 1, prev[i + 1] + 1, prev[i] + cost].min
         end
-        curr[m]
+        curr
       end
-      private_class_method :levenshtein, :best_candidate
+      private_class_method :best_candidate, :feasible_lengths, :cached_score,
+                           :bounded_similarity, :char_count_distance, :bounded_distance, :next_row
     end
   end
 end

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

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 require_relative 'reader'
-require_relative 'manager'
 require_relative 'path_builder'
 require_relative '../utils/error_handler'
+require_relative '../utils/msgstr_validator'
 
 module Jekyll
   module L10n
@@ -18,6 +18,7 @@ module Jekyll
     # * Construct file paths for locale/page combinations
     # * Load PO files from disk when not cached
     # * Parse PO file content into translation hashes
+    # * Drop entries whose msgstr markup does not match the msgid (MsgstrValidator)
     # * Cache parsed translations for reuse
     # * Handle file-not-found gracefully (return empty hash)
     # * Log errors during loading
@@ -26,11 +27,19 @@ module Jekyll
     #   translations = PoFileLoader.load('_site', '_locales', 'es', 'docs/index.html')
     #   # Returns cached or newly-loaded translations for that page/locale
     #
-    # @see Jekyll::L10n::PoFileManager for caching implementation details
+    # @see Jekyll::L10n::PoFileManager for the public cache API
     class PoFileLoader
+      # The global PO file cache, mapping PO file paths to translation
+      # hashes. Read and clear it through PoFileManager.
+      #
+      # @return [Hash]
+      def self.cache
+        @cache ||= {}
+      end
+
       # Load a PO file with caching.
       #
-      # First checks the global PoFileManager cache for already-loaded translations.
+      # First checks the global cache for already-loaded translations.
       # If not found, constructs the file path, loads from disk if file exists,
       # parses the PO file, caches the result, and returns. Returns empty hash
       # if file doesn't exist or if an error occurs during loading.
@@ -42,24 +51,24 @@ module Jekyll
       #   If nil, loads compendium.
       # @return [Hash] Translation hash { msgid => msgstr } or empty hash if not found
       def self.load(source, locales_dir, locale, page_path)
-        cache_key = "#{locale}:#{page_path}"
-        cached = PoFileManager.cache[cache_key]
-        return cached if cached
-
         po_path = PoPathBuilder.build(source, locales_dir, locale, page_path)
+        cached = cache[po_path]
+        return cached if cached
         return {} unless File.exist?(po_path)
 
-        load_and_cache(cache_key, po_path)
+        load_and_cache(po_path)
       end
 
-      def self.load_and_cache(cache_key, po_path)
-        translations = PoFileReader.parse_for_translation(po_path)
-        PoFileManager.cache[cache_key] = translations
+      def self.load_and_cache(po_path)
+        translations = MsgstrValidator.reject_invalid(PoFileReader.parse_for_translation(po_path), po_path)
+        cache[po_path] = translations
         translations
       rescue StandardError => e
         ErrorHandler.log_warning("loading PO file #{po_path}", e)
         {}
       end
+
+      private_class_method :load_and_cache
     end
   end
 end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../constants'
 require_relative 'loader'
 require_relative 'writer'
 require_relative 'merger'
@@ -22,7 +23,7 @@ module Jekyll
     # * Load and cache PO files (page-specific and compendium)
     # * Save new or updated PO files with optional merging of existing translations
     # * Merge PO files for locales (combining page-specific with compendium)
-    # * Manage global in-memory cache keyed by locale and page path
+    # * Manage global in-memory cache keyed by PO file path
     # * Clear cache when files are written or rebuilt
     # * Construct proper file paths for locale/page combinations
     #
@@ -31,25 +32,26 @@ module Jekyll
     #   translations = manager.load_po_file('es', 'docs/index.html')
     #   manager.save_po_file('es', entries, page_path: 'docs/index.html')
     class PoFileManager
-      DEFAULT_LOCALES_DIR = '_locales'
+      DEFAULT_LOCALES_DIR = Constants::DEFAULT_LOCALES_DIR
       attr_reader :site, :locales_dir
 
       class << self
         # Access the global PO file cache.
         #
-        # @return [Hash] Cache mapping "locale:page_path" keys to translation hashes
+        # @return [Hash] Cache mapping PO file paths to translation hashes
         def cache
-          @cache ||= {}
+          PoFileLoader.cache
         end
 
         # Clear the global PO file cache.
         #
-        # Clears all cached PO file translations. Should be called when the site
-        # is rebuilt or PO files are modified to ensure fresh data is loaded.
+        # Clears all cached PO file translations. Runs on every site reset (see
+        # the hook at the end of this file), so each rebuild reloads PO files
+        # edited since the previous one.
         #
         # @return [void]
         def clear_cache
-          @cache = {}
+          PoFileLoader.cache.clear
         end
 
         # Get the current size of the global cache.
@@ -64,7 +66,7 @@ module Jekyll
       #
       # @param site [Jekyll::Site] Jekyll site object
       # @param locales_dir [String] Directory containing PO files (defaults to
-      #   DEFAULT_LOCALES_DIR = "_locales")
+      #   Constants::DEFAULT_LOCALES_DIR)
       def initialize(site, locales_dir = DEFAULT_LOCALES_DIR)
         @site = site
         @source = SiteConfigAccessor.source(@site)
@@ -98,6 +100,23 @@ module Jekyll
         PoFileLoader.load(@source, @locales_dir, locale, page_path)
       end
 
+      # Path of a locale's compendium in this manager's locales directory.
+      #
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @return [String] Full path to the compendium PO file
+      def compendium_path(locale)
+        PoPathBuilder.build(@source, @locales_dir, locale, nil)
+      end
+
+      # Directory holding a locale's page-specific PO files in this manager's
+      # locales directory.
+      #
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @return [String] Full path to the locale directory
+      def locale_dir(locale)
+        PoPathBuilder.locale_dir(@source, @locales_dir, locale)
+      end
+
       # Save a PO file for a locale and optional page.
       #
       # Writes entries to PO file, optionally merging with existing translations to
@@ -111,8 +130,7 @@ module Jekyll
       # @return [Boolean] True if write successful, false on error
       def save_po_file(locale, entries, page_path: nil, skip_merge: false)
         po_path = PoPathBuilder.build(@source, @locales_dir, locale, page_path)
-        prepare_and_write_po_file(po_path, entries, locale, page_path: page_path,
-                                                            skip_merge: skip_merge)
+        prepare_and_write_po_file(po_path, entries, locale, skip_merge: skip_merge)
       rescue StandardError => e
         ErrorHandler.log_error("saving PO file #{po_path}", e)
         false
@@ -143,19 +161,16 @@ module Jekyll
 
       private
 
-      def prepare_and_write_po_file(po_path, entries, locale, page_path: nil, skip_merge: false)
+      def prepare_and_write_po_file(po_path, entries, locale, skip_merge: false)
         LoggerFormatter.debug_if_enabled('PoFileManager',
                                          "Writing PO file: #{po_path} (#{entries.length} entries)")
         FileOperations.ensure_directory(po_path)
         PoFileWriter.write(po_path, entries, locale, skip_merge: skip_merge)
-        invalidate_po_cache(locale, page_path)
+        self.class.cache.delete(po_path)
         true
       end
-
-      def invalidate_po_cache(locale, page_path)
-        cache_key = "#{locale}:#{page_path}"
-        self.class.cache.delete(cache_key)
-      end
     end
   end
 end
+
+Jekyll::Hooks.register(:site, :after_reset) { Jekyll::L10n::PoFileManager.clear_cache }

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'path_builder'
 require_relative 'reader'
 require_relative '../utils/error_handler'
 
@@ -37,7 +38,7 @@ module Jekyll
       # @return [Hash<String, Hash>] Merged translation hash where keys are msgid strings
       #   and values are hashes with :msgstr and :reference keys
       def self.merge_for_locale(source, locales_dir, locale)
-        locale_dir = File.join(source, locales_dir, locale)
+        locale_dir = PoPathBuilder.locale_dir(source, locales_dir, locale)
         return {} unless File.directory?(locale_dir)
 
         po_files = Dir.glob(File.join(locale_dir, '**', '*.po')).sort