jekyll-l10n 1.0.5

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../translation/translator"
+require_relative "page_writer"
+require_relative "localized_page_mapper"
+require_relative "../utils/url_path_builder"
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # File Synchronization Manager - Syncs localized pages and applies translations
+    #
+    # This class manages the synchronization of generated HTML content to localized page variants
+    # and applies translations to each variant. It works in coordination with Jekyll's file
+    # writing system to ensure all locale-specific content is properly translated.
+    #
+    # The sync process:
+    # 1. Builds a map of localized pages grouped by original URL
+    # 2. For each original page, finds its localized variants
+    # 3. Reads the original HTML file content
+    # 4. Applies translations to each localized variant
+    # 5. Writes the translated HTML to disk
+    #
+    # This class is typically used during the post-write phase to handle final translation
+    # application after Jekyll has written all files to disk.
+    #
+    # @example Usage (typically internal)
+    #   file_reader = SomeFileReader.new
+    #   page_writer = PageWriter.new
+    #   syncer = LocalizationFileSync.new(site, file_reader, page_writer)
+    #   syncer.sync
+    #
+    class LocalizationFileSync
+      # Initialize the file synchronization manager
+      #
+      # @param site [Jekyll::Site] The Jekyll site object
+      # @param file_reader [Object] A file reader object with a `read(page)` method
+      # @param page_writer [PageWriter] A page writer object to write translated HTML
+      def initialize(site, file_reader, page_writer)
+        @site = site
+        @file_reader = file_reader
+        @page_writer = page_writer
+      end
+
+      # Synchronize and translate all localized pages
+      #
+      # Builds a map of localized pages, reads original HTML content, and applies
+      # translations to each locale variant. Logs the process for debugging.
+      #
+      # @return [void]
+      def sync
+        Jekyll.logger.info "Localization", "Starting file sync process"
+        localized_pages_by_url = LocalizedPageMapper.build_map(@site)
+        count = localized_pages_by_url.keys.length
+        Jekyll.logger.info "Localization",
+                           "Found #{count} pages with localized versions"
+        sync_files_and_apply_translations(localized_pages_by_url)
+      end
+
+      private
+
+      def sync_files_and_apply_translations(localized_pages_by_url)
+        @site.pages.each do |page|
+          with_locales = page.data["with_locales"]
+          is_localized = page.data["localized"]
+          log_page_check(page.url, with_locales, is_localized)
+          next unless page.data["with_locales"] == true && page.data["localized"] != true
+
+          LoggerFormatter.debug_if_enabled("FileSync",
+                                           "Processing page for translation: #{page.url}")
+          original_content = @file_reader.read(page)
+          next unless original_content
+
+          apply_translations_to_localized_pages(page, localized_pages_by_url, original_content)
+        end
+      end
+
+      def apply_translations_to_localized_pages(page, localized_pages_by_url, original_content)
+        return unless localized_pages_by_url[page.url]
+
+        localized_pages_by_url[page.url].each do |localized_page|
+          translate_and_write_localized_page(localized_page, original_content)
+        end
+      end
+
+      def translate_and_write_localized_page(localized_page, original_content)
+        content_to_translate = if localized_page.output && !localized_page.output.empty?
+                                 localized_page.output
+                               else
+                                 original_content
+                               end
+
+        localized_page.instance_variable_set(:@output, content_to_translate)
+
+        locale = localized_page.data["locale"]
+        baseurl = @site.config["baseurl"]
+
+        translator = Translator.new(localized_page)
+
+        @page_writer.translate_and_write(localized_page, translator, locale, baseurl)
+      end
+
+      def log_page_check(url, with_locales, is_localized)
+        LoggerFormatter.debug_if_enabled("FileSync",
+                                         "Checking page: #{url} (with_locales: #{with_locales}, " \
+                                         "localized: #{is_localized})")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "regeneration_checker"
+
+module Jekyll
+  module L10n
+    # Localized Page Generator - Creates locale-prefixed copies of pages during Jekyll build
+    #
+    # This is the main Jekyll integration point for the localization plugin. It runs as a
+    # low-priority generator during the Jekyll build process, creating duplicate pages for each
+    # configured locale. Each localized page inherits content and metadata from the source page
+    # but includes locale-prefixed URLs.
+    #
+    # Key responsibilities:
+    # - Identify pages marked for localization (with_locales: true)
+    # - Extract configured locales from page front matter
+    # - Create LocalizedPage instances for each locale variant
+    # - Optimize regeneration by skipping unchanged pages
+    #
+    # The generator respects Jekyll's incremental build mode and only regenerates pages when
+    # the source page or configuration has changed, improving rebuild performance.
+    #
+    # @example Usage in Jekyll site configuration
+    #   # _config.yml
+    #   plugins:
+    #     - jekyll-l10n
+    #
+    # @example Marking pages for localization
+    #   # src/page.md
+    #   ---
+    #   with_locales: true
+    #   with_locales_data:
+    #     locales: [es, fr, pt, de]
+    #   ---
+    #
+    class Generator < Jekyll::Generator
+      priority :low
+
+      # Generate localized pages for all marked pages in the Jekyll site
+      #
+      # This method is automatically called by Jekyll during the generate phase.
+      # It iterates through all pages in the site, identifies those marked for localization,
+      # and creates locale-specific variants.
+      #
+      # @param site [Jekyll::Site] The Jekyll site object containing pages to process
+      # @return [void]
+      # @see LocalizedPage for details on page structure
+      def generate(site)
+        Jekyll.logger.info "Localization", "Generating localized pages..."
+        generate_localized_pages(site)
+      end
+
+      private
+
+      def generate_localized_pages(site)
+        original_pages = site.pages.dup
+        checker = Jekyll::L10n::RegenerationChecker.new(site)
+
+        original_pages.each do |page|
+          next unless should_localize_page?(page)
+
+          locales = get_page_locales(page)
+
+          locales.each do |locale|
+            next unless valid_locale_code?(locale)
+
+            if checker.should_regenerate?(page, locale)
+              localized_page = create_localized_page(site, page, locale)
+              site.pages << localized_page
+            end
+          end
+        end
+      end
+
+      def should_localize_page?(page)
+        return false if page.data["localized"] == true
+
+        page.data["with_locales"] == true
+      end
+
+      def get_page_locales(page)
+        data = page.data["with_locales_data"]
+
+        locales = if data.is_a?(Hash)
+                    data["locales"] || []
+                  else
+                    []
+                  end
+
+        locales.select { |l| valid_locale_code?(l) }
+      end
+
+      def create_localized_page(site, page, locale)
+        new_dir = "/#{locale}#{page.dir}"
+        LocalizedPage.new(:site => site, :base => site.source, :dir => new_dir, :page => page,
+                          :locale => locale)
+      end
+
+      def valid_locale_code?(locale)
+        return false unless locale.is_a?(String)
+
+        locale.match?(%r!^[a-z]{2}(_[A-Z]{2})?$!)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Localized Page - Represents a Jekyll page in a specific locale
+    #
+    # LocalizedPage extends Jekyll::Page to represent a page content variant for a
+    # specific language.
+    # It inherits content and metadata from the source page while maintaining locale-specific URLs
+    # and data attributes. The locale is included as a URL prefix (e.g., /es/path/to/page/).
+    #
+    # Key responsibilities:
+    # - Maintain both original and localized URLs and paths
+    # - Inherit content and front matter from source page
+    # - Set locale and lang attributes for Liquid templates
+    # - Generate locale-prefixed output paths
+    #
+    # During the post-render phase, LocalizedPage content is translated using translations from
+    # PO files. The translation process happens in the post_render Jekyll hook.
+    #
+    # @example Creating a localized page variant
+    #   page = LocalizedPage.new(site: site, base: site.source, dir: '/es',
+    #                             page: source_page, locale: 'es')
+    #   # Resulting URL: /es/path/to/page/
+    #   # Resulting locale: es
+    #
+    class LocalizedPage < Jekyll::Page
+      # @!attribute [rw] locale
+      #   The BCP 47 locale code for this page variant (e.g., 'es', 'pt_BR')
+      #   @return [String]
+      # @!attribute [rw] lang
+      #   Alias for locale, used in Liquid templates
+      #   @return [String]
+      # @!attribute [rw] original_page
+      #   Reference to the source page before localization
+      #   @return [Jekyll::Page]
+      # @!attribute [rw] original_url
+      #   The URL of the source page before locale prefix was added
+      #   @return [String]
+      attr_accessor :locale, :lang, :original_page, :original_url
+
+      # Initialize a new localized page variant
+      #
+      # Creates a page instance that represents the given page in a specific locale.
+      # Copies all essential attributes from the source page and sets up locale-specific
+      # metadata and URLs.
+      #
+      # Note: This method copies the @output attribute from the source page. In production,
+      # @output is typically nil at this point (during the Generate phase) and gets populated
+      # by Jekyll during the Render phase. This initialization ensures LocalizedPage has the
+      # same @output as its source page, which may be useful in test scenarios or if
+      # LocalizedPage is created after rendering.
+      #
+      # @param site [Jekyll::Site] (keyword) The Jekyll site object
+      # @param base [String] (keyword) The base directory (typically site.source)
+      # @param dir [String] (keyword) The directory path (will be prefixed with locale,
+      #   e.g., '/es/path')
+      # @param page [Jekyll::Page] (keyword) The source page to localize
+      # @param locale [String] (keyword) The BCP 47 locale code (e.g., 'es', 'pt_BR', 'zh_CN')
+      # @return [LocalizedPage] A new localized page instance
+      # @note All parameters are keyword arguments and must be passed by name
+      def initialize(site:, base:, dir:, page:, locale:) # rubocop:disable Metrics/ParameterLists
+        @site = site
+        @base = base
+        @dir = dir
+        @name = page.name
+        @ext = page.ext
+        @output_ext = page.output_ext
+
+        @locale = locale
+        @lang = locale
+        @original_url = page.url
+        @original_page = page
+        @path = page.path
+        @relative_path = page.relative_path
+        @content = page.content
+        @output = page.output
+
+        setup_localized_data(page, locale)
+      end
+
+      # Get the URL placeholder substitutions for this localized page
+      #
+      # Overrides Jekyll::Page's url_placeholders to include the locale prefix in path generation.
+      # This ensures that Jekyll's permalink logic respects the locale prefix.
+      #
+      # @return [Hash<Symbol, String>] Hash of placeholders with locale-prefixed path
+      def url_placeholders
+        placeholders = super
+        placeholders[:path] = "/#{@locale}#{placeholders[:path]}" if placeholders[:path]
+        placeholders
+      end
+
+      # Get the full URL for this localized page
+      #
+      # Returns the page's URL with a locale prefix. For example, if the source page URL is
+      # '/path/to/page/', this returns '/es/path/to/page/' for locale 'es'.
+      # The URL always ends with a trailing slash for consistency.
+      #
+      # @return [String] The locale-prefixed URL (e.g., '/es/path/to/page/')
+      def url
+        url = "/#{@locale}#{@original_url}"
+        url += "/" unless url.end_with?("/")
+        url
+      end
+
+      # Get the destination file path for this localized page
+      #
+      # Computes the full file system path where this page's HTML will be written.
+      # For a page with URL '/es/path/to/page/', this returns 'dest/es/path/to/page/index.html'.
+      #
+      # @param dest [String, nil] The destination directory (defaults to nil, which uses
+      #   site config destination)
+      # @return [String] The full file system path for the output HTML file
+      def destination(dest = nil)
+        dest ||= @site.config["destination"]
+        url_path = url
+        url_path += "/" unless url_path.end_with?("/")
+        "#{dest}#{url_path}index.html"
+      end
+
+      # Convert this localized page to Liquid template data
+      #
+      # Overrides Jekyll::Page's to_liquid to include locale and lang in template context.
+      # This makes the page's locale available to Liquid templates for conditional rendering
+      # and URL generation.
+      #
+      # @return [Hash<String, Object>] Hash of page data for Liquid templates, including locale
+      def to_liquid
+        computed_url = url
+        result = super
+        result["url"] = computed_url
+        result["locale"] = @locale
+        result["lang"] = @lang
+        result
+      end
+
+      private
+
+      def setup_localized_data(page, locale)
+        @data = page.data.dup
+        @data["locale"] = locale
+        @data["lang"] = locale
+        @data["localized"] = true
+        @data["original_url"] = @original_url
+        @data["original_permalink"] = page.data["permalink"] if page.data["permalink"]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # Localized Page Mapper - Indexes generated localized pages by their original URL
+    #
+    # This module builds a mapping of original URLs to their localized page variants.
+    # It scans all pages in the Jekyll site, identifies those marked as localized,
+    # and groups them by their original_url for quick lookup during processing.
+    #
+    # The map structure is: { original_url => [localized_page_1, localized_page_2, ...] }
+    # This enables efficient matching of localized variants back to their source pages.
+    #
+    # @example Usage
+    #   localized_map = LocalizedPageMapper.build_map(site)
+    #   # => { "/about/" => [<LocalizedPage locale="es">, <LocalizedPage locale="fr">] }
+    #
+    module LocalizedPageMapper
+      extend self
+
+      # Build a mapping of original URLs to localized page variants
+      #
+      # Scans all pages in the Jekyll site, finds those marked with `localized: true`,
+      # and groups them by their original_url. Returns a hash with original URLs as keys
+      # and arrays of LocalizedPage objects as values.
+      #
+      # @param site [Jekyll::Site] The Jekyll site object with all generated pages
+      # @return [Hash<String, Array<LocalizedPage>>] Map of original URL to localized variants
+      # @example
+      #   pages_map = LocalizedPageMapper.build_map(site)
+      #   spanish_pages = pages_map["/about/"]  # => [<LocalizedPage locale="es">]
+      def build_map(site)
+        localized_pages = {}
+        site.pages.each do |page|
+          next unless page.data["localized"] == true
+
+          original_url = page.data["original_url"]
+          LoggerFormatter.debug_if_enabled(
+            "LocalizedPageMapper",
+            "Found localized page: #{page.url} (original: #{original_url})"
+          )
+          localized_pages[original_url] ||= []
+          localized_pages[original_url] << page
+        end
+        localized_pages
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Locates original (non-localized) pages by URL.
+    #
+    # OriginalPageLocator builds an index of original pages in the site and
+    # provides fast lookup by URL. This is used during translation to find the
+    # original page configuration when processing localized variants.
+    #
+    # Key responsibilities:
+    # * Index original pages by URL
+    # * Exclude localized page variants from index
+    # * Provide O(1) lookup by URL
+    # * Lazily build index on first use
+    #
+    # @example
+    #   locator = OriginalPageLocator.new(site)
+    #   original_page = locator.find_by_url('/docs/index.html')
+    class OriginalPageLocator
+      # Initialize a new OriginalPageLocator.
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      def initialize(site)
+        @site = site
+        @index = nil
+      end
+
+      # Find an original page by URL.
+      #
+      # Builds index on first call, then uses cached index for subsequent lookups.
+      # Returns nil if page not found.
+      #
+      # @param url [String] Page URL (e.g., '/docs/index.html')
+      # @return [Jekyll::Page, nil] Original page if found, nil otherwise
+      def find_by_url(url)
+        build_index unless @index
+        @index[url]
+      end
+
+      private
+
+      # Build index of original pages by URL.
+      #
+      # Indexes all pages that are not marked as localized, allowing fast
+      # lookup by URL without iterating through site.pages each time.
+      #
+      # @return [void]
+      def build_index
+        @index = {}
+        @site.pages.each do |page|
+          next if page.data["localized"] == true
+
+          @index[page.url] = page
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../utils/url_path_builder"
+require_relative "../translation/html_translator"
+require_relative "../utils/file_operations"
+require_relative "../utils/logger_formatter"
+
+module Jekyll
+  module L10n
+    # Writes localized pages with metadata to disk.
+    #
+    # LocalizedPageWriter translates page output and updates locale metadata
+    # (html lang attribute) before writing localized pages to the build output
+    # directory. It ensures proper directory structure and updates locale information
+    # in the HTML tag.
+    #
+    # Key responsibilities:
+    # * Apply translations to localized page output
+    # * Update HTML lang attribute to target locale
+    # * Create necessary directory structure
+    # * Write localized HTML to disk with UTF-8 encoding
+    # * Clean up auto-inserted meta charset tags
+    # * Handle parse errors gracefully
+    #
+    # @example
+    #   writer = LocalizedPageWriter.new('_site')
+    #   writer.translate_and_write(page, translator, 'es', '/baseurl')
+    #   # Localized page written to disk with translations and lang attribute updated
+    class LocalizedPageWriter
+      # Initialize a new LocalizedPageWriter.
+      #
+      # @param dest [String] Destination build directory
+      def initialize(dest)
+        @dest = dest
+      end
+
+      # Translate page content and write to disk.
+      #
+      # Applies translator, updates HTML lang attribute with locale, ensures
+      # output directory exists, and writes translated HTML to file.
+      #
+      # @param localized_page [Jekyll::Page] Localized page to write
+      # @param translator [Object] Translator object with translate method
+      # @param locale [String] Target locale code
+      # @param _baseurl [String] Base URL (passed for compatibility, not used)
+      # @return [void]
+      def translate_and_write(localized_page, translator, locale, _baseurl)
+        log_debug_info(localized_page, locale, "start")
+        translator.translate
+
+        log_debug_info(localized_page, locale, "after translate")
+        localized_page.output = fix_locale_metadata(localized_page.output, locale)
+
+        log_debug_info(localized_page, locale, "after fix_locale")
+        write_localized_page(localized_page)
+      end
+
+      private
+
+      def log_debug_info(localized_page, locale, phase)
+        LoggerFormatter.debug_if_enabled("PageWriter",
+                                         "#{phase}: URL=#{localized_page.url}, locale=#{locale}, " \
+                                         "output_size=#{localized_page.output&.length || 0}")
+      end
+
+      def write_localized_page(localized_page)
+        localized_file_path = UrlPathBuilder.url_to_file_path(localized_page.url)
+        localized_file = File.join(@dest, localized_file_path)
+        FileOperations.ensure_directory(localized_file)
+
+        LoggerFormatter.debug_if_enabled("PageWriter", "Writing to #{localized_file_path}")
+        FileOperations.write_utf8(localized_file, localized_page.output)
+      end
+
+      def fix_locale_metadata(html, locale)
+        return html unless html && locale
+
+        doc = parse_html(html)
+        update_html_lang_attribute(doc, locale)
+        result = serialize_html(doc)
+        cleanup_auto_inserted_meta_tag(result)
+      rescue StandardError => e
+        Jekyll.logger.error "Localization",
+                            "Failed to parse HTML for locale #{locale}: #{e.message}"
+        html
+      end
+
+      def parse_html(html)
+        # CRITICAL: Nokogiri::HTML auto-inserts <meta http-equiv="Content-Type">
+        # We parse with HTML to access the <html> tag, then remove the auto-inserted
+        # meta tag using regex post-processing.
+        # See: spec/regression/nokogiri_meta_tag_spec.rb
+        Nokogiri::HTML(html)
+      end
+
+      def update_html_lang_attribute(doc, locale)
+        html_tag = doc.at("html")
+
+        if html_tag
+          html_tag["lang"] = locale
+        else
+          Jekyll.logger.warn("Localization",
+                             "No <html> tag found for locale #{locale}, skipping lang attribute")
+        end
+      end
+
+      def serialize_html(doc)
+        doc.to_html
+      end
+
+      def cleanup_auto_inserted_meta_tag(result)
+        # Remove the auto-inserted meta tag by libxml2 during HTML serialization
+        # Matches: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+        # See: spec/regression/nokogiri_meta_tag_spec.rb
+        pattern = %r!<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\n?!
+        result.gsub(pattern, "")
+      end
+    end
+  end
+end