Class: Jekyll::L10n::PoFileManager

Inherits:
Object
  • Object
show all
Defined in:
lib/jekyll-l10n/po_file/manager.rb

Overview

Manages reading, writing, merging, and caching of GNU Gettext PO files.

PoFileManager provides a centralized API for PO file operations and maintains an in-memory cache to avoid redundant disk I/O across multiple extraction and translation operations. It coordinates between loading, writing, and merging operations while managing file paths and locale directories.

Key responsibilities:

  • Load and cache PO files (page-specific and compendium)

  • Save new or updated PO files with optional merging of existing translations

  • Merge PO files for locales (combining page-specific with compendium)

  • Manage global in-memory cache keyed by locale and page path

  • Clear cache when files are written or rebuilt

  • Construct proper file paths for locale/page combinations

Examples:

manager = PoFileManager.new(site, '_locales')
translations = manager.load_po_file('es', 'docs/index.html')
manager.save_po_file('es', entries, page_path: 'docs/index.html')

Constant Summary collapse

DEFAULT_LOCALES_DIR = 
'_locales'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(site, locales_dir = DEFAULT_LOCALES_DIR) ⇒ PoFileManager

Initialize a new PoFileManager.

Parameters:

  • site (Jekyll::Site) —

    Jekyll site object

  • locales_dir (String) (defaults to: DEFAULT_LOCALES_DIR) —

    Directory containing PO files (defaults to DEFAULT_LOCALES_DIR = “_locales”)



67
68
69
70
71
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 67

def initialize(site, locales_dir = DEFAULT_LOCALES_DIR)
  @site = site
  @source = SiteConfigAccessor.source(@site)
  @locales_dir = locales_dir
end

Instance Attribute Details

#locales_dir ⇒ Object (readonly)

Returns the value of attribute locales_dir.



34
35
36
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 34

def locales_dir
  @locales_dir
end

#site ⇒ Object (readonly)

Returns the value of attribute site.



34
35
36
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 34

def site
  @site
end

Class Method Details

.cache ⇒ Hash

Access the global PO file cache.

Returns:

  • (Hash) —

    Cache mapping “locale:page_path” keys to translation hashes



40
41
42
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 40

def cache
  @cache ||= {}
end

.cache_size ⇒ Integer

Get the current size of the global cache.

Returns:

  • (Integer) —

    Number of entries currently cached



57
58
59
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 57

def cache_size
  cache.size
end

.clear_cache ⇒ void

This method returns an undefined value.

Clear the global PO file cache.

Clears all cached PO file translations. Should be called when the site is rebuilt or PO files are modified to ensure fresh data is loaded.



50
51
52
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 50

def clear_cache
  @cache = {}
end

Instance Method Details

#load_compendium(locale) ⇒ Hash

Load the compendium (shared translations) for a locale.

Compendiums are locale-level translation files shared across all pages. This delegates to load_po_file with page_path set to nil.

Parameters:

  • locale (String) —

    Target locale code (e.g., ‘es’, ‘fr’)

Returns:

  • (Hash) —

    Translation hash or empty hash if file doesn’t exist



80
81
82
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 80

def load_compendium(locale)
  load_po_file(locale, nil)
end

#load_po_file(locale, page_path = nil) ⇒ Hash<String, String>

Load a PO file for a specific locale and optional page.

First checks in-memory cache to avoid redundant disk I/O. If not cached, loads from disk using PoFileLoader and caches the result. Returns empty hash if file doesn’t exist.

Parameters:

  • locale (String) —

    Target locale code (e.g., ‘es’, ‘fr’)

  • page_path (String, nil) (defaults to: nil) —

    Optional page path for page-specific translations. Defaults to nil, which loads the compendium (shared translations) file instead.

Returns:

  • (Hash<String, String>) —

    Translation hash mapping msgid to msgstr, or empty hash if file doesn’t exist. Simple format where keys are original strings and values are translations.



96
97
98
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 96

def load_po_file(locale, page_path = nil)
  PoFileLoader.load(@source, @locales_dir, locale, page_path)
end

#merge_po_files(locale) ⇒ Boolean

Merge PO files for a locale.

Combines page-specific and compendium translations for a locale, handling merging logic to preserve translations while adding new strings.

Parameters:

  • locale (String) —

    Target locale code

Returns:

  • (Boolean) —

    True if merge successful



139
140
141
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 139

def merge_po_files(locale)
  PoFileMerger.merge_for_locale(@source, @locales_dir, locale)
end

#save_compendium(locale, entries) ⇒ Boolean

Save the compendium (shared translations) for a locale.

Writes entries to the locale’s compendium file, overwriting without merging (compendia are typically generated fresh each time).

Parameters:

  • locale (String) —

    Target locale code

  • entries (Array<Hash>) —

    Array of extraction entries

Returns:

  • (Boolean) —

    True if write successful, false on error



128
129
130
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 128

def save_compendium(locale, entries)
  save_po_file(locale, entries, page_path: nil, skip_merge: true)
end

#save_po_file(locale, entries, page_path: nil, skip_merge: false) ⇒ Boolean

Save a PO file for a locale and optional page.

Writes entries to PO file, optionally merging with existing translations to preserve any manual edits. Creates directory structure as needed. Invalidates relevant cache entries after write.

Parameters:

  • locale (String) —

    Target locale code (e.g., ‘es’, ‘fr’)

  • entries (Array<Hash>) —

    Array of extraction entries with :msgid, :msgstr, :reference

  • page_path (String, nil) (defaults to: nil) —

    Optional page path for page-specific file

  • skip_merge (Boolean) (defaults to: false) —

    If true, overwrites file without merging existing translations

Returns:

  • (Boolean) —

    True if write successful, false on error



111
112
113
114
115
116
117
118
 
# File 'lib/jekyll-l10n/po_file/manager.rb', line 111

def save_po_file(locale, entries, page_path: nil, skip_merge: false)
  po_path = PoPathBuilder.build(@source, @locales_dir, locale, page_path)
  prepare_and_write_po_file(po_path, entries, locale, page_path: page_path,
                                                      skip_merge: skip_merge)
rescue StandardError => e
  Jekyll.logger.error 'Localization', "Error saving PO file #{po_path}: #{e.message}"
  false
end