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

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.

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

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

Processes the POT files and found PO files in parallel.

import fillPotPo from "fill-pot-po";

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

fillPotPo(cb, options);

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

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

fillPotPo(cb, options);

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

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

try {
  const results = fillPotPoSync(options);

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

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

try {
  const results = fillPotPoSync(options);

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

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.

{
    // 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,
}

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/**']

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

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: ''

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

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

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: ''

object

Glob options used when matching PO source files.

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

Default: {}

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

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)

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: ''

boolean

Log results to console.

Default: false

integer

Line wrapping length excluding quotation marks.

This is forwarded as foldLength to gettext-parser.

Default: 77

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

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

boolean

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

Default: false

boolean

Include a X-Generator header to the PO files.

Default: true

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

boolean True on success, false on error.

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

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

string Error message.

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, fillPotPoSync() will throw an error.

• 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

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

MIT © Philip van Heemstra