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.

✨ This package now only supports ESM. For CommonJS use version 3. 🎉

Use case

If you have a development set-up where gettext translation strings are automatically extracted and compiled into a POT file, it can be bothersome to have to re-create PO files from that new POT file and include already translated strings from previous PO files. Especially, if you have multiple languages, like for a WordPress theme or plugin.

In this case, you can use this module to auto-create new PO files based on the new POT file, and have it fill in existing translated strings from previous PO files. The created PO files can now be opened and edited with the benefit of having to do fewer copy-pastes.

For Gulp, there is a wrapper plugin gulp-fill-pot-po.

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 (ESM)

import fillPotPo from "fill-pot-po";

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

fillPotPo(cb, options);

Example (CommonJS - only with versions <= 3)

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 (ESM)

import { sync as fillPotPoSync } from "fill-pot-po";

try {
  const results = fillPotPoSync(options);

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

Example (CommonJS - only with versions <= 3)

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

try {
  const results = fillPotPoSync(options);

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

Locating PO files for each POT file

For each POT file that is processed, the module will try to locate the proper PO files.

This is the algorithm in pseudo-code:

if (options.poSources) {
  po_search_glob = options.poSources;
} else {
  source_dir = options.srcDir || pot_file_directory;

  if (options.domainInPOPath) {
    if (options.domainFromPOTPath) {
      // NOTE: If the POT file is an unnamed Vinyl object, an error will be thrown now.

      po_search_glob = `${source_dir}/${pot_file_basename_without_ext}-${any_locale}.po`;
    } else {
      // NOTE: If options.domain is empty, an error will be thrown now.

      po_search_glob = `${source_dir}/${options.domain}-${any_locale}.po`;
    }
  } else {
    po_search_glob = `${source_dir}/${any_locale}.po`;
  }
}

// NOTE: For all glob searches, options.srcGlobOptions will be used.

For actual source code, see getPOFilepaths() in src/shared.js.

See also options poSources, srcDir, domainInPOPath, domainFromPOTPath and domain.

Options

Overview of all defaults

{
    // Input-related
    potSources: ['**/*.pot', '!node_modules/**'],
    poSources: null,
    srcDir: '',
    domainInPOPath: true,
    domainFromPOTPath: true,
    domain: '',
    srcGlobOptions: {},

    // Content-related
    wrapLength: 77,
    defaultContextAsFallback: false,
    appendNonIncludedFromPO: false,
    includePORevisionDate: false,
    includeGenerator: true,

    // Output-related
    returnPOT: false,
    writeFiles: true,
    destDir: '',
    logResults: false,
}

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 Locating PO files for each POT file for more info.

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.

See Locating PO files for each POT file for more info.

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 Locating PO files for each POT file for more info.

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 Locating PO files for each POT file for more info.

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 Locating PO files for each POT file for more info.

Default: ''

srcGlobOptions

object

Glob options used when matching PO source files.

See Locating PO files for each POT file for more info.

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

Extra

• Guide for migrating your Gulp set-up from CommonJS to ESM

License

MIT © Philip van Heemstra