jekyll-l10n 1.7.0 → 2.0.0

data/lib/jekyll-l10n.rb

@@ -7,167 +7,74 @@ require 'liquid'
 require 'nokogiri'
 require 'gettext/po'
 
-# # 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:
+# # jekyll-l10n: translate a Jekyll site with GNU Gettext PO files
+#
+# For every page with `with_locales: true`, the plugin adds a copy per locale
+# under a locale prefix (`/es/about/`), translates the copy from PO files, and
+# collects the page's English strings into PO files for translators.
+#
+# ## Where things live
+#
+# All classes sit directly in `Jekyll::L10n`. The folders group them by job:
+#
+# - `jekyll/`: hooks into the build. Start with Generator (adds the localized
+#   copies), LocalizedPage, PostWriteProcessor, and UrlFilter (Liquid filters).
+# - `translation/`: turns English HTML into translated HTML. Translator,
+#   PageTranslationLoader, HtmlTranslator.
+# - `extraction/`: collects strings into PO files after the site is written.
+#   Extractor, ExtractionResultSaver, CompendiumMerger, CompendiumTranslator.
+# - `po_file/`: reads, writes, merges, and caches PO files. PoFileManager.
+# - `utils/`: shared helpers. Read settings through SiteConfigAccessor and
+#   PageLocalesConfig.
+#
+# ## What happens during a build
+#
+# 1. Generate: Generator adds a LocalizedPage per page and locale. With
+#    `jekyll_l10n.incremental` on, it skips copies whose inputs did not change.
+# 2. Render: after Jekyll renders a localized page, a hook below runs
+#    Translator on it, using the PO files as they are now.
+# 3. Write: Jekyll writes the site.
+# 4. Post-write: a hook below runs PostWriteProcessor. It extracts strings
+#    from every English page, merges them into the locale compendia, runs
+#    machine translation if enabled. When that wrote PO files, it translates
+#    the localized files again so they include the new translations.
+#
+# ## Settings
+#
+# Localization settings live in `with_locales_data`, in `_config.yml`
+# defaults and page front matter. A page's value is merged over the defaults
+# that match it (SiteConfigAccessor.page_locales_data). A few settings apply
+# to the whole build and come from the first defaults entry instead
+# (SiteConfigAccessor.extract_locales_data). The only build-level setting,
+# `incremental`, lives under the top-level `jekyll_l10n` key.
 #
 # ```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
+# defaults:
+#   - scope:
+#       type: pages
+#     values:
+#       with_locales: true
+#       with_locales_data:
+#         locales: [es, fr]
+#
+# jekyll_l10n:
+#   incremental: true
 # ```
 #
-# Page-level configuration overrides site-level configuration:
+# ## Files
 #
-# ```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...
-# ```
+# - Compendium, one per locale: `_locales/es.po`. Translators work here.
+# - Page PO file: `_locales/es/<page url>/index.html.po`. Extraction writes
+#   it, and the compendium merge deletes it unless `update_compendium` is false.
+# - Output: `_site/es/<page url>/index.html`.
 #
-# ### Use locale-aware URLs in templates
+# ## Liquid example
 #
 # ```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>
+#   <a href="{{ page.url | switch_locale_url: locale }}">{{ locale }}</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/instrumentation'
@@ -218,40 +125,21 @@ 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
+    # The plugin namespace. See the top of this file for an overview.
     include Constants
 
-    # Module-level convenience constants that reference the Constants module
+    # Shortcuts to the most used defaults in Constants.
     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.
+    # Adds the locale prefix to the site's internal links in an HTML string.
     #
-    # @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
+    # @param html [String] HTML to change
+    # @param locale [String] Locale code, e.g. 'es'
+    # @param baseurl [String] The site baseurl
+    # @return [String] HTML with prefixed links
     # @example
     #   html_with_locale_urls = Jekyll::L10n.transform(html, 'es', '/mysite')
     def self.transform(html, locale, baseurl)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-l10n
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Alain Reguera Delgado
@@ -131,6 +131,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement