fill-pot-po

fill-pot-po   

Generate pre-filled PO files from POT file, using source PO files.

Based on the POT filename or set options, it looks for source PO files. For each PO file, it will create a new one, based on the contents of the POT file. The source PO file is used to fill in the matching translated strings.

Install

npm install --save-dev fill-pot-po

Usage

The fill-pot-po module exports an asynchronous and a synchronous method.

Depending on the chosen method, the result and the handling of the result is slightly different (see examples below).

1. Asynchronous (recommended)

fillPotPo( cb, options )

Processes the POT files and found PO files in parallel.

cb	required	function Callback function, with one argument containing the results (see Results).
options	optional	object Options object (see Options).
string|array Alternatively, a glob string or array can be provided that will be used as options.poSources. All other options will have their default values.

Example

const fillPotPo = require('fill-pot-po');

const cb = results => {
    // ...
};

fillPotPo( cb, options );

2. Synchronous

fillPotPoSync( options )

Processes the POT files and found PO files in series (slower).

options	optional	object Options object (see Options).
string|array Alternatively, a glob string or array can be provided that will be used as options.poSources. All other options will have their default values.
returns	array Results array on success (see Results).
throws	PluginError On error ;)

Example

const fillPotPoSync = require('fill-pot-po').sync;

try {
    const results = fillPotPoSync( options );

    //...
} catch ( error ) {
    console.log( error );
}

Options

potSources

string|Vinyl|array

The POT files to process. Can be a path or glob string, a Vinyl object, an array of strings or an array of Vinyl objects.

Default: ['**/*.pot', '!node_modules/**']

Options related to locating PO files

poSources

string|array

The PO source files to use. Can be a path or glob string, or an array of paths/globs.

By default, or if falsy, the module will look for PO files with filenames like {text-domain}-{locale}.po or {locale}.po if domainInPOPath is set to false.

{text-domain} is either the POT filename or the value set in the domain option.

See also domainInPOPath, domainFromPOTPath and domain.

Default: null

srcDir

string

Relative path from current working directory or absolute path to folder where source PO files can be found.

By default, the same folder as the POT file will be used.

Default: ''

domainInPOPath

boolean

Match source PO files with the text domain name in the filename.

For example: text-domain-en_EN.po and text-domain-nl_NL.po.

See also domainFromPOTPath and domain.

Default: true

domainFromPOTPath

boolean

Whether or not to get the text domain from the POT filename (excluding extension).

If set to false and domainInPOPath is true, a text domain must be set using the domain option.

See also domainInPOPath and domain.

Default: true

domain

string

The text domain slug, like text-domain.

By default this is the POT filename excluding extension and is used to find the right PO source files.

See also domainInPOPath and domainFromPOTPath.

Default: ''

srcGlobOptions

object

Glob options used when matching PO source files.

Default: {}

Options related to output

returnPOT

boolean

Whether the plugin should return the source POT file(s) (true) or the generated PO file(s) (false).

By default, it will return the generated PO files.

NOTE: If set to true, you need to set writeFiles to true as well or else no PO files will be generated and the plugin throws an error.

Default: false

writeFiles

boolean

Whether or not to write the newly generated PO files to disk.

If you wish to process the results array and content buffers yourself, you could set this to false.

NOTE: When using gulp-fill-pot-po, the default is false, since the resulting buffers will probably be .pipe( dest() )'d, which writes them to disk instead.

Default: true (for gulp-fill-pot-po: false)

destDir

string

Only if writeFiles is true.

Relative path from current working directory or absolute path to the folder where the PO files should be written.

Default: ''

logResults

boolean

Log results to console.

Default: false

Options related to generating PO content

wrapLength

integer

Line wrapping length excluding quotation marks.

This is forwarded as foldLength to gettext-parser.

Default: 77

defaultContextAsFallback

boolean

If a string is not found in the PO source file with a certain context, try searching for the same string without a context and use that.

A flag comment #, fuzzy will be added to signal translators to check the translation.

Default: false

appendNonIncludedFromPO

boolean

Append all translated strings from the source PO file that were not in the POT file.

A translator comment # DEPRECATED will be added to them.

Default: false

includePORevisionDate

boolean

Include a PO-Revision-Date header to the PO files with the current timestamp.

Default: false

includeGenerator

boolean

Include a X-Generator header to the PO files.

Default: true

Results

Results - Async mode

The first argument of the callback function will be the results array:

results[0]

boolean True on success, false on error.

results[1] (on success)

array Array of Vinyl file objects, depending on the value of options.returnPOT:

false	The generated PO files. (default)
true	The input POT files.

results[1] (on error)

string Error message.

Results - Sync mode

On success

array Returns an array of Vinyl file objects, depending on the value of options.returnPOT:

false	The generated PO files. (default)
true	The input POT files.

On error

On error, fillPotPoSync() will throw an error.

Related

• gulp-fill-pot-po - Run fill-pot-po in gulp
• gettext-parser - Parse and compile gettext PO and MO files with NodeJS
• gulp-wp-pot - Generate POT files in WordPress project in gulp

License

MIT © Philip van Heemstra