Class: YARD::I18n::PotGenerator

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/i18n/pot_generator.rb

Overview

The PotGenerator generates POT format string from CodeObjects::Base and CodeObjects::ExtraFileObject.

POT and PO

POT is an acronym for “Portable Object Template”. POT is a template file to create PO file. The extension for POT is “.pot”. PO file is an acronym for “Portable Object”. PO file has many parts of message ID (msgid) that is translation target message and message string (msgstr) that is translated message of message ID. If you want to tranlsate “Hello” in English into “Bonjour” in French, “Hello” is the msgid ID and “Bonjour” is msgstr. The extension for PO is “.po”.

How to extract msgids

The PotGenerator has two parse methods:

#parse_objects extracts msgids from docstring and tags of CodeObjects::Base objects. The docstring of CodeObjects::Base object is parsed and a paragraph is extracted as a msgid. Tag name and tag text are extracted as msgids from a tag.

#parse_files extracts msgids from CodeObjects::ExtraFileObject objects. The file content of CodeObjects::ExtraFileObject object is parsed and a paragraph is extracted as a msgid.

Usage

To create a .pot file by PotGenerator, instantiate a PotGenerator with a relative working directory path from a directory path that has created .pot file, parse CodeObjects::Base objects and CodeObjects::ExtraFileObject objects, generate a POT and write the generated POT to a .pot file. The relative working directory path is “..” when the working directory path is “.” and the POT is wrote into “po/yard.pot”.

Examples:

Generate a .pot file

po_file_path = "po/yard.pot"
po_file_directory_pathname = Pathname.new(po_file_path).directory)
working_directory_pathname = Pathname.new(".")
relative_base_path = working_directory_pathname.relative_path_from(po_file_directory_pathname).to_s
# relative_base_path -> ".."
generator = YARD::I18n::PotGenerator.new(relative_base_path)
generator.parse_objects(objects)
generator.parse_files(files)
pot = generator.generate
po_file_directory_pathname.mkpath
File.open(po_file_path, "w") do |pot_file|
  pot_file.print(pot)
end

See Also:

Since:

  • 0.8.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(relative_base_path) ⇒ PotGenerator

Creates a POT generator that uses relative_base_path to generate locations for a msgid.

Parameters:

  • relative_base_path (String) —

    a relative working directory path from a directory path that has created .pot file.

Since:

  • 0.8.0


89
90
91
92
93
 
# File 'lib/yard/i18n/pot_generator.rb', line 89

def initialize(relative_base_path)
  @relative_base_path = relative_base_path
  @extracted_objects = {}
  @messages = {}
end

Instance Attribute Details

#messages ⇒ Hash{String => Hash{:locations => Array<Array[String, Integer]>, :comments => Array<String>}} (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Extracted messages. Key is a translation target message and value is properties of the translation target message. The properties are added to the msgid entry for the translation target message. The properties are :locations and :comments.

:locations is an array of location. Location is an array of path and line number of the translation target message is appeared. Each location is prepended :relative_base_path that is passed on creating a PotGenerator instance.

:comments is an array of comment. All comments are added to the msgid entry for the translation target message.

Returns:

Since:

  • 0.8.0


81
82
83
 
# File 'lib/yard/i18n/pot_generator.rb', line 81

def messages
  @messages
end

Instance Method Details

#generate ⇒ String

Generates POT from @messages.

Returns:

  • (String) —

    POT format string

Since:

  • 0.8.0


122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/yard/i18n/pot_generator.rb', line 122

def generate
  pot = header
  sorted_messages = @messages.sort_by do |message, options|
    sorted_locations = (options[:locations] || []).sort_by do |location|
      location
    end
    sorted_locations.first || []
  end
  sorted_messages.each do |message, options|
    generate_message(pot, message, options)
  end
  pot
end

#parse_files(files) ⇒ void

This method returns an undefined value.

Parses CodeObjects::ExtraFileObject objects and stores extracted msgids into #messages.

Parameters:

Since:

  • 0.8.0


113
114
115
116
117
 
# File 'lib/yard/i18n/pot_generator.rb', line 113

def parse_files(files)
  files.each do |file|
    extract_paragraphs(file)
  end
end

#parse_objects(objects) ⇒ void

This method returns an undefined value.

Parses CodeObjects::Base objects and stores extracted msgids into #messages

Parameters:

Since:

  • 0.8.0


101
102
103
104
105
 
# File 'lib/yard/i18n/pot_generator.rb', line 101

def parse_objects(objects)
  objects.each do |object|
    extract_documents(object)
  end
end