{"id":19335241,"url":"https://github.com/wp-blocks/make-pot","last_synced_at":"2025-11-23T04:04:07.108Z","repository":{"id":216289002,"uuid":"740907066","full_name":"wp-blocks/make-pot","owner":"wp-blocks","description":"A node.js module that generates the pot file for your WordPress plugin or theme.","archived":false,"fork":false,"pushed_at":"2024-05-11T21:28:58.000Z","size":1760,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-05-14T12:25:13.468Z","etag":null,"topics":["gettext","i18n","pot","translations","wordpress"],"latest_commit_sha":null,"homepage":"https://wp-blocks.github.io/make-pot/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wp-blocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-09T10:09:06.000Z","updated_at":"2024-07-06T13:39:42.841Z","dependencies_parsed_at":"2024-01-17T13:53:30.287Z","dependency_job_id":"16715d6a-879f-4135-b683-92782db18247","html_url":"https://github.com/wp-blocks/make-pot","commit_stats":null,"previous_names":["erikyo/makepot","wp-blocks/makepot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2Fmake-pot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2Fmake-pot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2Fmake-pot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2Fmake-pot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wp-blocks","download_url":"https://codeload.github.com/wp-blocks/make-pot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250348305,"owners_count":21415893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gettext","i18n","pot","translations","wordpress"],"created_at":"2024-11-10T03:06:36.598Z","updated_at":"2025-11-23T04:04:07.102Z","avatar_url":"https://github.com/wp-blocks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/npm/v/@wp-blocks/make-pot.svg?label=npm%20version)](https://www.npmjs.com/package/@wp-blocks/make-pot)\n[![](https://img.shields.io/npm/l/@wp-blocks/make-pot)](https://github.com/wp-blocks/make-pot?tab=GPL-3.0-1-ov-file#readme)\n[![](https://github.com/wp-blocks/make-pot/actions/workflows/node.js.yml/badge.svg)](https://github.com/wp-blocks/make-pot/actions/workflows/node.js.yml)\n\n## Make POT\n\n`make-pot` is a Node.js module designed to generate the `.pot` file for your WordPress plugin or theme. This file serves as the basis for internationalization, allowing translators to localize your plugin or theme into different languages.\n\nExtract strings from your WordPress plugin or theme and generate a `.pot` file. Works with `js`, `jx`, `ts`, `tsx`, `cjs`, `mjs`,  `php`, `blade`, `txt`, `json` with a custom schema for theme and block.json files.\n\n## Make JSON\n`make-json` is a Node.js module designed to convert `.po` files into JSON format for your WordPress plugin or theme. This conversion facilitates client-side translations and enables your JavaScript code to use the translated strings.\n\nTransform your translation files into a JSON format compatible with WordPress i18n package. This module simplifies the process of making your WordPress plugin or theme fully translatable on the frontend.\n\n## Installation\n\nYou can install `make-pot` as a dependecy via npm:\n\n```\nnpm install -d @wp-blocks/make-pot\n```\n\nor globally\n\n```\nnpm install -g @wp-blocks/make-pot\n```\n\n### Usage\n\n```bash\n# without installation\nnpx @wp-blocks/make-pot [sourceDirectory] [destination] [options]\nnpx -p @wp-blocks/make-pot makejson [sourceDirectory] [destination] [options]\n\n# installed\nnpx makepot [sourceDirectory] [destination] [options]\nnpx makejson [sourceDirectory] [destination] [options]\n```\n\n## Make Pot\n\nExample usage:\n\n```bash\n# without installation\nnpx @wp-blocks/make-pot src languages --charset='utf-8' --include=\"src/**/*.{ts,tsx},inc/**/*,admin/**/*.{php}\"\n```\n\n#### Positional Arguments:\n\n- `sourceDirectory` (optional): Specifies the source directory of your plugin or theme. If not provided, the `.pot` file root will be the source directory.\n- `destination` (optional): Specifies the destination directory where the `.pot` file will be generated. If not provided, the `.pot` file will be created in the source directory.\n\n#### Make Pot Options:\n\n- `--version`: Displays the version number of `make-pot`.\n- `-h`, `--help`: Displays help information.\n- `--slug \u003cslug\u003e`: Specifies the plugin or theme slug.\n- `--domain \u003cdomain\u003e`: Specifies the text domain to look for in the source code, you can choose \"plugin\", \"theme\", \"block\", \"theme-block\", \"generic\".\n- `--skip-js`: Skips JavaScript files during processing.\n- `--skip-php`: Skips PHP files during processing.\n- `--skip-blade`: Skips Blade files during processing.\n- `--skip-block-json`: Skips block.json files during processing.\n- `--skip-theme-json`: Skips theme.json files during processing.\n- `--skip-audit`: Skips auditing of strings.\n- `--headers \u003cheaders\u003e`: Specifies additional headers for the `.pot` file. Accepts an array of strings (--headers=email:erik@ck.it,domain:my-block) or multiple values (--headers=email:erik@ck.it --headers=domain:my-block)\n- `--file-comment \u003ccomment\u003e`: Specifies the file comment for the `.pot` file.\n- `--package-name \u003cname\u003e`: Specifies the package name.\n- `--location`: Includes location information in the `.pot` file.\n- `--ignore-domain`: Ignores text domain in the processing.\n- `--mergePaths \u003cpaths\u003e`: Merges with existing POT file(s).\n- `--subtractPaths \u003cpaths\u003e`: Subtracts strings from existing POT file(s).\n- `--subtractAndMerge`: Subtracts and merges strings from existing POT file(s).\n- `--include \u003cfiles\u003e`: Includes specific files for processing.\n- `--exclude \u003cfiles\u003e`: Excludes specific files from processing.\n- `--silent`: Suppresses output to stdout.\n- `--json`: Outputs the JSON gettext data.\n- `--charset`: Defines the encoding charset of the pot file, you can choose \"iso-8859-1\" and \"uft-8\" (defaults to iso-8859-1)\n- `--translation-domains`: Restrict to specific translation domains.\n- `--output`: Outputs the gettext data.\n\n### Example usage\n\nFirst of all remember that the 'make-pot' help can be printed using the command `npx @wp-blocks/make-pot -h`, and the help for the json command can be printed using the command `npx make-json -h`. the commands are available after installing the module (`npm install @wp-blocks/make-pot`)\n\n#### Using `make-pot` in your `package.json` (assiming you have already installed the makepot command)\n```bash\n\t\"scripts\": {\n\t\t\"build\": \"npm run build:scripts \u0026\u0026 npm run build:makepot\",\n\t\t\"build:scripts\": \"wp-scripts build\",\n\t\t\"build:makepot\": \"npx makepot\",\n\t\t\"build-2:makejson\": \"npx makejson\",\n\t}\n```\n\u003e Note: that it should be launched after creating the “.po” files with the localized translations (and then at a later time)\n\nBoth command does not need any arguments, they will parse the required data from the plugin file (the one in the root directory with the same name of the folder) or the theme.json/theme css file in the case of themes.\nSo what you should check before running the command is to have all the WordPress and Node.js required data/metadata in place, nothing else. Anyway, the command can be customized if you need, let's see some examples:\n\n#### Using `make-pot` include and exclude files\nWe use glob module to include and exclude files. please check [glob](https://github.com/isaacs/node-glob)\n\n```bash\n\t# Every file in includes, frontend and admin directories that is not in node_modules\n\tnpx @wp-blocks/make-pot --include='includes/**/*,frontend/**/*,admin/**/*' --exclude=\"**/node_modules/**\"\n\n\t# Every file that is a tsx, ts, js and not in node_modules\n\tnpx @wp-blocks/make-pot --include='**/*.{tsx,ts,js}' --exclude=\"**/node_modules/**\"\n\n\t# Merge the resulting pot file with another pot file\n\tnpx @wp-blocks/make-pot --mergePaths='path/to/other.pot'\n\n\t# Remove the strings from the resulting pot file with another pot file\n\tnpx @wp-blocks/make-pot --subtractPaths='path/to/other.pot'\n```\n\n#### Tip:\nThe include and exclude options works in a different way... the include option adds the files to the default list of files to be processed, while the exclude option replaces the original list and excludes the specified files/directories.\nThe mergePaths option will merge the resulting pot file with another pot file, while the subtractPaths option will subtract the strings from the resulting pot file with another pot file.\n\n## As a build chain step\n\nThe `make-pot` module can be used as a build step in your build chain.\nTo do so, create a `build:makepot` action in your `package.json` with the following content (refer to the [options](https://github.com/wp-blocks/make-pot?tab=readme-ov-file#options) for more information):\n\n```json\n{\n\t\"build:makepot\": \"npx @wp-blocks/make-pot [sourceDirectory] [destination] [options]\"\n}\n```\n---\n\n# Make JSON\n\n### Why JSON Translation for WordPress JavaScript?\n\n#### Overview\nWordPress 5.0 introduced Gutenberg, a JavaScript-heavy editor. This shifted much of the internationalization (I18N) work from the server to the client side. While functions like `wp_localize_script()` were used before, Gutenberg required a more robust solution.\n\n#### JavaScript Localization Functions\nWordPress 5.0 introduced the `wp-i18n` JavaScript package, offering localization functions (`__()`, `_x()`, `_n()`, `_nx()`, `sprintf()`) similar to their PHP counterparts, enabling seamless I18N in JavaScript.\n\n#### Loading Translations\nTo fully internationalize a plugin or theme, you must load translations using `wp_set_script_translations()`, which requires:\n1. Script handle (e.g., `my-plugin-script`)\n2. Text domain (e.g., `my-plugin`)\n3. Optional: Path to translation files (if not hosted on WordPress.org)\n\n#### JSON Translation Files\nUnlike traditional PO/MO files, JavaScript translations use JSON. This format is easily readable in JavaScript and compatible with the Jed JavaScript gettext library, used by the `wp-i18n` package. WordPress.org generates these JSON files automatically, but custom ones can be created if needed.\n\n## JSON Utility args\n\n- `source`: (positional) the source directory of your plugin or theme translations (e.g. `languages`).\n- `destination`: (positional and optional) The destination directory where the `.json` file will be generated. If not provided, the `.json` file will be created in the source directory.\n- `--scriptName`: The name of the script that needs this translation file.\n- `--allowedFormats`: The allowed formats of the translation file (e.g. `js` or `tsx`).\n- `--purge`: if enabled, removes the existing translation file. Otherwise, the old translation file will be merged with the new.\n- `--prettyPrint`: Pretty prints the translation file.\n- `--stripUnused`: strips unused translations from the translation file (default: true).\n- `--debug`: Enables debug mode.\n\n## How to Generate Json translations\n\n#### Build the json translations file\n\nFirst, build the translation pot file using `makepot` (no matter with this module or not) and then translate it into the different languages.\n\ntranslate the pot file into your language and then run `makejson`:\n\n```bash\nnpx makejson\n# OR if you don't want to install the module\nnpx -p @wp-blocks/make-pot makejson,\n```\nIt Will create a file for each po file in the `languages` directory with the md5 hash with the name of the file.\nIn this case, the file will be named my-frontend-script-en_US-79431f0eb8deb8221f24df5112e15095.json because the md5 hash of \"build/frontend.js\" is 79431f0eb8deb8221f24df5112e15095.\nThis is crucial because the md5 hash has to be the same as the path of the script file.\n\n## Register the javascript block translations\n\n```php\n\u003c?php\n/**\n * Loads the plugin text domain for translation.\n */\nfunction my_i18n() {\n    load_plugin_textdomain( 'my-text-domain', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );\n}\nadd_action( 'init', 'my_i18n' );\n\n/**\n * Registers the block using the metadata loaded from the `block.json` file.\n */\nadd_action('init', function () {\n\tregister_block_type( dirname( plugin_basename( __FILE__ ) ) . '/build', [\n\t\t\"script\" =\u003e \"my-vendor-script\",\n\t\t\"viewScript\" =\u003e \"my-frontend-script\",\n\t\t\"editorScript\" =\u003e \"my-editor-script\",\n\t]);\n});\n\n/**\n * Registers the block using the metadata loaded from the `block.json` file.\n */\nfunction my_register_block_type() {\n\n\t$fe_assets = include dirname( __FILE__ ) . '/build/my-frontend-script.asset.php';\n\n\twp_register_script(\n\t\t'my-frontend-script',\n\t\tVSGE_MB_PLUGIN_URL . 'build/frontend.js',\n\t\t$fe_assets['dependencies'],\n\t\t$fe_assets['version']\n\t);\n\n\t// 1 - the name of the hook used to register the script\n\t// 2 - the text domaim of the block\n\t// 3 - the path to the translations directory\n\twp_set_script_translations( 'my-frontend-script', 'my-text-domain', plugin_dir_url(__FILE__) . '/languages' );\n\n\t...\n}\nadd_action( 'init', 'my_register_block_type' );\n```\n\n### Credits\n\nThis module is heavily inspired by the original `makepot` command from [WP-CLI](https://github.com/wp-cli/i18n-command).\nSpecial thanks to the maintainers in particular [Swissspidy](https://github.com/swissspidy) which\nhas been very helpful with suggestions and tips on how to rebuild `make-pot`.\n\n#### Useful links\n- https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/\n- https://pascalbirchler.com/internationalization-in-wordpress-5-0/\n\nFeel free to contribute or report issues on [GitHub](https://github.com/example/example).\n\nThis tool is licensed under the [GNU General Public License v3](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwp-blocks%2Fmake-pot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwp-blocks%2Fmake-pot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwp-blocks%2Fmake-pot/lists"}