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



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

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.



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

def locales_dir
  @locales_dir
end

#site ⇒ Object (readonly)

Returns the value of attribute site.



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

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



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

def cache
  @cache ||= {}
end

.cache_size ⇒ Integer

Get the current size of the global cache.

Returns:

  • (Integer) —

    Number of entries currently cached



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

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.



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

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



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

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.



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

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



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

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



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

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



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

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
  ErrorHandler.log_error("saving PO file #{po_path}", e)
  false
end