jekyll-l10n 1.0.5

data/lib/jekyll-l10n/utils/translation_resolver.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "text_normalizer"
+require_relative "html_elements"
+
+module Jekyll
+  module L10n
+    # Resolves translations for text nodes with fallback to block-level translations.
+    #
+    # TranslationResolver looks up translations for normalized text, first trying
+    # direct text node matches, then falling back to block-level translations when
+    # text is part of a larger block element with its own translation. This enables
+    # translating entire paragraphs as single units instead of word-by-word.
+    #
+    # Key responsibilities:
+    # * Look up direct translation for text node
+    # * Fall back to block-level translation if available
+    # * Return appropriate translation or nil if none found
+    #
+    # @example
+    #   translation = TranslationResolver.resolve(node, "Hello", translations)
+    #   # Returns translated text if available, nil otherwise
+    class TranslationResolver
+      # Resolve a translation for a text node.
+      #
+      # Attempts direct lookup of the normalized text in translations hash.
+      # If not found, checks if the text is part of a block element with
+      # a block-level translation and returns that.
+      #
+      # @param node [Nokogiri::XML::Node] Text node being translated
+      # @param text [String] Normalized text content
+      # @param translations [Hash] Translation hash mapping text to translations
+      # @return [String, nil] Translated text if found, nil otherwise
+      def self.resolve(node, text, translations)
+        return nil unless node && text && translations
+
+        direct_translation = translations[text]
+        return direct_translation if direct_translation
+
+        try_block_level_translation(node, text, translations)
+      end
+
+      # Attempt block-level translation for text nodes that are part of larger blocks.
+      #
+      # Checks if a text node is part of a larger block element (like a paragraph)
+      # that has a complete translation. Only returns block translation if the text
+      # node alone doesn't have a direct translation but the entire block does.
+      #
+      # Security consideration: Returns nil if the block contains protected elements
+      # (script, style, pre tags) to prevent unsafe translation application.
+      #
+      # @param node [Nokogiri::XML::Node] Text node being translated
+      # @param text [String] Normalized text of the node
+      # @param translations [Hash] Translation hash mapping text to translations
+      # @return [String, nil] Block-level translation if available, nil otherwise
+      #
+      # @example
+      #   # For text "text" in "<p><script>...</script> text</p>"
+      #   # Returns nil (protected element present, prevents block translation)
+      #   TranslationResolver.try_block_level_translation(node, "text", translations)
+      def self.try_block_level_translation(node, text, translations)
+        return nil unless node.parent && content_element?(node.parent)
+
+        # Don't attempt block-level translation if parent contains protected elements
+        # (script, style, pre). These cannot be safely applied at block level.
+        return nil if contains_protected_elements?(node.parent)
+
+        block_text = BlockTextExtractor.extract(node.parent)
+        return nil unless block_text && block_text != text
+
+        translations[block_text]
+      end
+
+      def self.content_element?(node)
+        return false unless node
+        return false unless node.element?
+
+        HtmlElements::CONTENT_ELEMENTS.include?(node.name)
+      end
+
+      # Check if an element contains protected child elements that block translations.
+      #
+      # Protected elements (script, style, pre) cannot have their surrounding text
+      # translated at the block level because:
+      # * script/style: Security and functionality reasons (executable content)
+      # * pre: Multi-line code blocks where translations break formatting
+      #
+      # This is a shared utility used by both HtmlTranslator and TranslationResolver
+      # to ensure consistent protection of sensitive content across the codebase.
+      #
+      # @param node [Nokogiri::XML::Node] Element to check
+      # @return [Boolean] true if node contains protected elements, false otherwise
+      #
+      # @example
+      #   doc = Nokogiri::HTML('<p><script>alert("xss")</script> text</p>')
+      #   para = doc.xpath('//p').first
+      #   TranslationResolver.contains_protected_elements?(para)
+      #   # => true
+      #
+      # @example
+      #   doc = Nokogiri::HTML('<p><code>inline</code> text</p>')
+      #   para = doc.xpath('//p').first
+      #   TranslationResolver.contains_protected_elements?(para)
+      #   # => false (code is allowed, only script/style/pre are protected)
+      def self.contains_protected_elements?(node)
+        return false unless node.element?
+
+        # Block block-level translation for script, style (security/functionality),
+        # and pre (multi-line code blocks). These cannot be safely applied at block level.
+        protected_elements = %w(script style pre)
+        node.children.any? { |child| child.element? && protected_elements.include?(child.name) }
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/url_path_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Builds file paths from URLs and vice versa.
+    #
+    # UrlPathBuilder provides conversions between Jekyll URLs and file system
+    # paths, handling root paths specially and normalizing separators. It supports
+    # both regular URLs and PO page paths used for translation files.
+    #
+    # Key responsibilities:
+    # * Normalize URLs (strip leading/trailing slashes)
+    # * Convert URLs to file paths
+    # * Convert URLs to PO page paths
+    # * Calculate relative paths from absolute paths
+    #
+    # @example
+    #   file_path = UrlPathBuilder.url_to_file_path('/docs/page.html')
+    #   # Returns 'docs/page.html/index.html'
+    module UrlPathBuilder
+      extend self
+
+      # Normalize a URL by removing leading and trailing slashes.
+      #
+      # @param url [String] URL to normalize
+      # @return [String] Normalized URL
+      def normalize_url(url)
+        url.sub(%r!^/!, "").sub(%r!/$!, "")
+      end
+
+      # Convert a URL to a file system path.
+      #
+      # Converts Jekyll URL to the path it would be written to on disk,
+      # using index.html for directory-based URLs.
+      #
+      # @param url [String] Jekyll URL (e.g., '/docs/page.html')
+      # @return [String] File path (e.g., 'docs/page.html/index.html')
+      def url_to_file_path(url)
+        "#{normalize_url(url)}/index.html"
+      end
+
+      # Convert a URL to a PO page path for translation files.
+      #
+      # Handles root path specially (converts to 'index'). Used when saving
+      # page-specific translation files.
+      #
+      # @param url [String] Jekyll URL
+      # @return [String] PO page path (e.g., 'docs/page.html/index.html')
+      def url_to_po_page_path(url)
+        path = normalize_url(url)
+        path = "index" if path.empty?
+        "#{path}/index.html"
+      end
+
+      # Calculate relative path from destination directory.
+      #
+      # @param file_path [String] Absolute file path
+      # @param dest [String] Destination directory to remove from path
+      # @return [String] Relative path
+      def relative_path(file_path, dest)
+        file_path.sub(dest, "").sub(%r!^/!, "")
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/url_transformer.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Jekyll
+  module L10n
+    # Transforms relative URLs in HTML to include locale prefixes.
+    #
+    # UrlTransformer modifies href attributes in links to prefix them with
+    # the target locale (e.g., /docs/page.html becomes /es/docs/page.html).
+    # It preserves external links, anchors, mailto, tel links, and links
+    # already containing locale prefixes. Skips English locale (default language).
+    #
+    # Key responsibilities:
+    # * Identify relative links to transform
+    # * Add locale prefix to href values
+    # * Preserve external links and special URLs
+    # * Skip already-localized URLs
+    # * Handle baseurl paths correctly
+    # * Remove auto-inserted meta tags
+    #
+    # @example
+    #   html = '<a href="/docs/page.html">Link</a>'
+    #   transformed = UrlTransformer.transform(html, 'es', '/baseurl')
+    #   # Returns '<a href="/baseurl/es/docs/page.html">Link</a>'
+    class UrlTransformer
+      class << self
+        # Transform all relative URLs in HTML to include locale prefix.
+        #
+        # Parses HTML document, identifies relative links, adds locale prefix,
+        # removes auto-inserted meta tags, and returns transformed HTML.
+        #
+        # @param html [String] HTML content with URLs to transform
+        # @param locale [String] Target locale code (e.g., 'es', 'fr')
+        # @param baseurl [String] Base URL for site (e.g., '/baseurl')
+        # @return [String] HTML with locale-prefixed URLs
+        def transform(html, locale, baseurl)
+          return html if should_skip_transform?(locale)
+
+          # Use Nokogiri::HTML to properly parse full HTML documents while preserving
+          # DOCTYPE, html tag, and document structure. Auto-inserted meta tags are
+          # removed via regex post-processing (same approach as HtmlTranslator).
+          # See: spec/regression/nokogiri_meta_tag_spec.rb for regression tests
+          doc = Nokogiri::HTML(html)
+
+          transform_document(doc, locale, baseurl)
+
+          result = doc.to_html
+
+          # Remove the auto-inserted meta tag by libxml2 during HTML serialization
+          # Matches: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+          pattern = %r!<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\n?!
+          result.gsub(pattern, "")
+        end
+
+        # Transform URLs in a parsed HTML document.
+        #
+        # Modifies href attributes of links in the parsed document in place.
+        # Useful when document is already parsed to avoid re-parsing.
+        #
+        # @param doc [Nokogiri::HTML::Document] Parsed HTML document
+        # @param locale [String] Target locale code
+        # @param baseurl [String] Base URL for site
+        # @return [void]
+        def transform_document(doc, locale, baseurl)
+          return if should_skip_transform?(locale)
+
+          doc.css("a[href]").each do |link|
+            href = link["href"]
+            next unless should_transform_href?(href, locale, baseurl)
+
+            next if language_dropdown_link?(link)
+
+            link["href"] = add_locale_prefix(href, locale, baseurl)
+          end
+        end
+
+        private
+
+        def should_skip_transform?(locale)
+          return true if locale.nil? || locale.empty?
+          return true if locale == "en"
+
+          false
+        end
+
+        def should_transform_href?(href, locale, _baseurl)
+          return false if invalid_href?(href)
+          return false if external_or_special_link?(href)
+          return false if relative_path?(href)
+          return false if already_localized?(href, locale)
+
+          true
+        end
+
+        def invalid_href?(href)
+          href.nil? || href.empty?
+        end
+
+        def external_or_special_link?(href)
+          href.start_with?("#", "http://", "https://", "mailto:", "tel:")
+        end
+
+        def relative_path?(href)
+          href.start_with?(".")
+        end
+
+        def already_localized?(href, locale)
+          href.start_with?("/#{locale}/") || locale_prefix?(href)
+        end
+
+        def language_dropdown_link?(link)
+          link_classes = link["class"] || ""
+          link_classes.split.any? { |c| c == "dropdown-item" }
+        end
+
+        def locale_prefix?(href)
+          path_without_leading_slash = href.sub(%r!^/!, "")
+          return false if path_without_leading_slash.empty?
+
+          parts = path_without_leading_slash.split("/")
+          return false if parts.empty?
+
+          first_part = parts.first
+          first_part.match?(%r!^[a-z]{2}(?:_[A-Z]{2})?$!)
+        end
+
+        def add_locale_prefix(href, locale, baseurl)
+          return "/#{locale}#{href}" unless baseurl && !baseurl.empty?
+
+          if href.start_with?(baseurl)
+            relative_path = href[baseurl.length..]
+            "#{baseurl}/#{locale}#{relative_path}"
+          else
+            "#{baseurl}/#{locale}#{href}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/xpath_reference_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "url_path_builder"
+
+module Jekyll
+  module L10n
+    # Generates file location references for extracted strings.
+    #
+    # XPathReferenceGenerator creates location references for extracted
+    # translatable strings in the format "file_path:line_number". These references
+    # appear as comments in PO files to help translators locate text in the
+    # original source. Note: Despite the module name, these are file location
+    # references, not XPath expressions.
+    #
+    # Key responsibilities:
+    # * Generate location references from DOM nodes
+    # * Include file path and line number
+    # * Format references for PO file comments
+    #
+    # @example
+    #   ref = XPathReferenceGenerator.generate(node, 'docs/index.html', '_site')
+    #   # Returns 'docs/index.html:42' (42 is line number in HTML)
+    module XPathReferenceGenerator
+      extend self
+
+      # Generate a reference for an extracted string.
+      #
+      # Creates a reference in the format "file_path:line_number" for use as
+      # a PO file comment marking where a string was extracted from.
+      #
+      # @param node [Nokogiri::XML::Node] DOM node where string was found
+      # @param file_path [String] Path to HTML file being processed
+      # @param dest [String] Destination directory (stripped to get relative path)
+      # @param _attr_name [String, nil] Optional attribute name (defaults to nil; maintained
+      #   for API compatibility)
+      # @return [String] Reference in format "relative_path:line_number"
+      def generate(node, file_path, dest, _attr_name = nil)
+        relative_path = UrlPathBuilder.relative_path(file_path, dest)
+        line_number = node.line.to_s
+
+        "#{relative_path}:#{line_number}"
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # The version of the jekyll-l10n gem.
+    #
+    # Updated with each release to reflect the current version.
+    VERSION = "1.0.0"
+  end
+end

data/lib/jekyll-l10n.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+# # jekyll-l10n: Complete Site Localization for Jekyll
+#
+# A comprehensive localization plugin for Jekyll that provides GNU Gettext-based translation
+# management. The plugin automatically creates locale-prefixed page variants and applies
+# translations using PO (Portable Object) files, the standard format for open-source translations.
+#
+# ## Core Features
+#
+# - **Automatic Page Duplication**: Creates locale-specific page variants with proper URL prefixes
+# - **HTML String Extraction**: Automatically finds translatable strings and attributes in
+#   generated HTML
+# - **PO File Management**: Reads, writes, and merges GNU Gettext PO files with caching
+# - **Flexible Translation Application**: Applies translations with configurable fallback modes
+# - **LibreTranslate Integration**: Automatic translation via LibreTranslate API (optional)
+# - **Compendium Support**: Shared translation files across multiple pages
+# - **Incremental Builds**: Optimizes performance by skipping unchanged content
+# - **Liquid Filters**: Template helpers for locale-aware URL generation
+#
+# ## Architecture Overview
+#
+# The plugin consists of five major modules, each handling a specific aspect of localization:
+#
+# ### 1. Jekyll Integration (`Jekyll::L10n::Jekyll`)
+# Integrates localization into the Jekyll build pipeline through hooks and generators.
+# - **Generator**: Creates localized page variants during generation phase
+# - **LocalizedPage**: Represents a page in a specific locale
+# - **PostWriteProcessor**: Extracts strings and reprocesses translations after build
+# - **UrlFilter**: Liquid filters for locale-aware URL generation
+#
+# ### 2. HTML Extraction (`Jekyll::L10n::Extraction`)
+# Extracts translatable content from generated HTML and maintains PO files.
+# - **Extractor**: Main orchestrator for extraction workflow
+# - **HtmlStringExtractor**: Finds translatable strings and attributes
+# - **DomTextExtractor**: Extracts text nodes with file location references
+# - **DomAttributeExtractor**: Extracts configurable HTML attributes
+# - **ResultSaver**: Writes extracted strings to PO files
+#
+# ### 3. HTML Translation (`Jekyll::L10n::Translation`)
+# Applies translations from PO files to HTML documents.
+# - **Translator**: Main orchestrator for translation workflow
+# - **HtmlTranslator**: Applies translations to HTML DOM nodes
+# - **PageTranslationLoader**: Loads translations with compendium support
+# - **BlockTextExtractor**: Context-aware text extraction
+# - **LibreTranslator**: LibreTranslate API integration
+#
+# ### 4. PO File Management (`Jekyll::L10n::PoFile`)
+# Manages GNU Gettext PO file operations with caching.
+# - **Manager**: Orchestrates PO file operations and caching
+# - **Reader**: Parses PO files into Ruby objects
+# - **Writer**: Serializes PO entries back to file format
+# - **Merger**: Merges translations from compendium files
+# - **Loader**: Loads and validates PO files
+#
+# ### 5. Utilities (`Jekyll::L10n`)
+# Common utilities supporting all other modules.
+# - **TextNormalizer**: Normalizes whitespace for consistent matching
+# - **TextValidator**: Validates extractable text
+# - **TranslationResolver**: Selects best translation with fallback
+# - **HtmlParser**: DOM parsing with safety guards
+# - **PathBuilder**: Constructs locale-specific file paths
+#
+# ## Configuration
+#
+# Configuration can be specified in Jekyll `_config.yml` or in individual page front matter:
+#
+# ```yaml
+# plugins:
+#   - jekyll-l10n
+#
+# localization_gettext:
+#   with_locales_data:
+#     locales: [es, fr, pt, de]
+#     extract_on_build: true
+#     translation:
+#       fallback: english
+#       libretranslate_enabled: true
+#       libretranslate_api_url: "https://api.libretranslate.de"
+#     logging:
+#       debug: false
+# ```
+#
+# Page-level configuration overrides site-level configuration:
+#
+# ```markdown
+# ---
+# with_locales: true
+# with_locales_data:
+#   locales: [es, fr]
+# ---
+# ```
+#
+# ## Usage Examples
+#
+# ### Enable localization for a page
+#
+# ```markdown
+# ---
+# title: About Us
+# with_locales: true
+# with_locales_data:
+#   locales: [es, fr, pt_BR]
+# ---
+# Content here...
+# ```
+#
+# ### Use locale-aware URLs in templates
+#
+# ```liquid
+# <!-- Link with current locale -->
+# <a href="{{ '/about/' | locale_url }}">About</a>
+#
+# <!-- Switch to different locale -->
+# <a href="{{ page.url | switch_locale_url: 'es' }}">Español</a>
+#
+# <!-- Build language switcher -->
+# {% for locale in page.with_locales_data.locales %}
+#   <a href="{{ page.url | switch_locale_url: locale }}">
+#     {{ locale | upcase }}
+#   </a>
+# {% endfor %}
+# ```
+#
+# ## Build Pipeline
+#
+# 1. **Generate Phase**: Generator creates LocalizedPage instances for each locale
+# 2. **Render Phase**: Jekyll renders all pages (including localized variants)
+# 3. **Post-Render Phase**: Translator hook applies translations to localized pages
+# 4. **Write Phase**: Jekyll writes HTML to disk
+# 5. **Post-Write Phase**: PostWriteProcessor extracts new strings and updates translations
+#
+# ## Translation Workflow Timing
+#
+# The plugin applies translations in two phases:
+#
+# 1. **Initial Build (post_render)**: Localized pages are translated during Jekyll's
+#    render phase using existing PO files
+# 2. **Post-Extraction (post_write)**: When new strings are extracted and PO files
+#    updated, localized HTML is immediately reprocessed with new translations
+#
+# This dual-phase approach ensures both incremental builds (using cached translations)
+# and immediate translation updates (when new strings are found).
+#
+# ## File Locations
+#
+# - **Source pages**: `src/**/*.md` (marked with `with_locales: true`)
+# - **Page-specific PO files**: `_locales/{locale}/{page_path}.po`
+# - **Compendium PO files**: `_locales/{locale}.po` (shared translations for locale)
+# - **Output**: `_site/[locale]/path/to/page/index.html`
+#
+# ## Terminology
+#
+# - **Source pages**: Pages marked with `with_locales: true` in front matter
+# - **Localized pages**: Generated LocalizedPage instances (marked with `localized: true`)
+# - **Compendium**: Locale-level shared translations at `_locales/{locale}.po`
+# - **Page-specific PO files**: Per-page translations at `_locales/{locale}/{page_path}.po`
+# - **String extraction**: Finding translatable text content and HTML attribute values
+#
+# @see Jekyll::L10n::Generator for page generation
+# @see Jekyll::L10n::Translator for translation application
+# @see Jekyll::L10n::Extractor for string extraction
+# @see Jekyll::L10n::UrlFilter for liquid filters
+
+require_relative "jekyll-l10n/version"
+require_relative "jekyll-l10n/constants"
+require_relative "jekyll-l10n/errors"
+require_relative "jekyll-l10n/po_file/reader"
+require_relative "jekyll-l10n/po_file/writer"
+require_relative "jekyll-l10n/po_file/loader"
+require_relative "jekyll-l10n/po_file/merger"
+require_relative "jekyll-l10n/po_file/path_builder"
+require_relative "jekyll-l10n/po_file/manager"
+require_relative "jekyll-l10n/extraction/dom_text_extractor"
+require_relative "jekyll-l10n/extraction/dom_attribute_extractor"
+require_relative "jekyll-l10n/extraction/html_string_extractor"
+require_relative "jekyll-l10n/extraction/config_loader"
+require_relative "jekyll-l10n/extraction/result_saver"
+require_relative "jekyll-l10n/extraction/compendium_translator"
+require_relative "jekyll-l10n/extraction/compendium_merger"
+require_relative "jekyll-l10n/extraction/logger"
+require_relative "jekyll-l10n/extraction/extractor"
+require_relative "jekyll-l10n/translation/html_translator"
+require_relative "jekyll-l10n/translation/page_translation_loader"
+require_relative "jekyll-l10n/translation/translator"
+require_relative "jekyll-l10n/translation/block_text_extractor"
+require_relative "jekyll-l10n/jekyll/localized_page"
+require_relative "jekyll-l10n/jekyll/regeneration_checker"
+require_relative "jekyll-l10n/jekyll/generator"
+require_relative "jekyll-l10n/jekyll/post_write_processor"
+require_relative "jekyll-l10n/jekyll/post_write_html_reprocessor"
+require_relative "jekyll-l10n/jekyll/file_sync"
+require_relative "jekyll-l10n/jekyll/page_locator"
+require_relative "jekyll-l10n/jekyll/page_writer"
+require_relative "jekyll-l10n/jekyll/url_filter"
+require_relative "jekyll-l10n/utils/text_normalizer"
+require_relative "jekyll-l10n/utils/translation_resolver"
+require_relative "jekyll-l10n/utils/html_elements"
+require_relative "jekyll-l10n/utils/html_parser"
+require_relative "jekyll-l10n/utils/html_text_utils"
+require_relative "jekyll-l10n/utils/debug_logger"
+require_relative "jekyll-l10n/utils/url_path_builder"
+require_relative "jekyll-l10n/utils/xpath_reference_generator"
+require_relative "jekyll-l10n/utils/page_locales_config"
+require_relative "jekyll-l10n/utils/text_validator"
+require_relative "jekyll-l10n/utils/url_transformer"
+require_relative "jekyll-l10n/utils/site_config_accessor"
+require_relative "jekyll-l10n/utils/error_handler"
+require_relative "jekyll-l10n/utils/logger_formatter"
+require_relative "jekyll-l10n/utils/external_link_icon_preserver"
+
+module Jekyll
+  # Main plugin namespace
+  module L10n
+    # Complete Site Localization for Jekyll
+    #
+    # Main plugin module providing GNU Gettext-based translation management
+    # with automatic page duplication, HTML string extraction, and translation
+    # application. This module serves as the entry point for the plugin and
+    # coordinates all localization functionality.
+    #
+    # Key public APIs:
+    # - {Jekyll::L10n::Generator} - Creates locale-prefixed page variants
+    # - {Jekyll::L10n::Translator} - Applies translations to localized pages
+    # - {Jekyll::L10n::Extractor} - Extracts translatable strings from HTML
+    # - {Jekyll::L10n::UrlFilter} - Liquid filters for locale-aware URLs
+    #
+    # @see lib/jekyll-l10n.rb for complete architecture overview and build pipeline
+
+    # Include Constants module to provide centralized constant definitions
+    include Constants
+
+    # Module-level convenience constants that reference the Constants module
+    MIN_TRANSLATABLE_LENGTH = Constants::MIN_TRANSLATABLE_LENGTH
+    DEFAULT_LOCALES_DIR = Constants::DEFAULT_LOCALES_DIR
+    DEFAULT_FALLBACK_MODE = Constants::DEFAULT_FALLBACK_MODE
+    DEFAULT_TRANSLATABLE_ATTRIBUTES = Constants::DEFAULT_TRANSLATABLE_ATTRIBUTES
+
+    # Transform URLs in HTML to include locale prefix.
+    #
+    # Walks the HTML document and transforms relative URLs to be locale-aware
+    # by adding locale prefixes. Useful for translating internal links in
+    # localized pages.
+    #
+    # @param html [String] HTML content to transform
+    # @param locale [String] Locale code for URL prefix (e.g., 'es', 'fr')
+    # @param baseurl [String] Base URL for relative URL transformation
+    # @return [String] HTML with transformed URLs
+    # @example
+    #   html_with_locale_urls = Jekyll::L10n.transform(html, 'es', '/mysite')
+    def self.transform(html, locale, baseurl)
+      UrlTransformer.transform(html, locale, baseurl)
+    end
+  end
+end
+
+Jekyll::Hooks.register :pages, :post_render do |page|
+  next unless page.data["localized"] == true
+
+  translator = Jekyll::L10n::Translator.new(page)
+  translator.translate
+end
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  Jekyll::L10n::PostWriteProcessor.new(site).process_localizations
+end
+
+Liquid::Template.register_filter(Jekyll::L10n::UrlFilter)