Class: Jekyll::L10n::PageLocalesConfig

Inherits:
Object
  • Object
show all
Defined in:
lib/jekyll-l10n/utils/page_locales_config.rb

Overview

Configuration Parser - Extracts and validates localization settings from page front matter

PageLocalesConfig parses the with_locales_data front matter field in Jekyll pages and provides a type-safe interface to localization configuration. It validates all values against expected types and ranges, raising clear errors for invalid configurations.

Configuration can be specified in page front matter at multiple levels:

  • Translation settings (fallback modes, LibreTranslate API)
  • Extraction settings (which attributes to extract, directories)
  • Logging settings (debug output, statistics)

Key responsibilities:

  • Parse with_locales_data from page front matter
  • Validate locale codes against ISO 639-1 (with optional ISO 3166-1 alpha-2 country) format
  • Validate LibreTranslate configuration when enabled
  • Provide getter methods with sensible defaults
  • Raise detailed validation errors for invalid configurations

Examples:

Minimal configuration

---
with_locales: true
with_locales_data:
  locales: [es, fr, pt]
---

Full configuration with LibreTranslate

---
with_locales: true
with_locales_data:
  locales: [es, fr, pt_BR]
  extract_on_build: true
  update_compendium: true
  extraction:
    translatable_attributes: [title, alt, aria-label]
  translation:
    fallback: english
    libretranslate_enabled: true
    libretranslate_api_url: "http://localhost:5000/translate"
    libretranslate_timeout: 300
  logging:
    debug: true
---

Constant Summary collapse

LOCALE_PATTERN =

Delegate all constant definitions to Constants module

Constants::LOCALE_PATTERN
DEFAULT_LOCALES_DIR = 
Constants::DEFAULT_LOCALES_DIR
DEFAULT_FALLBACK_MODE = 
Constants::DEFAULT_FALLBACK_MODE
DEFAULT_TRANSLATABLE_ATTRIBUTES = 
Constants::DEFAULT_TRANSLATABLE_ATTRIBUTES
DEFAULT_LIBRETRANSLATE_TIMEOUT = 
Constants::DEFAULT_LIBRETRANSLATE_TIMEOUT
DEFAULT_LIBRETRANSLATE_BATCH_SIZE = 
Constants::DEFAULT_LIBRETRANSLATE_BATCH_SIZE
DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS = 
Constants::DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS
DEFAULT_LIBRETRANSLATE_RETRY_DELAY = 
Constants::DEFAULT_LIBRETRANSLATE_RETRY_DELAY
DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR = 
Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR
DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL = 
Constants::DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL
DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE = 
Constants::DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE
DEFAULT_LIBRETRANSLATE_FORMAT = 
Constants::DEFAULT_LIBRETRANSLATE_FORMAT

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(page_data) ⇒ PageLocalesConfig

Initialize configuration from page front matter

Parses the with_locales_data section from page front matter and validates all configuration values. Raises detailed errors if any values are invalid.

Parameters:

  • page_data (Hash) —

    The Jekyll page data/front matter object

Raises:

  • (Jekyll::Errors::InvalidConfigurationError) —

    If locale codes are invalid

  • (Jekyll::Errors::InvalidConfigurationError) —

    If LibreTranslate config is invalid



78
79
80
81
82
83
84
85
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 78

def initialize(page_data)
  @config = page_data['with_locales_data'] || {}
  @data = page_data
  @page_path = page_data['path'] || 'unknown'

  validate_locales!
  validate_libretranslate!
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



68
69
70
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 68

def data
  @data
end

Instance Method Details

#debug_logging? ⇒ Boolean

Check if debug-level logging is enabled

Returns:

  • (Boolean) —

    true if debug logging is configured, false otherwise



133
134
135
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 133

def debug_logging?
  @config.dig('logging', 'debug') == true
end

#enabled? ⇒ Boolean

Check if localization is enabled for this page

A page is considered to have localization enabled if at least one locale is configured.

Returns:

  • (Boolean) —

    true if locales list is not empty, false otherwise



174
175
176
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 174

def enabled?
  !locales.empty?
end

#extract_on_build? ⇒ Boolean

Check if string extraction should run during Jekyll build

Returns:

  • (Boolean) —

    true if extraction is enabled (default), false if explicitly disabled



111
112
113
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 111

def extract_on_build?
  @config['extract_on_build'] != false
end

#fallback_mode ⇒ String

Get the fallback mode for missing translations

Determines how to handle translations that are not found in PO files. Valid modes: "english" (use original text), "marker" (wrap with markers), "empty" (leave blank).

Returns:

  • (String) —

    The fallback mode ("english", "marker", or "empty")



154
155
156
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 154

def fallback_mode
  @config.dig('translation', 'fallback') || DEFAULT_FALLBACK_MODE
end

#libretranslate_api_key ⇒ String?

Get the LibreTranslate API key (if required)

Some LibreTranslate instances require authentication via API key.

Returns:

  • (String, nil) —

    The API key, or nil if not configured



228
229
230
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 228

def libretranslate_api_key
  libretranslate_config['libretranslate_api_key']
end

#libretranslate_api_url ⇒ String

Get the LibreTranslate API endpoint URL

Example: "https://api.libretranslate.de" or "http://localhost:5000"

Returns:



219
220
221
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 219

def libretranslate_api_url
  libretranslate_setting('libretranslate_api_url', Constants::DEFAULT_LIBRETRANSLATE_API_URL)
end

#libretranslate_batch_size ⇒ Integer

Get the batch size for LibreTranslate translations

Controls how many strings are sent to LibreTranslate in a single API request. Larger batches are more efficient but may hit size limits.

Returns:

  • (Integer) —

    Batch size (default: 50)



245
246
247
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 245

def libretranslate_batch_size
  libretranslate_setting('libretranslate_batch_size', DEFAULT_LIBRETRANSLATE_BATCH_SIZE)
end

#libretranslate_enabled? ⇒ Boolean

Check if LibreTranslate automatic translation is enabled

Returns true if libretranslate_enabled is explicitly set to true, or if a libretranslate_api_url is configured (backward compatibility).

Returns:

  • (Boolean) —

    true if LibreTranslate is enabled and configured



184
185
186
187
188
189
190
191
192
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 184

def libretranslate_enabled?
  # Priority 1: Explicit flag (when set)
  if libretranslate_config.key?('libretranslate_enabled')
    return libretranslate_config['libretranslate_enabled'] == true
  end

  # Priority 2: Backward compatibility - URL presence (when flag not set)
  !libretranslate_api_url.nil? && !libretranslate_api_url.empty?
end

#libretranslate_format ⇒ String

Get the text format for LibreTranslate translation

Determines how text is passed to LibreTranslate API. Valid values: 'text' or 'html'. HTML format preserves markup and performs better with structured content.

Returns:

  • (String) —

    Either 'text' or 'html' (default: 'html')



210
211
212
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 210

def libretranslate_format
  libretranslate_setting('libretranslate_format', DEFAULT_LIBRETRANSLATE_FORMAT)
end

#libretranslate_progress_interval ⇒ Integer

Get the interval for logging LibreTranslate translation progress

Translation progress is logged every N entries translated. Set to 0 to disable progress logging.

Returns:

  • (Integer) —

    Number of entries between progress logs (default: 10)



281
282
283
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 281

def libretranslate_progress_interval
  libretranslate_setting('libretranslate_progress_interval', DEFAULT_LIBRETRANSLATE_PROGRESS_INTERVAL)
end

#libretranslate_retry_attempts ⇒ Integer

Get the number of retry attempts for failed LibreTranslate requests

Returns:

  • (Integer) —

    Number of retry attempts (default: 3)



252
253
254
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 252

def libretranslate_retry_attempts
  libretranslate_setting('libretranslate_retry_attempts', DEFAULT_LIBRETRANSLATE_RETRY_ATTEMPTS)
end

#libretranslate_retry_delay ⇒ Integer

Get the delay (in seconds) between LibreTranslate retry attempts

Returns:

  • (Integer) —

    Delay in seconds (default: 2)



259
260
261
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 259

def libretranslate_retry_delay
  libretranslate_setting('libretranslate_retry_delay', DEFAULT_LIBRETRANSLATE_RETRY_DELAY)
end

#libretranslate_source_locale ⇒ String

Get the source locale for LibreTranslate translation

The source locale is the language of the original content being translated. Defaults to "en" (English) if not specified.

Returns:

  • (String) —

    BCP 47 locale code (e.g., 'en', 'fr')



200
201
202
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 200

def libretranslate_source_locale
  libretranslate_setting('libretranslate_source_locale', DEFAULT_LIBRETRANSLATE_SOURCE_LOCALE)
end

#libretranslate_stop_on_error? ⇒ Boolean

Check if translation should stop on LibreTranslate errors

If true, any API error will halt the translation process. If false, errors are logged but translation continues with other entries.

Returns:

  • (Boolean) —

    true if errors should stop translation, false if translation continues (default: false)



270
271
272
273
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 270

def libretranslate_stop_on_error?
  val = libretranslate_config['libretranslate_stop_on_error']
  val.nil? ? Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR : val != false
end

#libretranslate_timeout ⇒ Integer

Get the timeout (in seconds) for LibreTranslate API requests

Returns:

  • (Integer) —

    Timeout in seconds (default: 300)



235
236
237
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 235

def libretranslate_timeout
  libretranslate_setting('libretranslate_timeout', DEFAULT_LIBRETRANSLATE_TIMEOUT)
end

#locales ⇒ Array<String>

Get the list of locales configured for this page

Returns the locales specified in with_locales_data.locales, or an empty array if not configured. All returned locales are guaranteed to match ISO 639-1 format, optionally suffixed with an ISO 3166-1 alpha-2 country code.

Returns:

  • (Array<String>) —

    BCP 47 locale codes (e.g., ['es', 'fr', 'pt_BR'])



94
95
96
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 94

def locales
  @config['locales'] || []
end

#locales_dir ⇒ String

Get the directory where PO files are stored for this page

Returns the directory specified in with_locales_data.locales_dir, or the default "_locales" if not configured.

Returns:

  • (String) —

    The directory path relative to site root



104
105
106
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 104

def locales_dir
  @config['locales_dir'] || DEFAULT_LOCALES_DIR
end

#show_statistics? ⇒ Boolean

Check if extraction statistics should be shown in logs

Returns:

  • (Boolean) —

    true if statistics are enabled (default), false if explicitly disabled



126
127
128
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 126

def show_statistics?
  @config.dig('logging', 'show_statistics') != false
end

#trace_logging? ⇒ Boolean

Check if trace-level logging is enabled

Trace logging includes detailed per-entry logs for extraction and translation operations. This is automatically enabled if debug_logging? is true.

Returns:

  • (Boolean) —

    true if trace logging is enabled or debug logging is enabled



143
144
145
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 143

def trace_logging?
  @config.dig('logging', 'trace') == true || debug_logging?
end

#translatable_attributes ⇒ Array<String>

Get the list of HTML attributes to extract for translation

Returns attributes specified in with_locales_data.extraction.translatable_attributes, or the default list if not configured (title, alt, aria-label, placeholder, aria-description).

Returns:

  • (Array<String>) —

    List of attribute names to extract



165
166
167
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 165

def translatable_attributes
  @config.dig('extraction', 'translatable_attributes') || DEFAULT_TRANSLATABLE_ATTRIBUTES
end

#update_compendium? ⇒ Boolean

Check if compendium files should be updated during extraction

Returns:

  • (Boolean) —

    true if compendium updates are enabled (default), false if explicitly disabled



119
120
121
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 119

def update_compendium?
  @config['update_compendium'] != false
end