# Makepot task

Generate a POT file for translators to use when translating your plugin or theme.

_Run this task with the `grunt makepot` command._


## Overview

In your project's Gruntfile, add a section named `makepot` to the data object passed into `grunt.initConfig()`.

```js
grunt.initConfig({
    makepot: {
        target: {
            options: {
                cwd: '',                          // Directory of files to internationalize.
                domainPath: '',                   // Where to save the POT file.
                exclude: [],                      // List of files or directories to ignore.
                include: [],                      // List of files or directories to include.
                mainFile: '',                     // Main project file.
                potComments: '',                  // The copyright at the beginning of the POT file.
                potFilename: '',                  // Name of the POT file.
                potHeaders: {
                    poedit: true,                 // Includes common Poedit headers.
                    'x-poedit-keywordslist': true // Include a list of all possible gettext functions.
                },                                // Headers to add to the generated POT file.
                processPot: null,                 // A callback function for manipulating the POT file.
                type: 'wp-plugin',                // Type of project (wp-plugin or wp-theme).
                updateTimestamp: true             // Whether the POT-Creation-Date should be updated without other changes.
                updatePoFiles: false              // Whether to update PO files in the same directory as the POT file.
            }
        }
    }
});
```

## Options

All options are optional, but at the very least a target needs to exist. At a minimum, set an option specifying the type of project.

```js
grunt.initConfig({
    makepot: {
        target: {
            options: {
                type: 'wp-plugin'
            }
        }
    }
});
```

### options.cwd
Type: `String`  
Default value: `''`  
Example value: `'release'`

The directory that should be internationalized. Defaults to the project root, but can be set to a subdirectory, for instance, when used in a build process. Should be relative to the project root.

### options.domainPath
Type: `String`  
Default value: `''`  
Example value: `'/languages'`

The directory where the POT file should be saved. Defaults to the value from the "Domain Path" header if it exists.

### options.exclude
Type: `String`  
Default value: `[]`  
Example value: `['subdir/.*']`

List of files or directories to ignore when generating the POT file. Note that the globbing pattern is a basic PHP [regular expression](https://github.com/blazersix/grunt-wp-i18n/blob/develop/vendor/wp-i18n-tools/extract.php#L66).

### options.include
Type: `String`  
Default value: `[]`  
Example value: `['subdir/.*']`

List of files or directories to include when generating the POT file. Note that the globbing pattern is a basic PHP [regular expression](https://github.com/blazersix/grunt-wp-i18n/blob/develop/vendor/wp-i18n-tools/extract.php#L66)

### options.mainFile
Type: `String`  
Default value: `''`  
Example value: `'plugin-slug.php'` or `'style.css'`

Name of the main project file where the headers can be found. In themes, this will default to `style.css`. An attempt will be made to auto-discover the main file for plugins, but specifying it here can improve performance and will help disambiguate between multiple plugin files in the same project.

### options.potComments
Type: `String`  
Example value: `'Custom Copyright (c) {{year}}'`

Comment at the beginning of the POT file. Defaults to the copyright message generated by makepot.php. Use `\n` for newlines and `{{year}}` to insert the current year.

### options.potFilename
Type: `String`  
Default value: `''`  
Example value: `'plugin-or-theme-slug.pot'`

Name of the POT file. Defaults to the "Text Domain" header if it exists, otherwise uses the project directory name.

### options.potHeaders
Type: `Object`  
Example value: `{ 'report-msgid-bugs-to': 'https://github.com/blazersix/grunt-wp-i18n/issues' }`

List of headers to add to the POT file in the form of key-value pairs.

Adding a `poedit` property with a value of `true` will add the following commonly-used Poedit headers to ease setup for translators:

```js
{
    'language': 'en',
    'plural-forms': 'nplurals=2; plural=(n != 1);',
    'x-poedit-country': 'United States',
    'x-poedit-sourcecharset': 'UTF-8',
    'x-poedit-keywordslist': '__;_e;__ngettext:1,2;_n:1,2;__ngettext_noop:1,2;_n_noop:1,2;_c;_nc:1,2;_x:1,2c;_ex:1,2c;_nx:4c,1,2;_nx_noop:4c,1,2;',
    'x-poedit-basepath': '../',
    'x-poedit-searchpath-0': '.',
    'x-poedit-bookmarks': '',
    'x-textdomain-support': 'yes'
}
```

If custom values are used for the various Poedit headers, but you want to include WordPress gettext function calls, set the value of `x-poedit-keywordslist` to `true` and they will be included automatically.

### options.processPot
Type: `Function( pot, options )`  
Default value: `null`

A callback function for advanced manipulation of the POT file after it's generated.

### options.type
Type: `String`  
Default value: `'wp-plugin'`  
Example value: `'wp-plugin'` or `'wp-theme'`

The type of project.

### options.updateTimestamp
Type: `Boolean`  
Default value: `true`

Whether the `POT-Creation-Date` header should be updated if no other changes to the POT file are detected.

### options.updatePoFiles
Type: `Boolean`  
Default value: `false`

[GNU gettext](https://www.gnu.org/software/gettext/) must be in your system path to use this option.

Whether to update the PO files that are present in the same directory as the POT file using the [msgmerge](https://www.gnu.org/software/gettext/manual/html_node/msgmerge-Invocation.html) program.

## Usage Examples

* [Using a custom working directory.](examples/custom-working-directory.md)
* [Remove plugin or theme metadata from the POT file.](examples/remove-package-metadata.md)