jekyll-l10n 1.0.5

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "loader"
+require_relative "writer"
+require_relative "merger"
+require_relative "path_builder"
+require_relative "../utils/site_config_accessor"
+require_relative "../utils/file_operations"
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # Manages reading, writing, merging, and caching of GNU Gettext PO files.
+    #
+    # PoFileManager provides a centralized API for PO file operations and maintains
+    # an in-memory cache to avoid redundant disk I/O across multiple extraction and
+    # translation operations. It coordinates between loading, writing, and merging
+    # operations while managing file paths and locale directories.
+    #
+    # Key responsibilities:
+    # * 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
+    # * Clear cache when files are written or rebuilt
+    # * Construct proper file paths for locale/page combinations
+    #
+    # @example
+    #   manager = PoFileManager.new(site, '_locales')
+    #   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"
+      attr_reader :site, :locales_dir
+
+      class << self
+        # Access the global PO file cache.
+        #
+        # @return [Hash] Cache mapping "locale:page_path" keys to translation hashes
+        def cache
+          @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.
+        #
+        # @return [void]
+        def clear_cache
+          @cache = {}
+        end
+
+        # Get the current size of the global cache.
+        #
+        # @return [Integer] Number of entries currently cached
+        def cache_size
+          cache.size
+        end
+      end
+
+      # Initialize a new PoFileManager.
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      # @param locales_dir [String] Directory containing PO files (defaults to
+      #   DEFAULT_LOCALES_DIR = "_locales")
+      def initialize(site, locales_dir = DEFAULT_LOCALES_DIR)
+        @site = site
+        @source = SiteConfigAccessor.source(@site)
+        @locales_dir = locales_dir
+      end
+
+      # Load the compendium (shared translations) for a locale.
+      #
+      # Compendiums are locale-level translation files shared across all pages.
+      # This delegates to load_po_file with page_path set to nil.
+      #
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @return [Hash] Translation hash or empty hash if file doesn't exist
+      def load_compendium(locale)
+        load_po_file(locale, nil)
+      end
+
+      # Load a PO file for a specific locale and optional page.
+      #
+      # First checks in-memory cache to avoid redundant disk I/O. If not cached,
+      # loads from disk using PoFileLoader and caches the result. Returns empty
+      # hash if file doesn't exist.
+      #
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @param page_path [String, nil] Optional page path for page-specific translations.
+      #   Defaults to nil, which loads the compendium (shared translations) file instead.
+      # @return [Hash<String, String>] Translation hash mapping msgid to msgstr,
+      #   or empty hash if file doesn't exist. Simple format where keys are original
+      #   strings and values are translations.
+      def load_po_file(locale, page_path = nil)
+        PoFileLoader.load(@source, @locales_dir, locale, page_path)
+      end
+
+      # Save a PO file for a locale and optional page.
+      #
+      # Writes entries to PO file, optionally merging with existing translations to
+      # preserve any manual edits. Creates directory structure as needed. Invalidates
+      # relevant cache entries after write.
+      #
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @param entries [Array<Hash>] Array of extraction entries with :msgid, :msgstr, :reference
+      # @param page_path [String, nil] Optional page path for page-specific file
+      # @param skip_merge [Boolean] If true, overwrites file without merging existing translations
+      # @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)
+      rescue StandardError => e
+        Jekyll.logger.error "Localization", "Error saving PO file #{po_path}: #{e.message}"
+        false
+      end
+
+      # Save the compendium (shared translations) for a locale.
+      #
+      # Writes entries to the locale's compendium file, overwriting without merging
+      # (compendia are typically generated fresh each time).
+      #
+      # @param locale [String] Target locale code
+      # @param entries [Array<Hash>] Array of extraction entries
+      # @return [Boolean] True if write successful, false on error
+      def save_compendium(locale, entries)
+        save_po_file(locale, entries, :page_path => nil, :skip_merge => true)
+      end
+
+      # Merge PO files for a locale.
+      #
+      # Combines page-specific and compendium translations for a locale, handling
+      # merging logic to preserve translations while adding new strings.
+      #
+      # @param locale [String] Target locale code
+      # @return [Boolean] True if merge successful
+      def merge_po_files(locale)
+        PoFileMerger.merge_for_locale(@source, @locales_dir, locale)
+      end
+
+      private
+
+      def prepare_and_write_po_file(po_path, entries, locale, page_path: nil, skip_merge: false) # rubocop:disable Metrics/ParameterLists
+        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)
+        true
+      end
+
+      def invalidate_po_cache(locale, page_path)
+        cache_key = "#{locale}:#{page_path}"
+        self.class.cache.delete(cache_key)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "reader"
+
+module Jekyll
+  module L10n
+    # Merges multiple PO files for a locale into a single translation hash.
+    #
+    # PoFileMerger combines page-specific PO files in a locale directory into
+    # a single merged translation hash. Used when creating compendia by combining
+    # all extracted strings across pages for a locale.
+    #
+    # Key responsibilities:
+    # * Find all PO files for a locale
+    # * Parse PO files with reference metadata
+    # * Merge into single translation hash
+    # * Preserve references for debugging
+    # * Handle parsing errors gracefully
+    #
+    # @see Jekyll::L10n::PoFileReader for file parsing
+    # @see Jekyll::L10n::CompendiumMerger for compendium merge workflow
+    #
+    # @example
+    #   merged = PoFileMerger.merge_for_locale('_site', '_locales', 'es')
+    #   # Returns combined translations from all _locales/es/**/*.po files
+    class PoFileMerger
+      # Merge all PO files for a locale.
+      #
+      # Finds all PO files in the locale subdirectory, parses them with
+      # references, and merges into a single hash. First occurrence of
+      # each msgid is kept.
+      #
+      # @param source [String] Site source directory
+      # @param locales_dir [String] Locales directory name
+      # @param locale [String] Locale code (e.g., 'es', 'fr')
+      # @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)
+        return {} unless File.directory?(locale_dir)
+
+        po_files = Dir.glob(File.join(locale_dir, "**", "*.po")).sort
+        merge_files(po_files)
+      end
+
+      # Merge a list of PO files.
+      #
+      # Parses each file and merges into single hash. Later files don't override
+      # entries from earlier files (first occurrence wins).
+      #
+      # @param po_files [Array<String>] Paths to PO files to merge
+      # @return [Hash<String, Hash>] Merged translation hash where keys are msgid strings
+      #   and values are hashes with :msgstr and :reference keys
+      def self.merge_files(po_files)
+        merged = {}
+        po_files.each do |po_file|
+          merge_file_into(po_file, merged)
+        end
+        merged
+      end
+
+      # Merge a single PO file into an existing merged hash.
+      #
+      # Parses the PO file with references and adds entries that aren't
+      # already in the merged hash. The hash can be empty, and it is modified in place.
+      #
+      # @param po_file [String] Path to PO file
+      # @param merged [Hash] Existing merged hash (can be empty, modified in place)
+      # @return [void]
+      def self.merge_file_into(po_file, merged)
+        translations = PoFileReader.parse_with_references(po_file)
+        translations.each do |msgid, entry|
+          merged[msgid] ||= entry
+        end
+      rescue StandardError => e
+        Jekyll.logger.warn "Localization", "Error merging PO file #{po_file}: #{e.message}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Constructs file paths for PO files.
+    #
+    # PoPathBuilder creates proper file paths for both compendium (locale-level)
+    # and page-specific PO files. Compendium files are at the locale level
+    # ({locales_dir}/{locale}.po), while page-specific files are nested
+    # ({locales_dir}/{locale}/{page_path}.po).
+    #
+    # Key responsibilities:
+    # * Build paths for compendium PO files
+    # * Build paths for page-specific PO files
+    # * Handle file path normalization
+    #
+    # @example
+    #   compendium = PoPathBuilder.build('_site', '_locales', 'es', nil)
+    #   # Returns '_site/_locales/es.po'
+    #   page_specific = PoPathBuilder.build('_site', '_locales', 'es', 'docs/index.html')
+    #   # Returns '_site/_locales/es/docs/index.html.po'
+    class PoPathBuilder
+      # Build a PO file path.
+      #
+      # For compendium (page_path nil): {source}/{locales_dir}/{locale}.po
+      # For page-specific: {source}/{locales_dir}/{locale}/{page_path}.po
+      #
+      # @param source [String] Site source directory
+      # @param locales_dir [String] Locales directory name (e.g., '_locales')
+      # @param locale [String] Locale code (e.g., 'es', 'fr')
+      # @param page_path [String, nil] Page path for page-specific file, nil for compendium
+      # @return [String] Full path to PO file
+      def self.build(source, locales_dir, locale, page_path)
+        if page_path.nil?
+          File.join(source, locales_dir, "#{locale}.po")
+        else
+          File.join(source, locales_dir, locale, "#{page_path}.po")
+        end
+      end
+    end
+  end
+end