Skip to content

Latest commit

 

History

History
156 lines (117 loc) · 5.98 KB

makepot.md

File metadata and controls

156 lines (117 loc) · 5.98 KB
Raw

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

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.

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.

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

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:

{
    '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 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 program.

Usage Examples