jekyll-l10n 1.7.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1eaa747e07f028e44e032b6e40fb1026b03a2ea8e04b4933e5f78043a55d465
-  data.tar.gz: d8230c41f61bf17c197098295a6fee79b2984640d28d03bed13cff5396e46ff4
+  metadata.gz: d6469f52a4c1ac2cc94d6e6c546a1091b91d1d6b30331110931496ad96422404
+  data.tar.gz: f9726ad1727591b5f2aebce4435f8dd99ad9e9269d6fd669a0a402c156e4219e
 SHA512:
-  metadata.gz: 92427c75eca422dd7ea4bc6771fd5ee371d01fb3655c132c0dde3df1da0c5c3f966fa94ddc65d6c5f15cc9d47b92bfc2dd006783d8f6ccb78f5c986cea9498e9
-  data.tar.gz: 8c66cbea172736c7c39b64cc1a1699c2f1fb862a10b5523cb26176860ec59072a4c1ed3b3888fd32ebdb780b7f06d6a3c6ce57436b8f08eb4ae5307087f9a822
+  metadata.gz: 62f17f5dcf12c508b5f2998d93d30b443aa3107a289cda6472b6df9a3249016516c4b5f6c309e5e258e20469d7bc6de957aefdbdd49575e80db0ddb325481578
+  data.tar.gz: dc55f0983289039c97b0c968d295685616ab467aeb766ea41729777629ac70c3c09a9585cd14dd3208dce59d64fd700a031107b71ba91a293f0fd102709a0920

data/README.md

@@ -6,11 +6,55 @@ translatable strings from your site's HTML, organizes them into PO files for
 professional translation, and automatically applies translations to generate
 fully localized pages with locale-prefixed URLs.
 
+## Installation
+
+Add the gem to your site's `Gemfile` and the plugin to `_config.yml`:
+
+```bash
+bundle add jekyll-l10n --group jekyll_plugins
+```
+
+```yaml
+plugins:
+  - jekyll-l10n
+```
+
+Then follow [Getting started](https://centos.gitlab.io/artwork/centos-web/jekyll-l10n/getting-started/)
+to enable localization.
+
 ## Documentation
 
 For complete documentation, configuration options, and examples, visit the
 [documentation site](https://centos.gitlab.io/artwork/centos-web/jekyll-l10n/).
 
+## Contributing
+
+1. Install the development dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+2. Run the tests and lint, the same checks CI runs before a release:
+
+   ```bash
+   make             # runs both of the commands below
+   bundle exec rspec
+   bundle exec rubocop
+   ```
+
+   `bundle exec rspec` also writes a coverage report to `coverage/`.
+
+3. Write commit messages in the
+   [Conventional Commits](https://www.conventionalcommits.org/) format, for
+   example `fix(translation): keep inline links in block translations`.
+   Releases and the changelog are generated from them: `feat` and `fix`
+   commits, and commits marked as breaking changes, publish a new version.
+
+4. If an AI tool helped write a commit, add an `Assisted-by:` trailer, as the
+   [Fedora AI contribution policy](https://docs.fedoraproject.org/en-US/council/policy/ai-contribution-policy/)
+   requires.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.

data/lib/jekyll-l10n/configuration/schema.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'did_you_mean'
+require_relative '../constants'
+
+module Jekyll
+  module L10n
+    module Configuration
+      # The type, scope and default of every setting, and how a value of the
+      # wrong type is converted or dropped, with a warning.
+      #
+      # {.normalize} cleans a settings hash: it drops unknown keys, converts
+      # near-misses such as "false", and drops values it cannot read so the
+      # default applies. It never adds defaults, so a setting the user did not
+      # set stays unset; PageLocalesConfig applies the defaults when asked.
+      # That matters for LibreTranslate, which turns on only when the user set
+      # `libretranslate_api_url` themselves.
+      #
+      # A bad locale code is dropped here, with a warning, so the page is built
+      # for its other locales. The LibreTranslate URL, format and source locale
+      # are checked by PageLocalesConfig instead, which turns machine
+      # translation off, with a warning, when one is invalid.
+      module Schema
+        # Every setting, by dotted path: its type, its scope, and its default
+        # (nil: none, or worked out by PageLocalesConfig). A :page setting is
+        # set under `with_locales_data` (page front matter or `_config.yml`
+        # defaults); a :site setting applies to the whole build and is set
+        # under the top-level `jekyll_l10n` key.
+        #
+        # @return [Hash{String => Hash}]
+        SETTINGS = {
+          'incremental' => { type: :boolean, scope: :site, default: Constants::DEFAULT_INCREMENTAL },
+          'locales' => { type: :locale_list, scope: :page, default: [] },
+          'locales_dir' => { type: :string, scope: :page, default: Constants::DEFAULT_LOCALES_DIR },
+          'extract_on_build' => { type: :boolean, scope: :page, default: Constants::DEFAULT_EXTRACT_ON_BUILD },
+          'update_compendium' => { type: :boolean, scope: :site, default: Constants::DEFAULT_UPDATE_COMPENDIUM },
+          'logging.show_statistics' => { type: :boolean, scope: :site, default: Constants::DEFAULT_SHOW_STATISTICS },
+          'logging.debug' => { type: :boolean, scope: :page, default: Constants::DEFAULT_DEBUG_LOGGING },
+          'logging.trace' => { type: :boolean, scope: :site, default: Constants::DEFAULT_TRACE_LOGGING },
+          'translation.fallback' => { type: :fallback, scope: :page, default: Constants::DEFAULT_FALLBACK_MODE },
+          'translation.min_coverage' => { type: :percentage, scope: :site, default: nil },
+          'translation.libretranslate_enabled' => { type: :boolean, scope: :site, default: nil },
+          'translation.libretranslate_api_url' => {
+            type: :string, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_API_URL
+          },
+          'translation.libretranslate_api_key' => { type: :string, scope: :site, default: nil, secret: true },
+          'translation.libretranslate_source_locale' => {
+            type: :string, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE
+          },
+          'translation.libretranslate_format' => {
+            type: :string, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_FORMAT
+          },
+          'translation.libretranslate_timeout' => {
+            type: :positive_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_TIMEOUT
+          },
+          'translation.libretranslate_batch_size' => {
+            type: :positive_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_BATCH_SIZE
+          },
+          'translation.libretranslate_concurrency' => {
+            type: :positive_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_CONCURRENCY
+          },
+          'translation.libretranslate_retry_attempts' => {
+            type: :non_negative_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS
+          },
+          'translation.libretranslate_retry_delay' => {
+            type: :non_negative_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_RETRY_DELAY
+          },
+          'translation.libretranslate_stop_on_error' => {
+            type: :boolean, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR
+          },
+          'translation.libretranslate_mark_fuzzy' => {
+            type: :boolean, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_MARK_FUZZY
+          },
+          'translation.libretranslate_progress_interval' => {
+            type: :non_negative_integer, scope: :site, default: Constants::DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL
+          },
+          'extraction.translatable_attributes' => {
+            type: :string_list, scope: :page, default: Constants::DEFAULT_TRANSLATABLE_ATTRIBUTES
+          },
+          'extraction.exclude_selectors' => {
+            type: :string_list, scope: :page, default: Constants::DEFAULT_EXCLUDE_SELECTORS
+          }
+        }.freeze
+
+        # Whether value is a locale code such as "es" or "pt_BR".
+        LOCALE_CODE = ->(value) { value.is_a?(String) && Constants::LOCALE_PATTERN.match?(value) }
+
+        # Converts "true"/"false" in any case, surrounding spaces ignored.
+        BOOLEAN_WORD = lambda { |value|
+          word = value.strip.downcase if value.is_a?(String)
+          [word == 'true'] if %w[true false].include?(word)
+        }
+
+        # Converts a string of digits to an Integer.
+        INTEGER_STRING = ->(value) { [value.strip.to_i] if value.is_a?(String) && value.strip.match?(/\A\d+\z/) }
+
+        # Per type: what the warning says to expect, which values pass as is,
+        # and how a near-miss converts (returns [converted], or nil when the
+        # value can't be converted and the default applies instead).
+        #
+        # @return [Hash{Symbol => Hash}]
+        COERCERS = {
+          boolean: {
+            expected: 'true or false',
+            accept: ->(value) { [true, false].include?(value) },
+            convert: BOOLEAN_WORD
+          },
+          string: {
+            expected: 'a string',
+            # Empty strings pass: an empty libretranslate_api_url makes
+            # PageLocalesConfig turn machine translation off, with a warning.
+            accept: ->(value) { value.is_a?(String) },
+            convert: ->(_value) {}
+          },
+          positive_integer: {
+            expected: 'a positive integer',
+            accept: ->(value) { value.is_a?(Integer) && value.positive? },
+            convert: ->(value) { INTEGER_STRING.call(value)&.then { |(int)| [int] if int.positive? } }
+          },
+          non_negative_integer: {
+            expected: 'an integer of 0 or more',
+            accept: ->(value) { value.is_a?(Integer) && !value.negative? },
+            convert: INTEGER_STRING
+          },
+          percentage: {
+            expected: 'an integer from 0 to 100',
+            accept: ->(value) { value.is_a?(Integer) && value.between?(0, 100) },
+            convert: ->(value) { INTEGER_STRING.call(value)&.then { |(int)| [int] if int <= 100 } }
+          },
+          string_list: {
+            expected: 'a list of strings',
+            accept: ->(value) { value.is_a?(Array) && value.all?(String) },
+            convert: ->(value) { [[value]] if value.is_a?(String) && !value.strip.empty? }
+          },
+          # A single code reads as a one-code list. Codes that don't match
+          # LOCALE_PATTERN are dropped, so the page skips only those locales.
+          locale_list: {
+            expected: 'a list of locale codes such as es or pt_BR',
+            accept: ->(value) { value.is_a?(Array) && value.all?(&LOCALE_CODE) },
+            convert: lambda { |value|
+              codes = value.is_a?(String) ? [value] : value
+              [codes.select(&LOCALE_CODE)] if codes.is_a?(Array)
+            }
+          },
+          fallback: {
+            expected: "one of #{Constants::FALLBACK_MODES.join(', ')}",
+            accept: ->(value) { Constants::FALLBACK_MODES.include?(value) },
+            convert: lambda { |value|
+              mode = value.to_s.strip.downcase if value.is_a?(String) || value.is_a?(Symbol)
+              [mode] if Constants::FALLBACK_MODES.include?(mode)
+            }
+          }
+        }.freeze
+
+        # The scope of the settings under each root key. PageLocalesConfig
+        # reads :all, the per-page and site-wide settings merged.
+        #
+        # @return [Hash{String => Symbol}]
+        ROOT_SCOPES = { PAGE_DATA_KEY => :page, CONFIG_KEY => :site }.freeze
+
+        # Every section name and setting name per scope (:page, :site, :all),
+        # by parent path ('' for the top level). Used to find unknown keys and
+        # suggest known ones.
+        #
+        # @return [Hash{Symbol => Hash{String => Array<String>}}]
+        KNOWN_KEYS = %i[page site all].to_h do |scope|
+          paths = SETTINGS.select { |_path, spec| scope == :all || spec[:scope] == scope }.keys
+          known = paths.each_with_object(Hash.new { |h, k| h[k] = [] }) do |path, keys|
+            *sections, name = path.split('.')
+            keys[sections.join('.')] |= [name]
+            keys[''] |= [sections.first] unless sections.empty?
+          end
+          [scope, known.to_h.freeze]
+        end.freeze
+
+        # Returns a cleaned copy of a settings hash: unknown keys and settings
+        # of the other scope dropped, near-misses converted, unreadable values
+        # dropped. Warns once per problem (see Configuration.warn_once).
+        #
+        # @param settings [Object] The settings, normally a Hash
+        # @param source [String, nil] Where the settings come from, for
+        #   warnings; nil cleans without warning (for values already checked)
+        # @param root [String] The key the settings sit under, for warnings
+        # @param scope [Symbol] The settings to keep: :page, :site or :all.
+        #   Defaults to the scope of root (see ROOT_SCOPES).
+        # @return [Hash]
+        def self.normalize(settings, source:, root: PAGE_DATA_KEY, scope: ROOT_SCOPES.fetch(root, :all))
+          return {} if settings.nil?
+          return normalize_section(settings, '', source, root, scope) if settings.is_a?(Hash)
+
+          warn_invalid(source, root, settings, 'a mapping of settings', 'ignoring it')
+          {}
+        end
+
+        # Reads a true/false flag such as `with_locales`. nil is false; "true"
+        # and "false" convert with a warning; anything else is false, with a
+        # warning.
+        #
+        # @param value [Object] The flag's value
+        # @param key [String] The flag's name, for warnings
+        # @param source [String] Where the value comes from, for warnings
+        # @return [Boolean]
+        def self.boolean_flag(value, key, source)
+          return value if [true, false].include?(value)
+          return false if value.nil?
+
+          converted = BOOLEAN_WORD.call(value)
+          if converted
+            warn_invalid(source, key, value, 'true or false', "reading it as #{converted.first}")
+            return converted.first
+          end
+
+          warn_invalid(source, key, value, 'true or false', 'using false')
+          false
+        end
+
+        # Logs "<source>: <key path> should be <expected>, got <value>;
+        # <outcome>." once per build. Secret values are never shown.
+        #
+        # @return [void]
+        def self.warn_invalid(source, key_path, value, expected, outcome)
+          return if source.nil?
+
+          shown = SETTINGS.dig(key_path.split('.', 2).last, :secret) ? '[hidden]' : value.inspect
+          Configuration.warn_once("#{source}: #{key_path} should be #{expected}, got #{shown}; #{outcome}.")
+        end
+
+        def self.normalize_section(settings, parent, source, root, scope)
+          settings.each_with_object({}) do |(key, value), clean|
+            next if value.nil?
+
+            path = parent.empty? ? key.to_s : "#{parent}.#{key}"
+            cleaned = normalize_value(path, value, source, root, scope)
+            clean[key] = cleaned unless cleaned.nil?
+          end
+        end
+
+        # The cleaned value of the setting or section at path, or nil to leave
+        # it out.
+        def self.normalize_value(path, value, source, root, scope)
+          spec = SETTINGS[path]
+          # A copy, so freezing the result never freezes the site config.
+          return coerce(value, path, source, root)&.dup if spec && [:all, spec[:scope]].include?(scope)
+          return warn_wrong_scope(source, root, path, spec[:scope]) if spec
+          # A section of the other scope is still walked, so each of its
+          # settings gets a warning that names where it belongs.
+          return normalize_subsection(value, path, source, root, scope) if KNOWN_KEYS[:all][''].include?(path)
+
+          parent, _, key = path.rpartition('.')
+          warn_unknown(source, root, parent, key, scope)
+          nil
+        end
+
+        def self.normalize_subsection(value, path, source, root, scope)
+          return normalize_section(value, path, source, root, scope) if value.is_a?(Hash)
+
+          warn_invalid(source, "#{root}.#{path}", value, 'a mapping of settings', 'ignoring it')
+          nil
+        end
+
+        # Returns value if its type accepts it; otherwise its conversion, with
+        # a warning; otherwise nil (the default applies), with a warning.
+        def self.coerce(value, path, source, root)
+          spec = SETTINGS.fetch(path)
+          coercer = COERCERS.fetch(spec[:type])
+          return value if coercer[:accept].call(value)
+
+          key_path = "#{root}.#{path}"
+          converted = coercer[:convert].call(value)
+          if converted
+            outcome = spec[:secret] ? 'reading it as text' : "reading it as #{converted.first.inspect}"
+            warn_invalid(source, key_path, value, coercer[:expected], outcome)
+            return converted.first
+          end
+
+          warn_invalid(source, key_path, value, coercer[:expected], 'using the default')
+          nil
+        end
+
+        # Warns that a setting sits under the wrong root key, and returns nil
+        # so the setting is left out.
+        def self.warn_wrong_scope(source, root, path, setting_scope)
+          return if source.nil?
+
+          hint = if setting_scope == :site
+                   "it applies to the whole build; set `#{CONFIG_KEY}.#{path}` in _config.yml"
+                 else
+                   "it applies per page; set `#{PAGE_DATA_KEY}.#{path}` in _config.yml defaults or page front matter"
+                 end
+          Configuration.warn_once("#{source}: #{root}.#{path} is ignored here, #{hint}.")
+          nil
+        end
+
+        def self.warn_unknown(source, root, parent, key, scope)
+          return if source.nil?
+
+          key_path = [root, parent, key].reject { |part| part.to_s.empty? }.join('.')
+          dictionary = KNOWN_KEYS[scope].fetch(parent, [])
+          suggestion = DidYouMean::SpellChecker.new(dictionary: dictionary).correct(key.to_s).first
+          hint = suggestion ? "; did you mean `#{suggestion}`?" : '.'
+          Configuration.warn_once("#{source}: #{key_path} is not a known setting and is ignored#{hint}")
+        end
+        private_class_method :normalize_section, :normalize_value, :normalize_subsection, :coerce,
+                             :warn_wrong_scope, :warn_unknown
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/configuration.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+require 'set'
+
+module Jekyll
+  module L10n
+    # Names the configuration keys the plugin reads, checks their values, and
+    # resolves each page's settings once per build.
+    #
+    # Localization is configured per page: a page opts in with `with_locales`
+    # and reads its settings from `with_locales_data`, its front matter merged
+    # over the matching `_config.yml` defaults. Settings that apply to the
+    # whole build live under the top-level `jekyll_l10n` key of `_config.yml`
+    # (see {.site}); Schema gives each setting's scope.
+    #
+    # Values are checked where they are written, so a warning names its
+    # source: each `defaults` entry once per build, and each page's own front
+    # matter once. Schema describes every setting.
+    module Configuration
+      # The top-level _config.yml key for build-wide settings.
+      # @return [String]
+      CONFIG_KEY = 'jekyll_l10n'
+
+      # The page key that opts a page into localization.
+      # @return [String]
+      PAGE_FLAG_KEY = 'with_locales'
+
+      # The page key that holds a page's localization settings.
+      # @return [String]
+      PAGE_DATA_KEY = 'with_locales_data'
+
+      # Source name used in warnings about the merged `_config.yml` defaults.
+      # @return [String]
+      DEFAULTS_SOURCE = '_config.yml defaults'
+
+      # Source name used in warnings about the `jekyll_l10n` settings.
+      # @return [String]
+      SITE_SOURCE = '_config.yml'
+
+      # Whether the page opted into localization. "true" and "false" are read
+      # as booleans, with a warning; any other non-boolean value is false.
+      #
+      # @param page [Jekyll::Page] The page
+      # @return [Boolean]
+      def self.localizable?(page)
+        own = page.data.respond_to?(:key?) && page.data.key?(PAGE_FLAG_KEY)
+        Schema.boolean_flag(page.data[PAGE_FLAG_KEY], PAGE_FLAG_KEY, own ? source_of(page) : DEFAULTS_SOURCE)
+      end
+
+      # The page's checked `with_locales_data`: its own front matter merged
+      # over the `_config.yml` defaults that match the page. Nested hashes
+      # merge; lists such as `locales` are replaced. Frozen, and worked out
+      # once per page per build.
+      #
+      # Jekyll's `page.data` fills in defaults one top-level key at a time, so
+      # as soon as a page sets any `with_locales_data` key, `page.data` loses
+      # every site default for it. Read page settings through this method.
+      #
+      # @param page [Jekyll::Page] The page. Any other object gets only its own value.
+      # @return [Hash] The page's settings
+      def self.page(page)
+        pages = cache[:pages] ||= {}.compare_by_identity
+        pages[page] ||= deep_freeze(resolve_page(page))
+      end
+
+      # The checked top-level `jekyll_l10n` settings, which apply to the whole
+      # build. A per-page setting found there is dropped with a warning.
+      # Frozen, and worked out once per build.
+      #
+      # @param site_config [Hash] The site configuration (site.config)
+      # @return [Hash] The settings, or {} when `jekyll_l10n` is not set
+      def self.site(site_config)
+        sites = cache[:sites] ||= {}.compare_by_identity
+        sites[site_config] ||= deep_freeze(
+          Schema.normalize(site_config[CONFIG_KEY], source: SITE_SOURCE, root: CONFIG_KEY)
+        )
+      end
+
+      # Checks every `defaults` entry's `with_locales_data` and `with_locales`
+      # once per build, so each warning names the entry (`defaults[2]`).
+      #
+      # @param site_config [Hash] The site configuration (site.config)
+      # @return [void]
+      def self.check_defaults(site_config)
+        checked = cache[:checked_defaults] ||= Set.new.compare_by_identity
+        return unless checked.add?(site_config)
+
+        Array(site_config['defaults']).each_with_index do |entry, index|
+          values = entry['values'] if entry.is_a?(Hash)
+          check_defaults_values(values, "_config.yml defaults[#{index}]") if values.is_a?(Hash)
+        end
+      end
+
+      # Logs a warning unless the same message was logged earlier in this
+      # build, so a bad value in a `defaults` entry warns once, not per page.
+      #
+      # @param message [String] The warning
+      # @return [void]
+      def self.warn_once(message)
+        warned = cache[:warned] ||= Set.new
+        Jekyll.logger.warn(Constants::LOG_PREFIX, message) if warned.add?(message)
+      end
+
+      # Drops every cached result and logged warning. Registered on
+      # :site, :after_reset below, so each build (including each
+      # `jekyll serve --watch` rebuild) starts from the config as it is then.
+      #
+      # @return [void]
+      def self.reset!
+        @cache = nil
+      end
+
+      # Holds results strongly: a weak map would let GC drop them mid-build
+      # and repeat every warning. reset! clears it at the start of each build.
+      def self.cache
+        @cache ||= {}
+      end
+
+      def self.check_defaults_values(values, source)
+        Schema.normalize(values[PAGE_DATA_KEY], source: source) if values.key?(PAGE_DATA_KEY)
+        Schema.boolean_flag(values[PAGE_FLAG_KEY], PAGE_FLAG_KEY, source) if values.key?(PAGE_FLAG_KEY)
+      end
+
+      def self.resolve_page(page)
+        own = page.data[PAGE_DATA_KEY] if page.data.respond_to?(:key?) && page.data.key?(PAGE_DATA_KEY)
+        own_settings = Schema.normalize(own, source: source_of(page))
+        Jekyll::Utils.deep_merge_hashes(defaults_for(page), own_settings)
+      end
+
+      # The page's merged `with_locales_data` defaults, cleaned without
+      # warnings (check_defaults has warned about each entry already), or {}
+      # when the page has no site to look them up in (as in some specs).
+      def self.defaults_for(page)
+        return {} unless page.is_a?(Jekyll::Page)
+
+        site = page.site
+        return {} unless site.respond_to?(:frontmatter_defaults)
+
+        check_defaults(site.config) if site.respond_to?(:config) && site.config.is_a?(Hash)
+        Schema.normalize(site.frontmatter_defaults.all(page.relative_path, :pages)[PAGE_DATA_KEY], source: nil)
+      end
+
+      def self.source_of(page)
+        path = page.relative_path if page.respond_to?(:relative_path)
+        path = page.path if (path.nil? || path.empty?) && page.respond_to?(:path)
+        path.nil? || path.empty? ? 'page front matter' : path
+      end
+
+      def self.deep_freeze(value)
+        case value
+        when Hash then value.each_value { |v| deep_freeze(v) }.freeze
+        when Array then value.each { |v| deep_freeze(v) }.freeze
+        else value
+        end
+      end
+      private_class_method :cache, :check_defaults_values, :resolve_page, :defaults_for, :source_of, :deep_freeze
+    end
+  end
+end
+
+# Schema's constants read the key names, defined above.
+require_relative 'configuration/schema'
+
+Jekyll::Hooks.register(:site, :after_reset) { Jekyll::L10n::Configuration.reset! }

data/lib/jekyll-l10n/constants.rb

@@ -12,6 +12,10 @@ module Jekyll
     #
     # @see PageLocalesConfig for configuration-specific defaults
     module Constants
+      # Prefix for every log line the plugin writes.
+      # @return [String]
+      LOG_PREFIX = 'Localization'
+
       # ## Text Validation Constants
 
       # Minimum length for translatable text strings (shorter strings not extracted)
@@ -100,31 +104,52 @@ module Jekyll
       # @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 for `extract_on_build`: extract strings on every build
+      # @return [Boolean] true
+      DEFAULT_EXTRACT_ON_BUILD = true
+
+      # Default for `update_compendium`: merge page PO files into compendia
+      # @return [Boolean] true
+      DEFAULT_UPDATE_COMPENDIUM = true
+
+      # Default for `logging.show_statistics`: print the extraction summary
+      # @return [Boolean] true
+      DEFAULT_SHOW_STATISTICS = true
+
+      # Default for `logging.debug`: no per-lookup translation log
+      # @return [Boolean] false
+      DEFAULT_DEBUG_LOGGING = false
+
+      # Default for `logging.trace`: no per-entry LibreTranslate log
+      # @return [Boolean] false
+      DEFAULT_TRACE_LOGGING = false
+
+      # Default for `jekyll_l10n.incremental`: rebuild every localized page
+      # @return [Boolean] false
+      DEFAULT_INCREMENTAL = false
+
       # Default fallback mode when translation is not found
       # @return [String] "english"
       DEFAULT_FALLBACK_MODE = FALLBACK_MODE_ENGLISH
 
+      # Every accepted value of `translation.fallback`
+      # @return [Array<String>]
+      FALLBACK_MODES = [FALLBACK_MODE_ENGLISH, FALLBACK_MODE_MARKER, FALLBACK_MODE_EMPTY].freeze
+
       # 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
 
-      # Structural/styling attributes restored from the source DOM at render time.
-      # These are never read from msgstr — always sourced from original HTML.
-      # Prevents MT-corrupted class strings from reaching the rendered page.
+      # Default CSS selectors of elements left out of extraction (can be
+      # overridden per-page with `extraction.exclude_selectors`)
       # @return [Array<String>]
-      STRUCTURAL_PASSTHROUGH_ATTRS = %w[class style id target rel tabindex aria-hidden].freeze
+      DEFAULT_EXCLUDE_SELECTORS = ['script', 'style', 'code.language-plaintext', 'pre code'].freeze
 
       # ## LibreTranslate Integration Defaults
 
@@ -142,6 +167,11 @@ module Jekyll
       # @return [Integer] 50
       DEFAULT_LIBRETRANSLATE_BATCH_SIZE = 50
 
+      # Default number of requests sent to LibreTranslate at once. Matches the
+      # server's default worker count, which translates one request per worker.
+      # @return [Integer] 4
+      DEFAULT_LIBRETRANSLATE_CONCURRENCY = 4
+
       # Default number of retry attempts for failed LibreTranslate requests
       # @return [Integer] 3
       DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS = 3
@@ -156,6 +186,11 @@ module Jekyll
       # @return [Boolean] false
       DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR = false
 
+      # Whether machine translations are written as fuzzy entries, which
+      # pages don't use until a person reviews them and removes the flag.
+      # @return [Boolean]
+      DEFAULT_LIBRETRANSLATE_MARK_FUZZY = false
+
       # 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)

data/lib/jekyll-l10n/errors.rb

@@ -55,6 +55,13 @@ module Jekyll
       # Common causes include network errors, API unavailability, invalid API keys,
       # or rate limiting.
       class LibreTranslateError < BaseError; end
+
+      # Error raised when a locale's translation coverage is below
+      # `translation.min_coverage`
+      #
+      # Fails the build so a CI job notices missing translations instead of
+      # publishing pages that fall back to the original text.
+      class CoverageError < BaseError; end
     end
   end
 end