Class: Jekyll::L10n::PoFileWriter

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

Overview

Writes extraction entries to GNU Gettext PO files.

PoFileWriter serializes extraction entries into standard PO file format with proper escaping, metadata, and optional merging of existing translations. It handles multi-line strings, special characters, fuzzy flags, and reference comments. When merging is enabled, existing translations are preserved while new strings are added or marked as fuzzy.

Key responsibilities:

  • Create PO file entries from extraction data

  • Merge new entries with existing translations

  • Escape special characters and line breaks

  • Format multi-line and long strings properly

  • Add reference comments (file location references)

  • Add fuzzy flags for merge operations

  • Setup PO file headers with encoding information

  • Write UTF-8 encoded output

Examples:

entries = [{ msgid: "Hello", msgstr: "", reference: "html/body/p[1]" }]
PoFileWriter.write('_locales/es.po', entries, 'es')
# Writes PO file with proper header and formatted entries

Class Method Summary collapse

Class Method Details

.add_flag_comment(entry, lines) ⇒ Object 



185
186
187
188
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 185

def self.add_flag_comment(entry, lines)
  flags = entry.flag.to_s.strip
  lines << "#, #{flags}" unless flags.empty?
end

.add_msgid_msgstr(entry, lines) ⇒ Object 



196
197
198
199
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 196

def self.add_msgid_msgstr(entry, lines)
  lines << escape_po_string('msgid', entry.msgid)
  lines << escape_po_string('msgstr', entry.msgstr.to_s)
end

.add_previous_msgid_comment(entry, lines) ⇒ Object 



176
177
178
179
180
181
182
183
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 176

def self.add_previous_msgid_comment(entry, lines)
  prev = entry.previous.to_s
  return if prev.empty?

  escaped = escape_backslashes(prev)
  _delim, escaped = escape_quotes_and_get_delimiter(escaped)
  lines << "#| msgid \"#{escaped}\""
end

.add_reference_comment(entry, lines) ⇒ Object 



190
191
192
193
194
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 190

def self.add_reference_comment(entry, lines)
  return unless entry.extracted_comment && !entry.extracted_comment.empty?

  lines << "#: #{entry.extracted_comment}"
end

.add_translator_comments(entry, lines) ⇒ Object 



168
169
170
171
172
173
174
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 168

def self.add_translator_comments(entry, lines)
  return unless entry.translator_comment && !entry.translator_comment.empty?

  entry.translator_comment.split("\n").each do |comment_line|
    lines << "#  #{comment_line}" unless comment_line.empty?
  end
end

.build_fuzzy_candidates(existing_po, new_msgids) ⇒ Object 



89
90
91
92
93
94
95
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 89

def self.build_fuzzy_candidates(existing_po, new_msgids)
  existing_po.reject do |old_msgid, entry|
    old_msgid.empty? ||
      new_msgids.include?(old_msgid) ||
      PoFuzzyMatcher.msgstr_from_entry(entry).empty?
  end
end

.create_po_entry(entry, existing_po, fuzzy_candidates = {}) ⇒ Object 



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 97

def self.create_po_entry(entry, existing_po, fuzzy_candidates = {})
  po_entry       = ::GetText::POEntry.new(:normal)
  po_entry.msgid = entry[:msgid]

  existing_entry = existing_po[entry[:msgid]]
  set_po_entry_msgstr(po_entry, existing_entry, entry[:msgstr], fuzzy_candidates)

  # Apply fuzzy metadata carried in the entry itself (set by CompendiumMerger)
  if !po_entry.flag && entry[:fuzzy]
    po_entry.flag     = 'fuzzy'
    po_entry.previous = entry[:previous_msgid] if entry[:previous_msgid]
  end

  po_entry
end

.escape_backslashes(value) ⇒ Object 



228
229
230
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 228

def self.escape_backslashes(value)
  value.gsub('\\') { '\\\\' }
end

.escape_po_string(prefix, value) ⇒ Object 



213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 213

def self.escape_po_string(prefix, value)
  value = value.strip
  escaped = escape_backslashes(value)

  delimiter, escaped = escape_quotes_and_get_delimiter(escaped)

  if escaped.include?("\n")
    format_multiline_string(prefix, delimiter, escaped)
  elsif escaped.length < Jekyll::L10n::Constants::PO_SHORT_LINE_LENGTH
    "#{prefix} #{delimiter}#{escaped}#{delimiter}"
  else
    format_long_string(prefix, delimiter, escaped)
  end
end

.escape_quotes_and_get_delimiter(escaped) ⇒ Object 



232
233
234
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 232

def self.escape_quotes_and_get_delimiter(escaped)
  ['"', escaped.gsub('"', '\\"')]
end

.format_long_string(prefix, delimiter, escaped) ⇒ Object 



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 247

def self.format_long_string(prefix, delimiter, escaped)
  lines = ["#{prefix} #{delimiter}#{delimiter}"]
  i = 0

  while i < escaped.length
    chunk = escaped[i...(i + Jekyll::L10n::Constants::PO_LINE_LENGTH)]

    # Never split an escape sequence: if chunk ends with an odd number of
    # backslashes, the trailing \ is the first byte of \" — pull it back
    # so it stays with its partner " in the next chunk.
    trailing_backslashes = chunk[/\\*\z/].length
    chunk = chunk[0...-1] if trailing_backslashes.odd?

    lines << "#{delimiter}#{chunk}#{delimiter}"
    i += chunk.length
  end

  lines.join("\n")
end

.format_multiline_string(prefix, delimiter, escaped) ⇒ Object 



236
237
238
239
240
241
242
243
244
245
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 236

def self.format_multiline_string(prefix, delimiter, escaped)
  lines = ["#{prefix} #{delimiter}#{delimiter}"]
  escaped.split("\n").each do |line|
    next if line.strip.empty?

    lines << "#{delimiter}#{line}\\n#{delimiter}"
  end
  lines << "#{delimiter}#{delimiter}" if lines.length == 1
  lines.join("\n")
end

.get_entries_list(po_file) ⇒ Object 



201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 201

def self.get_entries_list(po_file)
  begin
    po_file.entries
  rescue StandardError
    # entries method failed - try values as fallback
    po_file.values
  end
rescue StandardError => e
  ErrorHandler.log_warning('retrieving PO entries', e)
  []
end

.header(locale) ⇒ Object 



133
134
135
136
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 133

def self.header(locale)
  header_str = "Language: #{locale}\nMIME-Version: 1.0\nContent-Type: text/plain; "
  "#{header_str}charset=UTF-8\nContent-Transfer-Encoding: 8bit\n"
end

.merge_entries_preserving_translations(po_file, entries, existing_po) ⇒ Object 



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 67

def self.merge_entries_preserving_translations(po_file, entries, existing_po)
  errors           = []
  new_msgids       = entries.to_set { |e| e[:msgid] }
  fuzzy_candidates = build_fuzzy_candidates(existing_po, new_msgids)

  entries.each do |entry|
    po_entry = create_po_entry(entry, existing_po, fuzzy_candidates)
    po_entry.add_comment(entry[:reference]) if entry[:reference]

    po_file[entry[:msgid]] = po_entry
  rescue StandardError => e
    truncate_length = Jekyll::L10n::Constants::LOG_TRUNCATE_LONG
    errors << "Error adding '#{entry[:msgid][0..truncate_length]}': " \
              "#{e.class} - #{e.message}"
  end

  return unless errors.any?

  Jekyll.logger.warn 'Localization',
                     "#{errors.length} errors during merging: #{errors.join(', ')}"
end

.serialize_po_entry(entry, lines) ⇒ Object 



159
160
161
162
163
164
165
166
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 159

def self.serialize_po_entry(entry, lines)
  add_translator_comments(entry, lines)
  add_reference_comment(entry, lines)
  add_flag_comment(entry, lines)
  add_previous_msgid_comment(entry, lines)
  add_msgid_msgstr(entry, lines)
  lines << ''
end

.serialize_po_file(po_file) ⇒ Object 



145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 145

def self.serialize_po_file(po_file)
  lines = []
  entries_list = get_entries_list(po_file)

  entries_list.each do |entry|
    serialize_po_entry(entry, lines)
  end

  lines.join("\n")
rescue StandardError => e
  ErrorHandler.log_warning('serializing PO file entries', e)
  ''
end

.set_po_entry_msgstr(po_entry, existing_entry, new_msgstr, fuzzy_candidates = {}) ⇒ Object 



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 113

def self.set_po_entry_msgstr(po_entry, existing_entry, new_msgstr,
                             fuzzy_candidates = {})
  if existing_entry.is_a?(Hash)
    po_entry.msgstr = existing_entry[:msgstr] || ''
    po_entry.flag   = 'fuzzy' if existing_entry[:fuzzy]
    po_entry.previous = existing_entry[:previous_msgid] if existing_entry[:previous_msgid]
  elsif existing_entry
    po_entry.msgstr = existing_entry
  else
    match = PoFuzzyMatcher.find_match(po_entry.msgid, fuzzy_candidates)
    if match
      po_entry.msgstr   = match[:msgstr]
      po_entry.flag     = 'fuzzy'
      po_entry.previous = match[:msgid]
    else
      po_entry.msgstr = new_msgstr || ''
    end
  end
end

.setup_po_header(po_file, locale) ⇒ Object 



138
139
140
141
142
143
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 138

def self.setup_po_header(po_file, locale)
  header_entry = ::GetText::POEntry.new(:normal)
  header_entry.msgid = ''
  header_entry.msgstr = header(locale)
  po_file[''] = header_entry
end

.write(po_path, entries, locale, skip_merge: false) ⇒ Boolean

Write entries to a PO file.

Creates or updates a PO file with the provided entries. If file exists and skip_merge is false, existing translations are merged (preserved while new entries added). Sets proper PO header with language and UTF-8 encoding.

Parameters:

  • po_path (String) —

    Full path to output PO file

  • entries (Array<Hash>) —

    Array of extraction entries, each with:

    • :msgid [String] String to translate

    • :msgstr [String] Translated string (typically empty for new extractions)

    • :reference [String] File location reference for debugging

  • locale (String) —

    Locale code (e.g., ‘es’, ‘fr’)

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

    If true, overwrite without merging existing translations

Returns:

  • (Boolean) —

    True if successful



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/jekyll-l10n/po_file/writer.rb', line 50

def self.write(po_path, entries, locale, skip_merge: false)
  existing_po = if skip_merge || !File.exist?(po_path)
                  {}
                else
                  PoFileReader.parse_for_merge(po_path)
                end

  po_file = ::GetText::PO.new
  setup_po_header(po_file, locale)
  merge_entries_preserving_translations(po_file, entries, existing_po)

  output = serialize_po_file(po_file)
  FileOperations.write_utf8(po_path, output)

  true
end