jekyll-l10n 1.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4ab158ff22fa743e5ec910aab7b546e3a56796b2e7c09ed31b4f5acc7e4b123
+  data.tar.gz: b6b3f4a8a4bc06892581b9017b8018cc5d6c2c0b44f8599e3015fa123b29470f
+SHA512:
+  metadata.gz: 809000529424718152cc2c7d9c918d5cf780c9262388001fab8e62c4efeb6c122dce06dd40312b350d3d0fe1761116ea662d915ee03df37c29e1e5f069551630
+  data.tar.gz: 63282d1fad6f225a9e34fb39d56eade8a3fe5965e793993d5aded4a41b43bee55fad61b9d8c36ae3d5cd3d63ef964f771e7196b003d1fa632b3460e0fbba6d85

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alain Reguera Delgado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# jekyll-l10n
+
+`jekyll-l10n` is a Jekyll plugin that streamlines the localization of static
+websites using industry-standard GNU Gettext PO files. Creating multilingual
+sites presents unique challenges: maintaining consistent translations across
+multiple pages, managing translation workflows with non-technical translators,
+and keeping translations synchronized as content evolves. This plugin automates
+these challenges by integrating the proven Gettext workflow directly into your
+Jekyll build pipeline.
+
+The plugin works by extracting translatable strings from your site's generated
+HTML and organizing them into PO files that translators can edit using standard
+translation tools. As your content changes, the plugin intelligently updates
+these translation files, preserving existing translations while flagging
+changed or new content. When you rebuild your site, translated strings are
+automatically applied to localized versions of your pages, producing fully
+translated HTML output with locale-prefixed URLs.
+
+![Jekyll site localization](docs/assets/img/jekyll-l10n.png)
+
+Key features include automatic page duplication with locale-specific URL
+prefixes, flexible fallback modes when translations are incomplete (display
+original English, mark untranslated strings, or leave blank), and support for
+compendium files to share common translations across your site. By leveraging
+the standard Gettext format and workflow, `jekyll-l10n` enables collaboration
+with professional translators and integrates with existing translation
+management systems, while keeping your source content in Markdown where it
+belongs.
+
+## Development Setup
+
+To set up your development environment:
+
+```bash
+bundle install          # Install Ruby dependencies
+pip install pre-commit  # Install pre-commit framework
+pre-commit install      # Install pre-commit hooks
+```
+
+This enables pre-commit hooks that automatically check code style and format on each commit.
+
+## Configuration
+
+### Incremental Builds (Performance Optimization)
+
+By default, the plugin regenerates all localized pages on every build. For large
+sites with many locales, this can impact build performance. You can enable
+incremental build support to skip regenerating pages that haven't changed:
+
+```yaml
+localization_gettext:
+  with_locales_data:
+    incremental: true # Enable incremental builds
+```
+
+Or at the top level:
+
+```yaml
+localization_gettext:
+  incremental: true
+```
+
+When incremental mode is enabled, pages are only regenerated if:
+
+- The source page content has been modified
+- Any PO translation files have been updated
+- The Jekyll configuration has changed
+
+This significantly improves build times on subsequent builds when only
+translations or a few pages have changed.
+
+## Machine Translation
+
+For teams without translation resources, the plugin integrates with
+LibreTranslate, a free and open-source machine translation service, to
+automatically translate newly extracted strings during the extraction workflow.
+You can enable this optional integration on a per-locale basis, allowing
+LibreTranslate to generate initial translations for compendia files that serve
+as a foundation for professional translators to refine. This significantly
+reduces the initial translation effort and helps bootstrap localization for new
+content, though professional review is still recommended for
+publication-quality results.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request

data/lib/jekyll-l10n/constants.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Plugin Constants - Central definitions for magic values and configuration defaults
+    #
+    # This module consolidates all constant values used throughout the jekyll-l10n plugin,
+    # eliminating magic numbers and string literals from the codebase. Constants are organized
+    # into logical groups: text validation, fallback modes, formatting, debugging, and defaults.
+    #
+    # All constants are frozen to prevent accidental modification.
+    #
+    # @see PageLocalesConfig for configuration-specific defaults
+    module Constants
+      # ## Text Validation Constants
+
+      # Minimum length for translatable text strings (shorter strings not extracted)
+      # @return [Integer] Always 3
+      MIN_TRANSLATABLE_LENGTH = 3
+
+      # Regular expression pattern for validating locale codes
+      # Matches ISO 639-1 (2 letter language) with optional ISO 3166-1 (2 letter country)
+      # Examples: 'en', 'es', 'fr', 'pt_BR', 'zh_CN'
+      # @return [Regexp]
+      LOCALE_PATTERN = %r!^[a-z]{2}(_[A-Z]{2})?$!.freeze
+
+      # ## Translation Fallback Modes
+
+      # Fallback mode: use original English text if translation not found
+      # @return [String] "english"
+      FALLBACK_MODE_ENGLISH = "english"
+
+      # Fallback mode: wrap untranslated text with markers (e.g., "[UNTRANSLATED: text]")
+      # @return [String] "marker"
+      FALLBACK_MODE_MARKER = "marker"
+
+      # Fallback mode: leave text blank if no translation found
+      # @return [String] "empty"
+      FALLBACK_MODE_EMPTY = "empty"
+
+      # ## Translation Markers
+
+      # Marker used to indicate untranslated strings in marker fallback mode
+      # @return [String] "[UNTRANSLATED]"
+      UNTRANSLATED_MARKER = "[UNTRANSLATED]"
+
+      # ## PO File Formatting (GNU Gettext Standard)
+
+      # Line length threshold below which strings are rendered on a single line
+      # @return [Integer] 80
+      PO_SHORT_LINE_LENGTH = 80
+
+      # Character chunk size for long strings (split across multiple lines)
+      # @return [Integer] 70
+      PO_LINE_LENGTH = 70
+
+      # ## Debug Logger Text Length Thresholds
+
+      # Minimum text length to trigger logging (shorter strings are not logged)
+      # @return [Integer] 50
+      LOG_THRESHOLD_SHORT = 50
+
+      # Truncate length for key similarity logging (text[0..20])
+      # @return [Integer] 20
+      LOG_TRUNCATE_SHORT = 20
+
+      # Truncate length for text node previews (text[0..40])
+      # @return [Integer] 40
+      LOG_TRUNCATE_MEDIUM = 40
+
+      # Truncate length for translation log messages (text[0..60])
+      # @return [Integer] 60
+      LOG_TRUNCATE_LONG = 60
+
+      # ## Debug Logger Context Extraction
+
+      # Number of characters to show before/after difference in debug output
+      # @return [Integer] 10
+      BACKTRACE_CONTEXT_LENGTH = 10
+
+      # ## Default Configuration Values
+
+      # Default directory for storing PO translation files
+      # @return [String] "_locales"
+      DEFAULT_LOCALES_DIR = "_locales"
+
+      # Default fallback mode when translation is not found
+      # @return [String] "english"
+      DEFAULT_FALLBACK_MODE = FALLBACK_MODE_ENGLISH
+
+      # Default HTML attributes to extract from elements (can be overridden per-page)
+      # @return [Array<String>] ["title", "alt", "aria-label", "placeholder", "aria-description"]
+      DEFAULT_TRANSLATABLE_ATTRIBUTES = %w(title alt aria-label placeholder aria-description).freeze
+
+      # ## LibreTranslate Integration Defaults
+
+      # Default timeout (in seconds) for LibreTranslate API requests
+      # @return [Integer] 300 seconds (5 minutes)
+      DEFAULT_LIBRETRANSLATE_TIMEOUT = 300
+
+      # Default batch size for LibreTranslate API calls
+      # Controls how many strings are sent in a single request
+      # @return [Integer] 50
+      DEFAULT_LIBRETRANSLATE_BATCH_SIZE = 50
+
+      # Default number of retry attempts for failed LibreTranslate requests
+      # @return [Integer] 3
+      DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS = 3
+
+      # Default delay (in seconds) between LibreTranslate retry attempts
+      # Exponential backoff is applied: actual_delay = base_delay * (2 ^ (attempt - 1))
+      # @return [Integer] 2 seconds
+      DEFAULT_LIBRETRANSLATE_RETRY_DELAY = 2
+
+      # Default behavior when LibreTranslate API returns an error
+      # If true, translation stops immediately. If false, continues with remaining entries.
+      # @return [Boolean] true
+      DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR = true
+
+      # Default interval for logging LibreTranslate translation progress
+      # Progress is logged every N entries. Set to 0 to disable.
+      # @return [Integer] 10 (log every 10 entries)
+      DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL = 10
+
+      # Default source locale for LibreTranslate API
+      # The language of the original content being translated
+      # @return [String] "en" (English)
+      DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE = "en"
+
+      # Default text format for LibreTranslate API requests
+      # Either 'text' (plain text) or 'html' (preserves markup)
+      # @return [String] "html"
+      DEFAULT_LIBRETRANSLATE_FORMAT = "html"
+    end
+  end
+end

data/lib/jekyll-l10n/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Custom exception hierarchy for jekyll-l10n
+    #
+    # Provides specific error types for different aspects of the localization process.
+    # All custom exceptions inherit from BaseError, which inherits from StandardError,
+    # allowing for both specific exception handling and generic error catching.
+    #
+    # @example
+    #   begin
+    #     # Some localization operation
+    #   rescue Jekyll::L10n::Errors::ExtractionError => e
+    #     Jekyll.logger.error "Extraction failed: #{e.message}"
+    #   end
+    module Errors
+      # Base error class for all jekyll-l10n exceptions
+      #
+      # All custom exceptions in the plugin inherit from this class, allowing
+      # for both specific exception handling and generic catching of all
+      # jekyll-l10n errors.
+      class BaseError < StandardError; end
+
+      # Error raised during HTML string extraction
+      #
+      # Indicates a failure during the extraction of translatable strings
+      # from HTML documents. Common causes include invalid HTML structure,
+      # file I/O errors, or parse failures.
+      class ExtractionError < BaseError; end
+
+      # Error raised during translation application
+      #
+      # Indicates a failure while applying translations from PO files to HTML.
+      # Common causes include missing translation files, malformed HTML,
+      # or translation resolver failures.
+      class TranslationError < BaseError; end
+
+      # Error raised during PO file operations
+      #
+      # Indicates a failure while reading, writing, or parsing PO files.
+      # Common causes include invalid PO file format, file permissions issues,
+      # or corrupted translation data.
+      class PoFileError < BaseError; end
+
+      # Error raised due to invalid configuration
+      #
+      # Indicates that configuration values are invalid, missing required settings,
+      # or have conflicting values. Raised during configuration validation.
+      class ConfigurationError < BaseError; end
+
+      # Error raised during LibreTranslate API operations
+      #
+      # Indicates a failure while communicating with the LibreTranslate API.
+      # Common causes include network errors, API unavailability, invalid API keys,
+      # or rate limiting.
+      class LibreTranslateError < BaseError; end
+    end
+  end
+end

data/lib/jekyll-l10n/extraction/compendium_merger.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "../po_file/manager"
+require_relative "../utils/page_locales_config"
+require_relative "../utils/site_config_accessor"
+
+module Jekyll
+  module L10n
+    # Merges page-specific PO files into compendium files.
+    #
+    # CompendiumMerger combines all page-specific translations for a locale into
+    # a single compendium file. It preserves existing compendium translations,
+    # merges in new strings from pages, updates references, and cleans up the
+    # locale directory after merging.
+    #
+    # Key responsibilities:
+    # * Load existing compendium translations
+    # * Merge page-specific translations into compendium
+    # * Preserve existing translations while adding new ones
+    # * Update file location references for new entries
+    # * Save merged compendium back to file
+    # * Clean up locale-specific directory structure
+    #
+    # @example
+    #   merger = CompendiumMerger.new(site)
+    #   merger.merge_compendia(po_manager, config)
+    #   # Page-specific PO files merged into _locales/{locale}.po, directories cleaned up
+    #
+    # @see Jekyll::L10n::CompendiumTranslator for automatic translation workflow
+    class CompendiumMerger
+      # Initialize a new CompendiumMerger.
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      def initialize(site)
+        @site = site
+        with_locales_data = SiteConfigAccessor.extract_locales_data(@site)
+        @site_config = PageLocalesConfig.new({ "with_locales_data" => with_locales_data })
+      end
+
+      # Merge page-specific PO files into compendia for all locales.
+      #
+      # For each configured locale, loads existing compendium, merges all
+      # page-specific translations, and saves the combined result. Cleans up
+      # locale subdirectories after merging.
+      #
+      # @param po_manager [PoFileManager] Manager for PO file operations
+      # @param config [PageLocalesConfig] Localization configuration with locales list
+      # @return [void]
+      def merge_compendia(po_manager, config)
+        config.locales.each do |locale|
+          process_locale(locale, po_manager, config)
+        end
+      end
+
+      private
+
+      # Process a single locale: merge existing compendium with new page translations
+      def process_locale(locale, po_manager, config)
+        compendium_path = File.join(@site.source, config.locales_dir, "#{locale}.po")
+        existing_compendium = load_existing_compendium(compendium_path)
+        merged = po_manager.merge_po_files(locale)
+
+        combined = build_combined_hash(existing_compendium)
+        merge_into_combined(combined, merged)
+        combined_entries = format_compendium_entries(combined)
+
+        po_manager.save_compendium(locale, combined_entries)
+        cleanup_locale_directory(locale, config)
+      end
+
+      # Load existing compendium translations or return empty hash if not found
+      def load_existing_compendium(compendium_path)
+        if File.exist?(compendium_path)
+          PoFileReader.parse_with_references(compendium_path)
+        else
+          {}
+        end
+      end
+
+      # Initialize combined hash from existing compendium entries
+      def build_combined_hash(existing_compendium)
+        combined = {}
+        existing_compendium.each do |msgid, data|
+          combined[msgid] = normalize_compendium_entry(data)
+        end
+        combined
+      end
+
+      # Normalize entry format to ensure consistent hash structure with :msgstr and :reference keys
+      def normalize_compendium_entry(data)
+        if data.is_a?(Hash)
+          { :msgstr => data[:msgstr], :reference => data[:reference] }
+        else
+          { :msgstr => data, :reference => nil }
+        end
+      end
+
+      # Merge newly found translations into combined hash, preserving existing translations
+      def merge_into_combined(combined, merged)
+        merged.each do |msgid, entry|
+          if combined[msgid]
+            update_entry_reference(combined[msgid], entry)
+          else
+            combined[msgid] = create_new_entry(entry)
+          end
+        end
+      end
+
+      # Update reference for existing entry if new reference is available
+      def update_entry_reference(combined_entry, entry)
+        if combined_entry[:reference].nil? && entry.is_a?(Hash) && entry[:reference]
+          combined_entry[:reference] = entry[:reference]
+        end
+      end
+
+      # Create new entry for untranslated string with optional reference
+      def create_new_entry(entry)
+        { :msgstr => "", :reference => entry.is_a?(Hash) ? entry[:reference] : nil }
+      end
+
+      # Convert combined hash to array of entries suitable for PO file writing
+      def format_compendium_entries(combined)
+        combined.map do |msgid, data|
+          entry = { :msgid => msgid, :msgstr => data[:msgstr] }
+          entry[:reference] = data[:reference] if data[:reference]
+          entry
+        end
+      end
+
+      # IMPORTANT: Remove locale-specific directory after compendium merge
+      # This cleans up page-specific PO files that have been merged into the compendium
+      def cleanup_locale_directory(locale, config)
+        locale_dir = File.join(@site.source, config.locales_dir, locale)
+        FileUtils.rm_rf(locale_dir) if File.directory?(locale_dir)
+      end
+
+      private :process_locale, :load_existing_compendium, :build_combined_hash,
+              :normalize_compendium_entry, :merge_into_combined, :update_entry_reference,
+              :create_new_entry, :format_compendium_entries, :cleanup_locale_directory
+    end
+  end
+end

data/lib/jekyll-l10n/extraction/compendium_translator.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../po_file/manager"
+require_relative "../utils/page_locales_config"
+require_relative "../utils/po_entry_converter"
+require_relative "../utils/site_config_accessor"
+require_relative "../utils/logger_formatter"
+require_relative "../translation/libre_translator"
+
+module Jekyll
+  module L10n
+    # Automatically translates compendium PO files using LibreTranslate.
+    #
+    # CompendiumTranslator loads compendium files for each locale, identifies
+    # untranslated entries, sends them to the LibreTranslate API for translation,
+    # and saves the translated results back to the PO files. It provides detailed
+    # logging of the translation process.
+    #
+    # Key responsibilities:
+    # * Load compendium PO files for each locale
+    # * Convert between PO entry formats for API compatibility
+    # * Trigger LibreTranslate translation for untranslated entries
+    # * Save translated entries back to compendium files
+    # * Log translation statistics and progress
+    #
+    # @example
+    #   translator = CompendiumTranslator.new(site)
+    #   translator.translate_compendia(config) if config.libretranslate_enabled?
+    #   # Compendia updated with LibreTranslate translations
+    class CompendiumTranslator
+      # Initialize a new CompendiumTranslator.
+      #
+      # @param site [Jekyll::Site] Jekyll site object
+      def initialize(site)
+        @site = site
+        with_locales_data = SiteConfigAccessor.extract_locales_data(@site)
+        @site_config = PageLocalesConfig.new({ "with_locales_data" => with_locales_data })
+      end
+
+      # Translate compendia for all configured locales.
+      #
+      # Checks if LibreTranslate is enabled. If so, for each configured locale,
+      # loads the compendium PO file, identifies untranslated entries, sends them
+      # to LibreTranslate API, and saves the updated file.
+      #
+      # @param config [PageLocalesConfig] Localization configuration
+      # @return [void]
+      def translate_compendia(config)
+        po_manager = PoFileManager.new(@site, config.locales_dir)
+        translate_compendia_for_locale(po_manager, config)
+      end
+
+      private
+
+      def translate_compendia_for_locale(po_manager, config)
+        log_compendia_enabled_check(config.libretranslate_enabled?)
+        return unless config.libretranslate_enabled?
+
+        log_translation_start(config)
+        translator = LibreTranslator.new(config)
+
+        config.locales.each do |locale|
+          process_single_locale(locale, config, translator, po_manager)
+        end
+
+        log_translation_complete(config)
+      end
+
+      def process_single_locale(locale, config, translator, po_manager)
+        compendium_path = File.join(@site.source, config.locales_dir, "#{locale}.po")
+        LoggerFormatter.debug_if_enabled("CompendiumTranslator",
+                                         "Processing compendium file: #{compendium_path}")
+        return unless File.exist?(compendium_path)
+
+        entries = PoFileReader.parse_with_references(compendium_path)
+        po_entries = PoEntryConverter.hash_to_po_entry_array(entries)
+
+        log_compendium_stats(locale, po_entries, compendium_path)
+        translator.translate_compendium(po_entries, locale)
+
+        log_translation_complete_for_locale(locale)
+        translated_hashes = PoEntryConverter.po_entries_to_array_of_hashes(po_entries)
+
+        po_manager.save_compendium(locale, translated_hashes)
+        log_compendium_saved(locale, compendium_path)
+      end
+
+      def log_compendia_enabled_check(enabled)
+        msg = "translate_compendia_for_locale called, libretranslate_enabled:"
+        LoggerFormatter.debug_if_enabled("CompendiumTranslator", "#{msg} #{enabled}")
+      end
+
+      def log_compendium_stats(locale, po_entries, compendium_path)
+        msg = "Locale #{locale}: Loaded #{po_entries.length} entries from compendium"
+        LoggerFormatter.debug_if_enabled("CompendiumTranslator", "#{msg} #{compendium_path}")
+
+        empty_count = count_empty_entries(po_entries)
+        LoggerFormatter.debug_if_enabled(
+          "CompendiumTranslator",
+          "Locale #{locale}: #{empty_count} empty msgstr entries to translate"
+        )
+      end
+
+      def log_translation_complete_for_locale(locale)
+        msg = "Locale #{locale}: Translation complete, saving compendium"
+        LoggerFormatter.debug_if_enabled("CompendiumTranslator", msg)
+      end
+
+      def log_compendium_saved(locale, compendium_path)
+        msg = "Locale #{locale}: Saved compendium to"
+        LoggerFormatter.debug_if_enabled("CompendiumTranslator", "#{msg} #{compendium_path}")
+      end
+
+      def count_empty_entries(po_entries)
+        po_entries.count do |e|
+          (e.msgstr.nil? || e.msgstr.empty?) && !e.msgid.strip.empty?
+        end
+      end
+
+      def log_translation_start(config)
+        locales = config.locales.join(", ")
+        Jekyll.logger.info "Localization",
+                           "Starting LibreTranslate translation for locales: #{locales}"
+      end
+
+      def log_translation_complete(config)
+        locales = config.locales.join(", ")
+        Jekyll.logger.info "Localization",
+                           "LibreTranslate translation complete for locales: #{locales}"
+      end
+
+      private :translate_compendia_for_locale, :process_single_locale,
+              :log_compendia_enabled_check, :log_compendium_stats,
+              :log_translation_complete_for_locale, :log_compendium_saved,
+              :count_empty_entries, :log_translation_start, :log_translation_complete
+    end
+  end
+end