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/2 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



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

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



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

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



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

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”)



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

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: “api.libretranslate.de” or “localhost:5000”

Returns:



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

def libretranslate_api_url
  libretranslate_config['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_config['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



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

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_config['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)



283
284
285
286
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 283

def libretranslate_progress_interval
  libretranslate_config['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
255
 
# File 'lib/jekyll-l10n/utils/page_locales_config.rb', line 252

def libretranslate_retry_attempts
  libretranslate_config['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)



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

def libretranslate_retry_delay
  libretranslate_config['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’)



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

def libretranslate_source_locale
  libretranslate_config['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)



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

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_config['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/2 format.

Returns:

  • (Array<String>) —

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



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

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



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

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



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

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



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

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



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

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



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

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