157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
# 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)
|