jekyll-l10n 1.0.5

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../translation/page_translation_loader"
+require_relative "../translation/html_translator"
+require_relative "../utils/page_locales_config"
+require_relative "../utils/file_operations"
+require_relative "../utils/site_config_accessor"
+require_relative "../utils/external_link_icon_preserver"
+
+module Jekyll
+  module L10n
+    # Applies translations to localized HTML pages after Jekyll build.
+    #
+    # PostWriteHtmlReprocessor finds all localized HTML pages generated by the
+    # Generator, loads appropriate translations, applies them using HtmlTranslator,
+    # and rewrites the HTML files. It processes pages after Jekyll's standard
+    # build completes, during the post-write phase.
+    #
+    # Key responsibilities:
+    # * Find localized HTML pages in the build output
+    # * Load page translations (compendium + page-specific)
+    # * Create HtmlTranslator with proper configuration
+    # * Apply translations to HTML documents
+    # * Preserve external link icons from original HTML
+    # * Write translated HTML back to files
+    # * Handle errors gracefully with logging
+    #
+    # @example
+    #   reprocessor = PostWriteHtmlReprocessor.new(site)
+    #   reprocessor.reprocess_localized_pages
+    #   # Reads localized HTML, translates, preserves icons, writes back
+    class PostWriteHtmlReprocessor
+      attr_reader :site
+
+      # Initialize a new PostWriteHtmlReprocessor.
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      def initialize(site)
+        @site = site
+        @dest = SiteConfigAccessor.dest(@site)
+      end
+
+      # Reprocess all localized pages with translations.
+      #
+      # Finds all localized HTML pages that were written during the Jekyll build,
+      # loads their translations, applies translations to text and attributes,
+      # preserves external link icon styling from the original HTML, and writes
+      # the translated HTML back to disk.
+      #
+      # @return [void]
+      def reprocess_localized_pages
+        localized_files = find_localized_html_files
+        return if localized_files.empty?
+
+        msg = "Applying translations to #{localized_files.length} localized pages..."
+        Jekyll.logger.info "Localization", msg
+
+        localized_files.each do |html_path, locale, original_url|
+          translate_html_file(html_path, locale, original_url)
+        end
+      end
+
+      private
+
+      def find_localized_html_files
+        results = []
+
+        @site.pages.each do |page|
+          next unless page.data["localized"] == true
+
+          locale = page.data["locale"]
+          original_url = page.data["original_url"]
+          html_path = page.destination(@dest)
+
+          results << [html_path, locale, original_url] if File.exist?(html_path)
+        end
+
+        results
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def translate_html_file(html_path, locale, original_url)
+        # rubocop:enable Metrics/AbcSize
+        original_html = FileOperations.read_utf8(html_path)
+        original_page = find_original_page(original_url)
+
+        return unless original_page
+
+        config = PageLocalesConfig.new(original_page.data)
+        translations = PageTranslationLoader.load(@site, locale, original_url, config)
+
+        return if translations.nil? || translations.empty?
+
+        translator = HtmlTranslator.new(
+          config.fallback_mode,
+          config.translatable_attributes,
+          :debug_logging => config.debug_logging?
+        )
+
+        baseurl = @site.config["baseurl"] || ""
+        translated_html = translator.translate(original_html, translations, locale, baseurl)
+
+        if translated_html
+          # Preserve external link icons from the original HTML after translation
+          translated_html = ExternalLinkIconPreserver.preserve(original_html, translated_html)
+          FileOperations.write_utf8(html_path, translated_html)
+        end
+      rescue StandardError => e
+        error_msg = "Failed to reprocess #{html_path}: #{e.message}"
+        Jekyll.logger.warn "Localization", error_msg
+      end
+
+      def find_original_page(url)
+        @site.pages.find { |p| p.url == url && p.data["localized"] != true }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../extraction/extractor"
+require_relative "post_write_html_reprocessor"
+
+module Jekyll
+  module L10n
+    # Post-Write Processor - Extracts strings and applies translations after Jekyll build
+    #
+    # This class handles the final localization phase of the Jekyll build process. It runs
+    # after Jekyll has written all HTML files to disk (via the site:post_write hook).
+    #
+    # The processor coordinates two main operations:
+    # 1. String Extraction: Finds new and modified translatable strings in generated HTML
+    # 2. HTML Reprocessing: Applies translations to localized page variants
+    #
+    # Key responsibilities:
+    # - Invoke the Extractor to scan generated HTML for translatable content
+    # - Update PO files with new/changed strings
+    # - Reprocess localized HTML if PO files were modified
+    # - Provide logging of extraction results
+    #
+    # This is invoked automatically by Jekyll during the post_write phase and should not be
+    # called directly in most use cases.
+    #
+    # This runs in phase 5 of the Jekyll build pipeline (Post-Write Phase). See the "Build
+    # Pipeline" section in lib/jekyll-l10n.rb for the complete workflow.
+    #
+    # @example Manual invocation (advanced)
+    #   processor = PostWriteProcessor.new(site)
+    #   processor.process_localizations
+    #
+    # @see Jekyll::L10n for Build Pipeline documentation
+    # @see Jekyll::L10n::Extractor for details on string extraction
+    # @see Jekyll::L10n::PostWriteHtmlReprocessor for details on translation application
+    #
+    class PostWriteProcessor
+      # @!attribute [r] site
+      #   The Jekyll site object with all generated pages
+      #   @return [Jekyll::Site]
+      attr_reader :site
+
+      # Initialize the post-write processor
+      #
+      # @param site [Jekyll::Site] The Jekyll site object
+      def initialize(site)
+        @site = site
+      end
+
+      # Process all localizations for the site
+      #
+      # Runs the extraction and reprocessing pipeline:
+      # 1. Extracts translatable strings from all HTML files
+      # 2. Updates PO files with new entries and modified translations
+      # 3. If PO files were created or updated, reprocess localized pages to apply translations
+      #
+      # @return [void]
+      # @note This is automatically called by Jekyll's site:post_write hook
+      def process_localizations
+        extractor = Extractor.new(@site)
+        extraction_result = extractor.extract_site
+
+        # Reprocess localized HTML if PO files were created/updated
+        if extraction_result && extraction_result[:po_files_created].positive?
+          reprocessor = PostWriteHtmlReprocessor.new(@site)
+          reprocessor.reprocess_localized_pages
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "../utils/site_config_accessor"
+require_relative "../po_file/path_builder"
+
+module Jekyll
+  module L10n
+    # Regeneration Checker - Optimizes incremental builds by skipping unchanged pages
+    #
+    # This class implements incremental build optimization for localized pages. When Jekyll's
+    # incremental build mode is enabled, it checks whether a specific locale variant of a page
+    # needs to be regenerated based on source modification times.
+    #
+    # The checker compares modification times of:
+    # - Source page file
+    # - Page-specific PO translation file
+    # - Compendium (shared translations) PO file
+    # - Jekyll configuration (_config.yml)
+    #
+    # If any of these are newer than the output HTML, the page is regenerated.
+    # This significantly speeds up rebuilds when only a few files have changed.
+    #
+    # @example Usage
+    #   checker = RegenerationChecker.new(site)
+    #   if checker.should_regenerate?(page, 'es')
+    #     # Create localized_page and add to site.pages
+    #   end
+    #
+    class RegenerationChecker
+      # @!visibility private
+      DEFAULT_LOCALES_DIR = "_locales"
+
+      # Initialize the regeneration checker
+      #
+      # @param site [Jekyll::Site] The 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
+        @locales_dir = locales_dir
+        @source = SiteConfigAccessor.source(@site)
+        @destination = @site&.config&.dig("destination") || ""
+      end
+
+      # Determine if a localized page variant should be regenerated
+      #
+      # Returns true if:
+      # - Incremental builds are disabled (always regenerate)
+      # - Output file doesn't exist yet
+      # - Source page has been modified since output was generated
+      # - PO translation files have been modified since output was generated
+      # - Jekyll configuration has been modified since output was generated
+      #
+      # Returns false if incremental builds are enabled and output is up-to-date.
+      #
+      # @param page [Jekyll::Page] The source page to check
+      # @param locale [String] The locale code for the variant (e.g., 'es', 'fr')
+      # @return [Boolean] true if the page should be regenerated, false if output is current
+      def should_regenerate?(page, locale)
+        return true unless incremental_enabled?
+        return true unless dest_path_exists?(page, locale)
+
+        dest_mtime = File.mtime(dest_path(page, locale))
+
+        source_modified?(page, dest_mtime) ||
+          po_files_modified?(page, locale, dest_mtime) ||
+          config_modified?(dest_mtime)
+      end
+
+      private
+
+      def incremental_enabled?
+        return false if @site&.config.nil?
+
+        localization_config = @site.config.dig("localization_gettext", "with_locales_data",
+                                               "incremental") ||
+          @site.config.dig("localization_gettext", "incremental") ||
+          false
+        localization_config == true
+      end
+
+      def dest_path_exists?(page, locale)
+        File.exist?(dest_path(page, locale))
+      end
+
+      def dest_path(page, locale)
+        # Replicate LocalizedPage destination logic without instantiation
+        url = "/#{locale}#{page.url.chomp("/")}/"
+        "#{@destination}#{url}index.html"
+      end
+
+      def source_modified?(page, dest_mtime)
+        page_mtime = File.mtime(page.path)
+        page_mtime > dest_mtime
+      rescue StandardError
+        true
+      end
+
+      def po_files_modified?(page, locale, dest_mtime)
+        # Check page-specific PO file
+        page_po_path = PoPathBuilder.build(@source, @locales_dir, locale, page.path)
+        return true if file_modified?(page_po_path, dest_mtime)
+
+        # Check compendium PO file
+        compendium_po_path = PoPathBuilder.build(@source, @locales_dir, locale, nil)
+        file_modified?(compendium_po_path, dest_mtime)
+      end
+
+      def config_modified?(dest_mtime)
+        config_path = File.join(@source, "_config.yml")
+        file_modified?(config_path, dest_mtime)
+      end
+
+      def file_modified?(file_path, dest_mtime)
+        return false unless File.exist?(file_path)
+
+        File.mtime(file_path) > dest_mtime
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module Jekyll
+  module L10n
+    # URL Filter - Liquid filters for locale-aware URL generation
+    #
+    # Provides Liquid filters for use in Jekyll templates to generate locale-prefixed URLs.
+    # These filters are automatically registered with Liquid during plugin initialization.
+    #
+    # This module is designed to be included in Liquid::Template's filter registry, making
+    # the filters available in all Jekyll templates.
+    #
+    # Key responsibilities:
+    # - Generate locale-prefixed URLs for links
+    # - Switch between locale variants of the same page
+    # - Validate locales against site configuration
+    # - Handle edge cases (external URLs, anchors, protocols)
+    #
+    # @example Usage in Jekyll Liquid templates
+    #   <!-- Add locale prefix to URL -->
+    #   <a href="{{ '/about/' | locale_url: 'es' }}">Acerca de</a>
+    #
+    #   <!-- Switch to different locale variant -->
+    #   <a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
+    #
+    # @see Jekyll::L10n for filter registration (line 218 in lib/jekyll-l10n.rb)
+    #
+    module UrlFilter
+      # Generate a locale-prefixed URL for the given URL and locale
+      #
+      # Adds a locale prefix to the given URL, making it suitable for use in locale-specific
+      # links. For example, '/about/' becomes '/es/about/' for locale '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:
+      # - Invalid locale codes (nil, empty, or 'en') are skipped
+      # - URLs already localized are not prefixed again
+      # - External URLs, anchors, and relative paths are not modified
+      #
+      # @param url [String] The URL to prefix (e.g., '/about/', '/path/to/page/')
+      # @param locale [String, nil] The locale code (e.g., 'es', 'pt_BR'). Defaults to nil
+      #   (uses current page's locale). If nil, uses page's locale from context.
+      # @return [String] The locale-prefixed URL, or original URL if prefixing is not appropriate
+      # @example
+      #   <!-- Explicit locale -->
+      #   {{ '/about/' | locale_url: 'es' }}  # => '/es/about/'
+      #
+      #   <!-- Current page's locale -->
+      #   {{ '/about/' | locale_url }}  # => '/es/about/' (if page locale is 'es')
+      def locale_url(url, locale = nil)
+        locale ||= current_locale
+        return url if should_skip?(url, locale)
+
+        "/#{locale}#{url}"
+      end
+
+      # 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/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,
+      # then applies the target locale using the standard locale_url logic.
+      #
+      # @param url [String] The current URL (may or may not have a locale prefix)
+      # @param target_locale [String] The target locale code (e.g., 'es', 'fr', 'pt_BR')
+      # @return [String] The URL for the target locale, or original URL if locale is invalid
+      # @example
+      #   <!-- Current page is /es/about/, switch to French -->
+      #   {{ page.url | switch_locale_url: 'fr' }}  # => '/fr/about/'
+      #
+      #   <!-- Build a language switcher -->
+      #   <a href="{{ page.url | switch_locale_url: 'es' }}">Español</a>
+      #   <a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
+      #   <a href="{{ page.url | switch_locale_url: 'pt' }}">Português</a>
+      def switch_locale_url(url, target_locale)
+        # Validate target locale is configured
+        return url unless valid_target_locale?(target_locale)
+
+        # Get base URL without locale prefix
+        base_url_value = base_url(url)
+
+        # Apply target locale using existing locale_url logic
+        locale_url(base_url_value, target_locale)
+      end
+
+      private
+
+      def current_locale
+        page = @context.registers[:page]
+        return nil unless page
+
+        if page.is_a?(Hash)
+          page.dig("data", "locale")
+        else
+          page&.data&.[]("locale")
+        end
+      rescue StandardError => e
+        Jekyll.logger.warn "Localization", "Error retrieving current locale: #{e.message}"
+        nil
+      end
+
+      def should_skip?(url, locale)
+        url_str = url.to_s
+
+        skip_checks = [
+          invalid_locale?(locale),
+          already_localized?(url_str),
+          external_url?(url_str),
+          protocol_url?(url_str),
+          anchor_only?(url_str),
+          relative_path?(url_str),
+          !root_relative_path?(url_str),
+        ]
+
+        skip_checks.any?
+      end
+
+      def invalid_locale?(locale)
+        locale.nil? || locale.empty? || locale == "en"
+      end
+
+      def already_localized?(url_str)
+        %r!^/[a-z]{2}(?:[_-][A-Z]{2})?(?=/|\?)!.match?(url_str)
+      end
+
+      def external_url?(url_str)
+        %r!^https?://!.match?(url_str)
+      end
+
+      def protocol_url?(url_str)
+        %r!^[a-z]+:!.match?(url_str)
+      end
+
+      def anchor_only?(url_str)
+        url_str.start_with?("#")
+      end
+
+      def relative_path?(url_str)
+        url_str.start_with?("..")
+      end
+
+      def root_relative_path?(url_str)
+        url_str.start_with?("/")
+      end
+
+      def valid_target_locale?(locale)
+        return false if locale.nil? || locale.empty?
+        return true if locale == "en" # English is always valid
+
+        # Get configured locales from page or site config
+        locales_config = configured_locales
+        locales_config.include?(locale)
+      end
+
+      def configured_locales
+        page = @context.registers[:page]
+
+        # Try to get from page data first (most specific)
+        if page
+          locales = if page.is_a?(Hash)
+                      page.dig("with_locales_data", "locales")
+                    else
+                      page.data&.dig("with_locales_data", "locales")
+                    end
+          return locales if locales && !locales.empty?
+        end
+
+        # Fallback to empty array if not configured
+        []
+      end
+
+      def base_url(url)
+        page = @context.registers[:page]
+
+        # Try to get original_url from page data (preferred method)
+        if page
+          original = if page.is_a?(Hash)
+                       page.dig("data", "original_url") || page["original_url"]
+                     else
+                       page.data&.[]("original_url")
+                     end
+          return original if original
+        end
+
+        # Fallback: strip locale prefix from current URL
+        strip_locale_from_url(url)
+      end
+
+      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})?)(?=/|$)!, "")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "reader"
+require_relative "manager"
+require_relative "path_builder"
+
+module Jekyll
+  module L10n
+    # Loads PO files from disk with automatic caching.
+    #
+    # PoFileLoader handles loading PO files and managing the global in-memory cache
+    # to avoid redundant disk I/O. It constructs proper file paths for locale and
+    # page combinations, checks the cache first, and reads from disk only when needed.
+    #
+    # Key responsibilities:
+    # * Check global cache for already-loaded files
+    # * Construct file paths for locale/page combinations
+    # * Load PO files from disk when not cached
+    # * Parse PO file content into translation hashes
+    # * Cache parsed translations for reuse
+    # * Handle file-not-found gracefully (return empty hash)
+    # * Log errors during loading
+    #
+    # @example
+    #   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
+    class PoFileLoader
+      # Load a PO file with caching.
+      #
+      # First checks the global PoFileManager 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.
+      #
+      # @param source [String] Site source directory
+      # @param locales_dir [String] Locales directory name (e.g., '_locales')
+      # @param locale [String] Target locale code (e.g., 'es', 'fr')
+      # @param page_path [String, nil] Optional page path for page-specific file.
+      #   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)
+        return {} unless File.exist?(po_path)
+
+        load_and_cache(cache_key, po_path)
+      end
+
+      def self.load_and_cache(cache_key, po_path)
+        translations = PoFileReader.parse(po_path)
+        PoFileManager.cache[cache_key] = translations
+        translations
+      rescue StandardError => e
+        Jekyll.logger.warn "Localization", "Error loading PO file #{po_path}: #{e.message}"
+        {}
+      end
+    end
+  end
+end