Class | YARD::I18n::PotGenerator
In: | lib/yard/i18n/pot_generator.rb
Parent: | Object

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} 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.

## 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".

@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

### Methods

generate new parse_files parse_objects

### Attributes

messages | [R] | Extracted messages. @return [Messages] @since 0.8.1

### Public Class methods

new(relative_base_path)

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.

### Public Instance methods

generate()

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

parse_files(files)

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]

parse_objects(objects)

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]

[Validate]