jekyll-l10n 2.0.0 → 3.0.0

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

@@ -1,103 +1,105 @@
 # frozen_string_literal: true
 
+require_relative '../configuration'
+require_relative 'page_locales_config'
+
 module Jekyll
   module L10n
-    # Reads `with_locales_data` settings from the site and its pages.
+    # Reads the plugin's settings from the site and its pages.
     #
     # The plugin reads settings in two ways, and this class holds both:
     # - Per-page settings: {.page_locales_data} merges the page's front matter
     #   over the `_config.yml` defaults that match the page. Read page settings
     #   through it (or {.effective_page_data}), never from `page.data` directly.
-    # - Site-wide settings: {.extract_locales_data} returns the first `defaults`
-    #   entry that has `with_locales_data`, whatever its scope.
+    # - Site-wide settings: {.site_settings} returns the top-level `jekyll_l10n`
+    #   settings, and {.site_config} wraps them, with the site's locales, in a
+    #   PageLocalesConfig for the build-wide steps.
     #
     # Methods that take a site also accept a Hash, so specs can pass a plain
     # hash instead of a Jekyll::Site.
     #
     # @example
     #   SiteConfigAccessor.page_locales_data(page)['locales'] # => ["es", "fr"]
-    #   SiteConfigAccessor.extract_locales_data(site)['update_compendium']
+    #   SiteConfigAccessor.site_config(site).update_compendium? # => true
     class SiteConfigAccessor
-      # Site-wide `with_locales_data`: the value from the first `defaults` entry
-      # that has one, whatever pages it matches. Used for settings that apply
-      # to the whole build, such as `update_compendium` and
-      # `logging.show_statistics`.
+      # The checked top-level `jekyll_l10n` settings, which apply to the whole
+      # build. See Configuration.site.
+      #
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [Hash] The settings (frozen), or {} when `jekyll_l10n` is not set
+      def self.site_settings(site)
+        Configuration.site(site_config_hash(site) || {})
+      end
+
+      # Settings for the steps that run once per build (extraction summary,
+      # compendium merge, machine translation): the {.site_settings} merged
+      # over the first `defaults` entry's `with_locales_data`, which gives the
+      # site's `locales` and `locales_dir`.
+      #
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @param all_locales [Boolean] Use {.all_configured_locales} as the
+      #   locale list, so locales that only some pages add are covered too
+      # @return [PageLocalesConfig]
+      def self.site_config(site, all_locales: false)
+        data = extract_locales_data(site)
+        data = data.merge('locales' => all_configured_locales(site)) if all_locales
+        PageLocalesConfig.new(Configuration::PAGE_DATA_KEY => Jekyll::Utils.deep_merge_hashes(data, site_settings(site)))
+      end
+
+      # The first `defaults` entry's `with_locales_data`, whatever pages it
+      # matches, checked by Schema. Its `locales` and `locales_dir` are the
+      # site's own; prefer {.site_config}, which adds the `jekyll_l10n`
+      # settings.
       #
       # @param site [Jekyll::Site, Hash] The site, or a hash in specs
       # @return [Hash] The settings, or {} when no entry has them
       def self.extract_locales_data(site)
-        config = site.is_a?(Hash) ? site['config'] : site.config
+        config = site_config_hash(site)
+        Configuration.check_defaults(config)
         defaults = config['defaults'] || []
-        entry = defaults.find { |d| d.dig('values', 'with_locales_data') }
-        entry&.dig('values', 'with_locales_data') || {}
+        entry = defaults.find { |d| d.is_a?(Hash) && d.dig('values', Configuration::PAGE_DATA_KEY) }
+        Configuration::Schema.normalize(entry&.dig('values', Configuration::PAGE_DATA_KEY), source: nil)
       end
 
       # The page's `with_locales_data`, merged over the `_config.yml` defaults
-      # that match the page.
-      #
-      # We need this because Jekyll's `page.data` fills in defaults one
-      # top-level key at a time: as soon as a page sets any `with_locales_data`
-      # key, `page.data` loses all the site defaults for it. This method gives
-      # the same result Liquid templates see. Nested hashes merge key by key;
-      # lists such as `locales` are replaced, not combined.
+      # that match the page. See Configuration.page.
       #
       # @param page [Jekyll::Page] The page. Any other object gets only its own value.
-      # @return [Hash] The page's settings
+      # @return [Hash] The page's settings (frozen)
       def self.page_locales_data(page)
-        own = page.data['with_locales_data']
-        own = {} unless own.is_a?(Hash)
-        deep_merge(defaults_locales_data_for(page), own)
+        Configuration.page(page)
       end
 
-      # Like Jekyll::Utils.deep_merge_hashes: nested hashes merge, and any other
-      # value from `override` (lists included) wins. Returns a new hash.
-      def self.deep_merge(base, override)
-        base.merge(override) do |_key, base_value, override_value|
-          if base_value.is_a?(Hash) && override_value.is_a?(Hash)
-            deep_merge(base_value, override_value)
-          else
-            override_value
-          end
-        end
-      end
-      private_class_method :deep_merge
-
       # The page's data with `with_locales_data` replaced by
       # {.page_locales_data}. Pass this to PageLocalesConfig.new.
       #
       # @param page [Jekyll::Page] The page
       # @return [Hash] Page data with merged `with_locales_data`
       def self.effective_page_data(page)
-        page.data.merge('with_locales_data' => page_locales_data(page))
+        page.data.merge(Configuration::PAGE_DATA_KEY => page_locales_data(page))
       end
 
-      # `with_locales_data` from the defaults that match the page, or {} when
-      # the page has no site to look them up in (as in some specs).
-      def self.defaults_locales_data_for(page)
-        return {} unless page.is_a?(Jekyll::Page)
-
-        site = page.site
-        return {} unless site.respond_to?(:frontmatter_defaults)
-
-        value = site.frontmatter_defaults.all(page.relative_path, :pages)['with_locales_data']
-        value.is_a?(Hash) ? value : {}
-      end
-      private_class_method :defaults_locales_data_for
-
-      # Every locale the site uses: the site-wide list plus any list a page sets
-      # in its front matter. Extraction uses it to skip localized output
-      # folders, and the compendium steps use it to cover locales that only one
-      # page adds.
+      # Every locale the site uses: the site-wide list plus each page's own
+      # list, read through {.page_locales_data} so a page also brings the
+      # locales of the defaults entries that match it. Extraction uses it to
+      # skip localized output folders, and the compendium steps use it to
+      # cover locales that only one page adds.
       #
       # @param site [Jekyll::Site, Hash] The site, or a hash in specs
       # @return [Array<String>] Unique locale codes
       def self.all_configured_locales(site)
         site_wide_locales = extract_locales_data(site)['locales'] || []
         pages = site.is_a?(Hash) ? site['pages'] : site.pages
-        page_locales = pages.flat_map { |p| p.data.dig('with_locales_data', 'locales') || [] }
+        page_locales = pages.flat_map { |p| page_locales_data(p)['locales'] || [] }
         (site_wide_locales + page_locales).uniq
       end
 
+      # @param site [Jekyll::Site, Hash] The site, or a hash in specs
+      # @return [Hash, nil] The site configuration
+      def self.site_config_hash(site)
+        site.is_a?(Hash) ? site['config'] : site.config
+      end
+
       # @param site [Jekyll::Site, Hash] The site, or a hash in specs
       # @return [String] The site source directory
       def self.source(site)

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

@@ -27,17 +27,46 @@ module Jekyll
       # If not found, checks if the text is part of a block element with
       # a block-level translation and returns that.
       #
+      # Text inside an inline element of a content element that has a msgid is
+      # translated only through that msgid (see {.covered_by_block?}), so a
+      # translation of the same text elsewhere does not translate it alone.
+      #
       # @param node [Nokogiri::XML::Node] Text node being translated
       # @param text [String] Normalized text content
       # @param translations [Hash] Translation hash mapping text to translations
+      # @param block_texts [Hash, nil] (keyword) Identity-keyed cache for block text
+      #   extraction results ({}.compare_by_identity), or nil to bypass caching.
+      #   Pass the per-document cache from HtmlTranslator to avoid redundant
+      #   BlockTextExtractor calls across multiple text nodes in the same ancestor.
       # @return [String, nil] Translated text if found, nil otherwise
-      def self.resolve(node, text, translations)
+      def self.resolve(node, text, translations, block_texts: nil)
         return nil unless node && text && translations
 
-        direct_translation = translations[text]
-        return direct_translation if direct_translation
+        unless covered_by_block?(node, text, block_texts)
+          direct_translation = translations[text]
+          return direct_translation if direct_translation
+        end
+
+        try_block_level_translation(node, text, translations, block_texts: block_texts)
+      end
+
+      # Check whether a text node sits inside an inline element of a content
+      # element that has a msgid of its own. Extraction gives such text no msgid
+      # (HtmlStringExtractor), so it is translated only as part of the block.
+      # Text directly inside the content element keeps its direct lookup, for
+      # msgstrs that hold the element's markup (a heading with an anchor).
+      #
+      # @param node [Nokogiri::XML::Node] Text node being translated
+      # @param text [String] Normalized text of the node
+      # @param block_texts [Hash, nil] Identity-keyed cache, see {.block_text_for}
+      # @return [Boolean]
+      def self.covered_by_block?(node, text, block_texts = nil)
+        ancestor = find_content_element_ancestor(node)
+        return false if ancestor.nil? || node.parent == ancestor
+        return false if contains_protected_elements?(ancestor)
 
-        try_block_level_translation(node, text, translations)
+        block_text = block_text_for(ancestor, block_texts)
+        !block_text.nil? && block_text != text
       end
 
       # Attempt block-level translation for text nodes that are part of larger blocks.
@@ -52,24 +81,45 @@ module Jekyll
       # @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
+      # @param block_texts [Hash, nil] (keyword) Identity-keyed cache for block text
+      #   results, or nil to bypass caching. See {.block_text_for}.
       # @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)
+      def self.try_block_level_translation(node, text, translations, block_texts: nil)
         ancestor = find_content_element_ancestor(node)
         return nil unless ancestor
 
         return nil if contains_protected_elements?(ancestor)
 
-        block_text = BlockTextExtractor.extract(ancestor)
+        block_text = block_text_for(ancestor, block_texts)
         return nil unless block_text && block_text != text
 
         translations[block_text]
       end
 
+      # Return the extracted block text for a content element, using the supplied
+      # cache when available.
+      #
+      # When a cache is given (an identity-keyed hash), the result is stored on
+      # the first call and returned directly on subsequent calls for the same
+      # ancestor object — nil results are cached too, so a non-extractable
+      # ancestor is not retried. When no cache is given, delegates directly to
+      # BlockTextExtractor every time.
+      #
+      # @param ancestor [Nokogiri::XML::Element] Content element to extract from
+      # @param cache [Hash, nil] Identity-keyed cache ({}.compare_by_identity),
+      #   or nil to bypass caching
+      # @return [String, nil] Extracted block text, or nil if not extractable
+      def self.block_text_for(ancestor, cache = nil)
+        return BlockTextExtractor.extract(ancestor) if cache.nil?
+
+        cache.fetch(ancestor) { cache[ancestor] = BlockTextExtractor.extract(ancestor) }
+      end
+
       def self.content_element?(node)
         return false unless node
         return false unless node.element?

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

@@ -2,21 +2,19 @@
 
 module Jekyll
   module L10n
-    # Builds file paths from URLs and vice versa.
+    # Builds paths from Jekyll URLs.
     #
-    # 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.
+    # UrlPathBuilder converts Jekyll URLs to the page paths used for translation
+    # files, handling root paths specially and normalizing separators.
     #
     # 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'
+    #   po_page_path = UrlPathBuilder.url_to_po_page_path('/docs/guide/')
+    #   # Returns 'docs/guide/index.html'
     module UrlPathBuilder
       module_function
 
@@ -28,26 +26,6 @@ module Jekyll
         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.
-      # For URLs with file extensions (assets), preserves the extension.
-      # For directory-style URLs, uses index.html.
-      #
-      # @param url [String] Jekyll URL (e.g., '/docs/page.html' or '/assets/style.css')
-      # @return [String] File path (e.g., 'docs/page.html/index.html' or 'assets/style.css')
-      def url_to_file_path(url)
-        normalized = normalize_url(url)
-
-        # Preserve file extensions for assets (css, js, etc.)
-        # Only add /index.html for directory-style URLs
-        if /\.[a-zA-Z0-9]+$/.match?(normalized)
-          normalized
-        else
-          "#{normalized}/index.html"
-        end
-      end
-
       # Convert a URL to a PO page path for translation files.
       #
       # Handles root path specially (converts to 'index'). Used when saving

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

@@ -11,7 +11,7 @@ module Jekyll
     #
     # UrlTransformer modifies href attributes in links to prefix them with
     # the target locale in BCP 47 hyphenated form (e.g., /docs/page.html becomes
-    # /es-ES/docs/page.html for a canonical "es_ES" locale).
+    # /es-es/docs/page.html for a canonical "es_ES" locale).
     # It preserves external links, anchors, mailto, tel links, and links
     # already containing locale prefixes. Skips English locale (default language).
     #
@@ -26,7 +26,7 @@ module Jekyll
     # @example
     #   html = '<a href="/docs/page.html">Link</a>'
     #   transformed = UrlTransformer.transform(html, 'es_ES', '/baseurl')
-    #   # Returns '<a href="/baseurl/es-ES/docs/page.html">Link</a>'
+    #   # Returns '<a href="/baseurl/es-es/docs/page.html">Link</a>'
     class UrlTransformer
       class << self
         # Transform all relative URLs in HTML to include locale prefix.
@@ -46,17 +46,11 @@ module Jekyll
 
           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)
+          doc = HtmlParser.parse_document(html)
 
           transform_document(doc, locale, baseurl)
 
-          result = doc.to_html
-
-          HtmlParser.remove_meta_charset(result)
+          doc.to_html
         end
 
         # Transform URLs in a parsed HTML document.
@@ -64,7 +58,7 @@ module Jekyll
         # 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 doc [Nokogiri::HTML5::Document] Parsed HTML document
         # @param locale [String] Target locale code (canonical or BCP 47 form)
         # @param baseurl [String] Base URL for site
         # @return [void]

data/lib/jekyll-l10n/version.rb

@@ -6,6 +6,6 @@ module Jekyll
     # Regenerated alongside the gemspec on every `make jekyll-l10n.gemspec`
     # run (locally or in CI), so it always matches spec.version in the built
     # gem. Any hand edit is overwritten on the next run.
-    VERSION = '2.0.0'
+    VERSION = '3.0.0'
   end
 end

data/lib/jekyll-l10n.rb

@@ -41,12 +41,13 @@ require 'gettext/po'
 #
 # ## 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.
+# Per-page 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). Settings that apply to the
+# whole build, such as `incremental`, `update_compendium` and the
+# LibreTranslate settings, live under the top-level `jekyll_l10n` key
+# (SiteConfigAccessor.site_settings). Configuration::Schema gives each
+# setting's scope; a setting in the wrong place is ignored with a warning.
 #
 # ```yaml
 # defaults:
@@ -59,6 +60,7 @@ require 'gettext/po'
 #
 # jekyll_l10n:
 #   incremental: true
+#   update_compendium: true
 # ```
 #
 # ## Files
@@ -79,6 +81,7 @@ require 'gettext/po'
 require_relative 'jekyll-l10n/version'
 require_relative 'jekyll-l10n/instrumentation'
 require_relative 'jekyll-l10n/constants'
+require_relative 'jekyll-l10n/configuration'
 require_relative 'jekyll-l10n/errors'
 require_relative 'jekyll-l10n/po_file/reader'
 require_relative 'jekyll-l10n/po_file/fuzzy_matcher'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-l10n
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Alain Reguera Delgado
@@ -75,7 +75,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.13'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -85,7 +85,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '1.13'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -253,11 +253,14 @@ files:
 - LICENSE
 - README.md
 - lib/jekyll-l10n.rb
+- lib/jekyll-l10n/configuration.rb
+- lib/jekyll-l10n/configuration/schema.rb
 - lib/jekyll-l10n/constants.rb
 - lib/jekyll-l10n/errors.rb
 - lib/jekyll-l10n/extraction/compendium_merger.rb
 - lib/jekyll-l10n/extraction/compendium_translator.rb
 - lib/jekyll-l10n/extraction/config_loader.rb
+- lib/jekyll-l10n/extraction/coverage_report.rb
 - lib/jekyll-l10n/extraction/dom_attribute_extractor.rb
 - lib/jekyll-l10n/extraction/dom_text_extractor.rb
 - lib/jekyll-l10n/extraction/extractor.rb
@@ -271,6 +274,7 @@ files:
 - lib/jekyll-l10n/jekyll/post_write_processor.rb
 - lib/jekyll-l10n/jekyll/regeneration_checker.rb
 - lib/jekyll-l10n/jekyll/url_filter.rb
+- lib/jekyll-l10n/po_file/entry_parser.rb
 - lib/jekyll-l10n/po_file/fuzzy_matcher.rb
 - lib/jekyll-l10n/po_file/loader.rb
 - lib/jekyll-l10n/po_file/manager.rb
@@ -280,9 +284,13 @@ files:
 - lib/jekyll-l10n/po_file/writer.rb
 - lib/jekyll-l10n/translation/block_text_extractor.rb
 - lib/jekyll-l10n/translation/html_translator.rb
+- lib/jekyll-l10n/translation/libre_translate_languages.rb
 - lib/jekyll-l10n/translation/libre_translator.rb
 - lib/jekyll-l10n/translation/page_translation_loader.rb
+- lib/jekyll-l10n/translation/request_slots.rb
+- lib/jekyll-l10n/translation/translation_progress.rb
 - lib/jekyll-l10n/translation/translator.rb
+- lib/jekyll-l10n/utils/baseurl_normalizer.rb
 - lib/jekyll-l10n/utils/debug_logger.rb
 - lib/jekyll-l10n/utils/error_handler.rb
 - lib/jekyll-l10n/utils/external_link_icon_preserver.rb
@@ -293,6 +301,7 @@ files:
 - lib/jekyll-l10n/utils/locale_name_resolver.rb
 - lib/jekyll-l10n/utils/locale_url_formatter.rb
 - lib/jekyll-l10n/utils/logger_formatter.rb
+- lib/jekyll-l10n/utils/msgstr_validator.rb
 - lib/jekyll-l10n/utils/page_locales_config.rb
 - lib/jekyll-l10n/utils/po_entry_converter.rb
 - lib/jekyll-l10n/utils/site_config_accessor.rb