The PotGenerator
generates POT format string from
{CodeObjects::Base} and {CodeObjects::ExtraFileObject}.
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”.
The PotGenerator
has two parse methods:
{parse_objects} for {CodeObjects::Base}
{parse_files} for {CodeObjects::ExtraFileObject}
{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.
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”.
@example 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 www.gnu.org/software/gettext/manual/html_node/PO-Files.html
GNU gettext manual about details of PO file
Extracted messages.
@return [Messages] @since 0.8.1
Creates a POT generator that uses relative_base_path
to
generate locations for a msgid. relative_base_path
is
prepended to all locations.
@param [String] relative_base_path a relative working
directory path from a directory path that has created .pot file.
# File lib/yard/i18n/pot_generator.rb, line 78 def initialize(relative_base_path) @relative_base_path = relative_base_path @extracted_objects = {} @messages = Messages.new end
Generates POT from +@messages+.
One PO file entry is generated from a Message
in +@messages+.
Locations of the Message
are used to generate the reference
line that is started with “#: ”. relative_base_path
passed
when the generater is created is prepended to each path in location.
Comments of the Message
are used to generate the
translater-comment line that is started with “# ”.
@return [String] POT format string
# File lib/yard/i18n/pot_generator.rb, line 121 def generate pot = header sorted_messages = @messages.sort_by do |message| sorted_locations = message.locations.sort_by do |location| location end sorted_locations.first || [] end sorted_messages.each do |message| generate_message(pot, message) end pot end
Parses {CodeObjects::ExtraFileObject} objects and stores extracted msgids into {messages}.
@param [Array<CodeObjects::ExtraFileObject>] files a list
of {CodeObjects::ExtraFileObject} objects to be parsed.
@return [void]
# File lib/yard/i18n/pot_generator.rb, line 102 def parse_files(files) files.each do |file| extract_paragraphs(file) end end
Parses {CodeObjects::Base} objects and stores extracted msgids into {messages}
@param [Array<CodeObjects::Base>] objects a list of
{CodeObjects::Base} to be parsed.
@return [void]
# File lib/yard/i18n/pot_generator.rb, line 90 def parse_objects(objects) objects.each do |object| extract_documents(object) end end