@wpelevator/wp-release 0.16.0 → 0.17.0

package/README.md

@@ -1,10 +1,10 @@
 # WP Release
 
-Package, checksum, sign, verify and version-check WordPress plugins and themes, deploy plugins to the WordPress.org plugin SVN repository, and deploy plugins, themes and packages to Git repositories. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
+Package, checksum, sign, verify and version-check WordPress plugins and themes, extract and compile their translations, deploy plugins to the WordPress.org plugin SVN repository, and deploy plugins, themes and packages to Git repositories. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
 
 Themes are released by uploading a ZIP on WordPress.org, so `deploy-svn` is for plugins only; use `zip` to build the theme upload.
 
-Option names follow the existing community tools (10up WordPress.org actions, `wp dist-archive`, `wp-scripts plugin-zip`, `grunt-wp-deploy`) so that migrating needs few or no renames. See [Comparison with existing tools](#comparison-with-existing-tools) for the differences.
+Packaging and deploy options follow the existing community tools (10up WordPress.org actions, `wp dist-archive`, `wp-scripts plugin-zip`, `grunt-wp-deploy`) so that migrating needs few or no renames. The internationalization commands favor simpler, CI-friendly options over matching `wp i18n`. See [Comparison with existing tools](#comparison-with-existing-tools) for the differences.
 
 ## Install
 
@@ -35,12 +35,17 @@ npx wp-release --help
 | `wp-release deploy-git [<source-dir>] --git-url <url> [options]` | Deploy the files of a plugin, theme or package to a Git repository as a release commit. |
 | `wp-release deploy-git --release-ref <ref> [--package <name>] [--list]` | Deploy the configured packages of a release tag or branch to their Git targets. |
 | `wp-release deploy-svn --release-ref <ref> [--package <name>] [--list]` | Deploy the configured plugin of a release tag to WordPress.org. |
+| `wp-release i18n-pot [<source-dir>] [options]` | Extract translatable strings into a reproducible POT file. |
+| `wp-release i18n-audit [<source-dir>] [options]` | Report translation string problems without writing files. |
+| `wp-release i18n-mo <file.po> [options]` | Compile a translated PO file into MO. |
+| `wp-release i18n-json <file.po> --domain <domain> [options]` | Compile the JavaScript strings of a translated PO file into WordPress script JSON files. |
+| `wp-release i18n-php <file.po> [options]` | Compile a translated PO file into a WordPress `.l10n.php` file. |
 | `wp-release changeset-add [options]` | Record the release impact of a pull request. |
 | `wp-release changeset-status [options]` | List pending releases and check changed packages for changesets. |
 | `wp-release changeset-version [options]` | Apply version bumps and changelog entries. |
 | `wp-release changeset-tag [options]` | Create missing package release tags. |
 
-Run `npx wp-release <command> --help` for the options of each command. Directory-based commands accept a first `<source-dir>` argument or `--source-dir`, defaulting to the current directory. `sign` takes file arguments, `keygen` generates keys, and changeset commands operate on the configured repository. Every command prints its result as JSON with `--json`.
+Run `npx wp-release <command> --help` for the options of each command. Directory-based commands accept a first `<source-dir>` argument or `--source-dir`, defaulting to the current directory. `sign` and the `i18n-mo`, `i18n-json` and `i18n-php` compilers take file arguments, `keygen` generates keys, and changeset commands operate on the configured repository. Every command prints its result as JSON with `--json`.
 
 In GitHub Actions, `--github-output` writes the complete result as JSON to `steps.<id>.outputs.result` and exposes each top-level string, number or boolean as a plain output. Use `steps.zip.outputs.zipPath` for a ZIP path, for example. Arrays and objects remain in `result`: tag metadata is read with `fromJSON( steps.tag.outputs.result ).tags[0].tag`, even when only one package is selected. There is no plain `steps.tag.outputs.tag` output.
 
@@ -795,6 +800,83 @@ A deploy releases the files of the working tree, so build the packages first. On
 
 Other monorepo tools split the same way with less of the release in the config: [splitsh-lite](https://github.com/splitsh/lite), [Symplify MonorepoBuilder](https://github.com/symplify/monorepo-builder) and [`danharrin/monorepo-split-github-action`](https://github.com/danharrin/monorepo-split-github-action) push the source history of each package directory, with the packages and repositories listed in the workflow or a matrix, while `deploy-git` releases the built files on top of that history, so `vendor/` and `build/` reach Composer and WordPress installs. Like the publishers of [GoReleaser](https://goreleaser.com/), targets are lists with templates, and pre-releases skip the targets where they would replace the stable version.
 
+### WordPress internationalization
+
+`i18n-pot` extracts plugin/theme strings and writes a reproducible UTF-8 POT. `i18n-audit` reads the same source and returns findings without writing files. Both run with Node alone: no PHP, WordPress installation, database, WP-CLI or network requests. Extraction is independent of `files`, `.distignore` and Git `export-ignore` distribution rules.
+
+```sh
+wp-release i18n-pot .
+wp-release i18n-pot --package plugins/agent-pilot
+wp-release i18n-pot --all
+wp-release i18n-pot --package plugins/agent-pilot --check
+wp-release i18n-audit --package plugins/agent-pilot --json
+wp-release i18n-audit . --strict --suppress conflicting-comments
+```
+
+Config-free source directories must have plugin/theme headers. The actual main file is discovered using the package metadata reader, including plugins whose main filename differs from their slug. The selected domain defaults to `Text Domain`, then the directory name. Calls with omitted domains belong to WordPress's `default` domain; block metadata without a domain inherits the package domain. `--all-domains` explicitly combines domains. A block's explicit `textdomain` always controls its messages.
+
+`--package` selects one configured package and permits extraction-specific overrides; `--all` requires configuration and selects enabled WordPress packages only. Source directories, package selectors and `--all` are mutually exclusive. Config-free directory mode reads only its explicit options and metadata; it does not import repository config implicitly. A disabled package fails when explicitly selected. Configuration uses `i18n` at the root and on package entries, including an exact `glob` for an individual package, following the existing group model. Package entries remain non-overlapping; there is no additional package manifest configuration source.
+
+```js
+export default defineConfig( {
+	root: 'packages',
+	i18n: {
+		headers: { 'Report-Msgid-Bugs-To': 'https://example.org/issues' },
+		fileComment: `Copyright (C) Example Company
+This file is distributed under the same license as the Example plugin.`,
+	},
+	packages: [ {
+		glob: 'plugins/*',
+		i18n: {
+			include: [ '**/*.{php,js,jsx,ts,tsx,mjs,cjs}', '**/block.json', '**/theme.json' ],
+			exclude: [ '**/node_modules/**', '**/vendor/**', '**/tests/**', '**/build/**' ],
+			destination: 'languages',
+			strict: false,
+		},
+	} ],
+} );
+```
+
+Precedence is defaults, root configuration, package group/individual entry, then explicit command options. Scalars override, lists replace inherited lists, and gettext headers merge by key, case-insensitively, preserving intentionally empty values. A header set to `false` is removed, like `'Project-Id-Version': false` to keep the plugin version out of the POT so that it changes only when strings change; a later layer can set it again. `Content-Type` can't be removed, since it declares the UTF-8 charset. Options include `enabled`, `domain`, `allDomains`, `include`, `exclude`, `destination`, `headers`, `fileComment`, `references`, `strict`, `legacyGlobals` and audit `suppress`. `fileComment` adds static text above the POT header; each line is emitted as a gettext comment, and no copyright year is generated. The CLI accepts the same setting with `--file-comment`. Repeat `--include` or `--exclude` for multiple globs; these use case-sensitive [minimatch](https://github.com/isaacs/minimatch) semantics with `/` paths, `**`, brace expansion and dotfile matching, without gitignore negation or comma splitting. Default excludes cover dependency directories, dot directories, tests, minified files and generated translations. Source/build exclusions are a repository choice; this repository excludes `build`, `tools` and isolated vendors in its config.
+
+The default output is `<Domain Path>/<text-domain>.pot`, or `languages/<text-domain>.pot`. A leading `/` in `Domain Path` is package-relative, and configured destinations cannot escape the package. `--destination` changes the package-relative directory. An explicit `--output <file.pot>` resolves against the command's working directory and requires one package. All multi-package destinations are validated before writing; each completed package replaces its file atomically, independently of other packages. `--check` compares bytes without writing and fails if the POT is absent or stale. Source references are preserved by default; `--no-references` omits them. `POT-Creation-Date` and `PO-Revision-Date` default to empty values; no current date or year is inserted. Name/version headers come from metadata, and `--header NAME=VALUE` overrides any default, including with an empty value, and `--header NAME` removes the header. The POT lists the plugin or theme header strings first, then the strings of PHP, JavaScript, `block.json` and other metadata files in source order, so related strings stay together for translators. Each entry has its extracted comments, references and flags before the strings, in the usual gettext layout. The default headers come in a fixed order, and custom headers follow them. No generator header or generated copyright comment is added; set `fileComment` for a static one.
+
+#### Supported extraction syntax
+
+PHP extraction uses `php-parser` in PHP 8.3 mode, tested with attributes, enums, match expressions, promoted properties and readonly classes. Supported WordPress functions are `__`, `_e`, `_x`, `_ex`, `_n`, `_nx`, `_n_noop`, `_nx_noop`, `esc_attr__`, `esc_attr_e`, `esc_attr_x`, `esc_html__`, `esc_html_e` and `esc_html_x`. Global and explicitly global calls, namespace fallback and explicit function imports/aliases are supported. Known file-local declarations and unrelated namespaced imports are excluded; methods and static methods are never translation calls. Named arguments resolve by PHP parameter name. Literal strings, static concatenation and non-interpolated heredoc/nowdoc preserve decoded escapes, Unicode and newlines. Counts may be dynamic; IDs, contexts and selected domains must be static.
+
+JavaScript extraction uses Babel's parser and lexical scope traversal, without transforms or project Babel config. JS, JSX, TS, TSX, MJS, CJS, MTS and CTS are supported. Named imports/aliases and namespace imports from `@wordpress/i18n`, unshadowed `wp.i18n` calls and unbound canonical legacy `__`, `_x`, `_n` and `_nx` calls extract strings. `--no-legacy-globals` requires imported or `wp.i18n` bindings. Locally shadowed/reassigned imports are excluded. Static literals, templates without substitutions, concatenation and TypeScript assertions are supported. Destructured CommonJS imports, transpiled `(0, i18n.__)` forms and arbitrary minified bundles are outside the supported syntax; scan source and use explicit source/build mapping for compiled JSON.
+
+A `translators:` comment attaches to the first translation call whose containing expression or nearest statement immediately follows it. Whitespace, parsed comments and ternary branch punctuation may intervene, but unrelated statements or argument expressions may not. Comments before outer wrappers reach nested translation calls; a comment is consumed once, so unrelated sibling calls do not inherit it. Multiline comment content is preserved. WordPress plugin/theme header labels serialize as extracted comments. Bundled metadata tables follow [WordPress 6.8 block fields](https://github.com/WordPress/wordpress-develop/blob/6.8/src/wp-includes/block-i18n.json) and [theme fields](https://github.com/WordPress/wordpress-develop/blob/6.8/src/wp-includes/theme-i18n.json), including styles, variations, presets, template names and nested block settings. Their upstream data license is GPL-2.0-or-later; tables are maintained intentionally with fixtures and never fetched during generation.
+
+Invalid syntax, unreadable selected files, selected source symlinks, empty/reserved message IDs, conflicting plural definitions and output errors fail generation. Unsupported dynamic arguments warn and are fatal with `--strict`. Audit adds `placeholder-comment`, `unordered-placeholders`, `plural-placeholders`, `empty-message` and `conflicting-comments` findings; suppress these explicitly by code where justified. Placeholders support `%%`, positional indexes, numeric width/precision, padding/flags and PHP/JS sprintf conversion types. Audit checks extraction and message quality, not every untranslated user-facing string. Audit fails on errors; strict audit also fails on warnings. Failed checks return exit code `2`; unexpected I/O/option-loading errors follow the existing CLI error handling. `--json`, GitHub annotations, summaries and step outputs use the existing CLI reporting facilities.
+
+#### Compile translated catalogs
+
+Runtime formats require a translated PO, not an untranslated POT. PO updating, fuzzy matching and automatic translation are not provided. Compilation validates `Language` and `Plural-Forms`, excludes fuzzy, obsolete and untranslated entries, preserves contexts and plural forms, and never changes the input PO. An incompletely translated plural entry is excluded as a unit. Gettext parsing handles source encoding; runtime outputs use UTF-8. Each output is replaced atomically; JSON outputs are independent writes, and obsolete output files are not deleted automatically.
+
+```sh
+wp-release i18n-mo languages/my-plugin-lv.po
+wp-release i18n-php languages/my-plugin-lv.po
+wp-release i18n-json languages/my-plugin-lv.po --domain my-plugin --map scripts.json --output languages
+wp-release i18n-mo languages/my-plugin-lv.po --check
+```
+
+MO and `.l10n.php` default beside the PO, with `.mo` and `.l10n.php` extensions; `--output` selects an explicit file relative to cwd. WordPress PHP catalogs require WordPress 6.5 or later. JSON requires an explicit domain; `--output` is a directory, defaulting to the PO directory. `--check` compares proposed bytes without writing and exits `2` on absent/stale outputs. Compiler commands are primitives and do not select configured packages.
+
+A script map is a JSON object from normalized package-relative source references to arrays of normalized runtime script paths. Many source files can feed one bundle, and one source can feed several scripts. An explicit map selects only listed references; an empty target array excludes that source. Without a map, JS/MJS/CJS references use identity paths, while JSX/TypeScript references require mapping. PHP-only references do not enter JSON catalogs.
+
+```json
+{
+  "src/blocks/editor.tsx": [ "build/editor.js", "build/shared.js" ],
+  "src/components/panel.js": [ "build/editor.js" ]
+}
+```
+
+JSON filenames are `<domain>-<Language>-<md5(runtime-path)>.json`; the WordPress `default` domain uses `<Language>-<md5(runtime-path)>.json`. WordPress's `.min.js` normalization applies consistently to grouping, hashing and the JSON `source`. Jed keys preserve context through `\u0004`, plural arrays contain all translated forms, and revision dates come from the PO metadata. `.l10n.php` writes safely escaped data arrays with NUL-separated plural translations; catalog text is never treated as executable PHP.
+
+The package can be installed and used in any WordPress plugin or theme project; repository package selection is optional, and directory mode works without a wp-release config.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -946,9 +1028,24 @@ const { valid, changed, missing, extra } = await verifyChecksums( {
 
 `loadFileRules()` reads the ignore file and `--exclude` patterns into a gitignore matcher, optionally adds Git `export-ignore` paths, and `selectFiles()` lists the files it doesn't ignore. `compareChecksums()` compares two hash maps without reading any files, and `parseChecksums()` validates manifest JSON. `extractZip()` extracts a ZIP after the same checks as `deploy-svn --from-zip`.
 
+Translations:
+```js
+import { extractCatalog, auditCatalog, serializePot, generatePackagePot } from '@wpelevator/wp-release';
+
+const { catalog, diagnostics, files } = await extractCatalog( {
+	sourceDir: '/project/plugin',
+	options: { domain: 'my-plugin' },
+} );
+const findings = auditCatalog( catalog );
+const pot = serializePot( catalog );
+const result = await generatePackagePot( { sourceDir: '/project/plugin', check: true } );
+```
+
+Parsers return messages and structured diagnostics with stable codes, severity and source-relative locations. Catalog messages retain IDs, contexts, plurals, translations, translator comments, flags and structured references. `aggregateCatalog()` selects/merges a domain, unions references/comments and diagnoses plural conflicts. `resolveI18nPackages()` is the separate config adapter; extraction and serialization primitives know nothing about the repository. Library functions do not log, parse process arguments or set exit codes. Extraction results report unique files consulted, including the main plugin/theme file used for headers and header strings even when source globs exclude it. `parseTranslatedPo()`, `compileMo()`, `compileScriptTranslations()`, `compilePhpTranslations()` and `compileTranslations()` expose the same typed operations to library callers.
+
 ## Development
 
-The source is TypeScript in `src/`, with tests next to the files they test (`*.test.ts`). The published package contains only the compiled `dist/` with JavaScript and `.d.ts` files.
+The source is TypeScript in `src/`, with tests next to the files they test (`*.test.ts`). The published package contains only the compiled `dist/` with JavaScript and `.d.ts` files; tests and translation fixtures stay in the repository.
 
 ```bash
 npm run build --workspace @wpelevator/wp-release
@@ -960,6 +1057,8 @@ npm run lint --workspace @wpelevator/wp-release
 - `test` runs the `.ts` tests directly with `node --test`, using Node.js type stripping, so it needs Node.js 22.18 or later but no build. The SVN integration tests in `svn-deploy.integration.test.ts` create repositories with `svnadmin` and deploy to their `file://` URLs; they're skipped when `svn` or `svnadmin` isn't installed.
 - `lint` runs ESLint and a `tsc` type check.
 
+The i18n tests validate gettext round trips, script catalogs and generated PHP data without launching PHP, WP-CLI or WordPress, covering contexts, plural forms, comments, flags, Unicode, escaping and PHP-looking input as data.
+
 The `wpelevator-source` export condition points at `src/index.ts`. The wp-release tests and monorepo CLI scripts use it to work with the source instead of a `dist/` build. Action builds use the declared dependency's default export, which resolves to `dist/` for the workspace copy and the published package. Build wp-release before building the actions.
 
 `execute( 'deploy-svn', args, { cwd, logger, svnRunner } )` runs a single-plugin deployment or a configured plan or deployment. The optional `svnRunner` replaces the external command runner in both modes; without it, the command uses its normal runner.
@@ -968,8 +1067,8 @@ The `wpelevator-source` export condition points at `src/index.ts`. The wp-releas
 
 wp-release has two layers, so that it fits any repository layout:
 
-- **Primitives** work on the directory, file or values they're given and know nothing about the repository: `build <dir>`, `zip <dir>`, `checksums`, `sign`, `verify`, `version-check`, `deploy-git <dir>` and `deploy-svn <dir>`.
-- **The config layer** reads `wp-release.config.js` for everything about the repository: where packages are (`root` and the package globs), how their versions and tags are named (`version`, `tagFormat`), which files they ship (`files`), where they deploy (`deploy`) and the git `remote`. The changeset commands (with a single-project fallback when no config exists), `deploy-git` and `deploy-svn --release-ref`, and `build --package` and `zip --package` belong to it, and the global `--config` and `--tag-format` options select or adjust the config. `zip` and `checksums` also read caller configuration for integrity settings even without `--package`; verification reads it only when explicitly selected. Only `--release-ref` reads which package and version a ref releases. A primitive with a config mode, like `deploy-git --release-ref` beside `deploy-git <dir>` or `zip --package` beside `zip <dir>`, only takes the package directory, its files and its targets from the config there, and otherwise works the same.
+- **Primitives** work on the directory, file or values they're given and know nothing about the repository: `build <dir>`, `zip <dir>`, `checksums`, `sign`, `verify`, `version-check`, `deploy-git <dir>`, `deploy-svn <dir>`, `i18n-pot <dir>`, `i18n-audit <dir>` and the `i18n-mo`, `i18n-json` and `i18n-php` compilers.
+- **The config layer** reads `wp-release.config.js` for everything about the repository: where packages are (`root` and the package globs), how their versions and tags are named (`version`, `tagFormat`), which files they ship (`files`), how their translations are extracted (`i18n`), where they deploy (`deploy`) and the git `remote`. The changeset commands (with a single-project fallback when no config exists), `deploy-git` and `deploy-svn --release-ref`, `build --package` and `zip --package`, and `i18n-pot` and `i18n-audit` with `--package` or `--all` belong to it, and the global `--config` and `--tag-format` options select or adjust the config. `zip` and `checksums` also read caller configuration for integrity settings even without `--package`; verification reads it only when explicitly selected. Only `--release-ref` reads which package and version a ref releases. A primitive with a config mode, like `deploy-git --release-ref` beside `deploy-git <dir>` or `zip --package` beside `zip <dir>`, only takes the package directory, its files and its targets from the config there, and otherwise works the same.
 
 Configured repositories use the layout and naming conventions their config sets. Config-free changeset releases use the root-only detection and defaults described above.
 
@@ -1004,6 +1103,23 @@ The changeset release modules, from the entry point down:
 | `file-journal.ts` | `FileJournal`, which restores every file a failed `changeset-version` run changed. |
 | `versions.ts` | Version checks and SemVer precedence. |
 
+The internationalization modules in `src/i18n/`, from the entry points down:
+
+| Module | Responsibility |
+|---|---|
+| `packages.ts` | `resolveI18nPackages()`, the config adapter that selects a directory, one package or all packages and resolves their options and POT paths. |
+| `options.ts` | Validating and merging the `i18n` options of the config layers and the CLI. |
+| `generate.ts` | `extractCatalog()` and `generatePackagePot()`, which read the selected files of a package and write or check its POT. |
+| `compile.ts` | `compileTranslations()`, which compiles a translated PO into MO, script JSON or `.l10n.php` and writes or checks the outputs. |
+| `files.ts` | Selecting source files with the include and exclude globs, independently of the distribution file rules. |
+| `php.ts`, `javascript.ts` and `metadata.ts` | Parsers for PHP, JavaScript and TypeScript, and `block.json`, `theme.json` and plugin and theme headers. |
+| `extraction.ts` | The translation functions and their arguments, shared by the parsers. |
+| `catalog.ts` | Catalog types, merging messages of a domain and the diagnostics. |
+| `audit.ts` and `placeholders.ts` | Audit findings and the sprintf placeholders that they check. |
+| `pot.ts` | Serializing a catalog as a POT. |
+| `po.ts`, `translation-json.ts` and `translation-php.ts` | Parsing translated PO files and compiling MO, script JSON and `.l10n.php`. |
+| `atomic-output.ts` | Validating output paths and replacing output files atomically. |
+
 ## Comparison with existing tools
 
 | Tool | What it does | How `wp-release` differs |
@@ -1012,5 +1128,7 @@ The changeset release modules, from the entry point down:
 | [`grunt-wp-deploy`](https://github.com/stephenharris/grunt-wp-deploy) | Grunt task with `deploy_trunk` and `deploy_tag` booleans, interactive password prompts and a `Stable tag` check. | No Grunt dependency and never interactive. `--readme-only` is a separate flag, where `grunt-wp-deploy` can only update trunk with the full build. Assets are independent of trunk writes. |
 | [codeinwp theme deploy](https://github.com/codeinwp/action-wordpress-theme-deploy) | Fork of the 10up plugin action that commits themes to the themes SVN repository. | Doesn't deploy themes. Theme releases are ZIP uploads on WordPress.org; `zip` builds the upload with the theme folder as the root. |
 | [`wp dist-archive`](https://github.com/wp-cli/dist-archive-command) | WP-CLI command that zips a project using `.distignore`, with `--plugin-dirname` and `--filename-format`. | Same `.distignore` file and `{name}.{version}` style filename format, but needs only Node.js instead of PHP and WP-CLI. `.distignore` is matched with full gitignore syntax, including `!` negation, and `--distignore` / `--exclude` let you point at another ignore file or add patterns on the command line. Builds are reproducible, and `--checksums` writes a manifest next to the ZIP. |
+| [`wp i18n make-pot`](https://developer.wordpress.org/cli/commands/i18n/make-pot/) | WP-CLI command that extracts PHP, JavaScript, `block.json` and `theme.json` strings into a POT, with `--domain`, `--include`/`--exclude`, `--headers`, `--file-comment`, `--merge`/`--subtract` and audit warnings. | `i18n-pot` and `i18n-audit` need only Node.js, write byte-for-byte reproducible POTs without dates, and `--check` fails CI on a stale POT. Headers are set one at a time with a repeatable `--header NAME=VALUE` instead of a JSON object, and `--include`/`--exclude` take one glob each, so patterns never need escaping or comma splitting. `--no-references` and `--all-domains` say what they do. Monorepos keep these settings once in `wp-release.config.js` and select packages with `--package` or `--all` instead of running the command for every directory. The audit is a separate read-only command with stable finding codes for `--suppress`, instead of warnings mixed into generation. There's no `--merge`, `--subtract` or `--skip-*`; `--include` and `--exclude` cover the same needs. |
+| [`wp i18n make-mo`, `make-json` and `make-php`](https://developer.wordpress.org/cli/commands/i18n/) | WP-CLI commands that compile PO files into MO, script JSON and `.l10n.php` files. `make-json` maps sources with `--use-map` and removes JavaScript strings from the PO unless `--no-purge` is passed. | `i18n-mo`, `i18n-json` and `i18n-php` compile one translated PO at a time, never change it, and leave out fuzzy, obsolete and untranslated entries. `i18n-json` takes a many-to-many `--map` from source files to built scripts, and JSX and TypeScript sources need one, so catalogs are never written for files WordPress doesn't load. `--check` compares the outputs without writing. There's no `update-po`, so update PO files from the POT with gettext's `msgmerge` or a translation platform. |
 | [`wp plugin verify-checksums`](https://developer.wordpress.org/cli/commands/plugin/verify-checksums/) | WP-CLI command that checks installed plugins against the WordPress.org checksums API. | Reads the same manifest format, but from a file, so it also works for plugins and themes that aren't hosted on WordPress.org and for build directories in CI. `checksums` writes the manifest that WordPress.org generates for its own plugins. |
 | [`wp-scripts plugin-zip`](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts#plugin-zip) | Zips files from `package.json` `files` or a fixed allowlist, named after the npm package, with `--root-folder` / `--no-root-folder`. | Reuses the root folder flags, selects files with `.distignore` by default and can optionally honor Git `export-ignore` attributes, puts the version from the plugin headers in the filename and streams the archive instead of building it in memory. |

package/dist/changeset-config.d.ts

@@ -1,3 +1,4 @@
+import type { I18nOptions } from './i18n/options.ts';
 import type { IntegrityConfig } from './integrity.ts';
 import type { Changeset, ChangesetBump, ChangesetPackage } from './changesets.ts';
 export type PackageVersionSource = {
@@ -59,6 +60,8 @@ export interface PackageVersionConfig {
 export type PackageIdSource = 'package.json#name' | 'composer.json#name' | 'path';
 /** One directory pattern that describes packages sharing release behavior. */
 export interface ChangesetPackageGroup {
+    /** Extraction settings, independent of release file rules. */
+    i18n?: I18nOptions;
     /** Package directories to discover, relative to the configured package root. */
     glob: string;
     /** Package paths excluded from this group, relative to root. */
@@ -218,6 +221,8 @@ export interface DependentsConfig {
 }
 /** JavaScript configuration for changeset-aware releases. */
 export interface ChangesetConfig {
+    /** Extraction defaults for configured WordPress packages. */
+    i18n?: I18nOptions;
     /** Default checksum format, placement and manifest signing for ZIPs. */
     integrity?: IntegrityConfig;
     /** Branch receiving ordinary changes. */

package/dist/changeset-config.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { validateI18nOptions } from "./i18n/options.js";
 import { access } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -171,6 +172,7 @@ function validateChangesetConfig(config, configFile) {
         throw new ValidationError(`wp-release config ${configFile} must default-export a configuration object.`);
     }
     const candidate = config;
+    validateI18nOptions(candidate.i18n, `${configFile}.i18n`);
     if (!Array.isArray(candidate.packages)) {
         throw new ValidationError(`wp-release config ${configFile} must define a packages array.`);
     }
@@ -267,6 +269,7 @@ function validateChangesetConfig(config, configFile) {
                     !Array.isArray(group.version.to)))) {
             throw new ValidationError(`wp-release config ${configFile} has an invalid packages[${index}] entry.`);
         }
+        validateI18nOptions(group.i18n, `${configFile}.packages[${index}].i18n`);
         if (undefined !== group.idFrom &&
             !['path', 'package.json#name', 'composer.json#name'].includes(group.idFrom)) {
             throw new ValidationError(`wp-release config ${configFile} packages[${index}].idFrom is not supported.`);

package/dist/cli.d.ts

@@ -59,6 +59,11 @@ export declare function formatGitHubOutputs(result: unknown): string;
  * Results of the commands that can be run with execute(), by command name.
  */
 export interface CommandResults {
+    'i18n-mo': import('./i18n/compile.ts').CompileTranslationsResult;
+    'i18n-json': import('./i18n/compile.ts').CompileTranslationsResult;
+    'i18n-php': import('./i18n/compile.ts').CompileTranslationsResult;
+    'i18n-pot': import('./commands/i18n.ts').I18nCommandResult;
+    'i18n-audit': import('./commands/i18n.ts').I18nCommandResult;
     build: import('./commands/build.ts').BuildResult;
     'deploy-svn': import('./commands/deploy-svn.ts').DeploySvnResult;
     zip: ZipResult;

package/dist/cli.js

@@ -1,6 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { appendFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
+import i18nMo from "./commands/i18n-mo.js";
+import i18nJson from "./commands/i18n-json.js";
+import i18nPhp from "./commands/i18n-php.js";
+import i18nPot from "./commands/i18n-pot.js";
+import i18nAudit from "./commands/i18n-audit.js";
 import zip from "./commands/zip.js";
 import build from "./commands/build.js";
 import checksums from "./commands/checksums.js";
@@ -23,6 +28,11 @@ export const EXIT_SUCCESS = 0;
 export const EXIT_FAILURE = 1;
 export const EXIT_INVALID = 2;
 export const commands = [
+    i18nMo,
+    i18nJson,
+    i18nPhp,
+    i18nPot,
+    i18nAudit,
     build,
     zip,
     checksums,

package/dist/commands/i18n-audit.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("./command.ts").Command;
+export default _default;

package/dist/commands/i18n-audit.js

@@ -0,0 +1,2 @@
+import { createI18nCommand } from "./i18n.js";
+export default createI18nCommand('audit');

package/dist/commands/i18n-compile.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from './command.ts';
+/**
+ * Flat compiler adapters: translated PO input, independent of package/source discovery.
+ * @param format
+ */
+export declare function createI18nCompileCommand(format: 'mo' | 'json' | 'php'): Command;

package/dist/commands/i18n-compile.js

@@ -0,0 +1,76 @@
+import { resolve } from 'node:path';
+import { compileTranslations } from "../i18n/compile.js";
+import { ValidationError } from "../errors.js";
+import { readJson } from "../json-files.js";
+import { getBoolean, getString } from "./command.js";
+/**
+ * Flat compiler adapters: translated PO input, independent of package/source discovery.
+ * @param format
+ */
+export function createI18nCompileCommand(format) {
+    return {
+        name: `i18n-${format}`,
+        usage: `i18n-${format} <file.po> [options]`,
+        summary: `Compile translated PO into ${'php' === format ? 'WordPress .l10n.php' : format.toUpperCase()} files.`,
+        help: `Options:
+  --output <path>     Output file (${format === 'json' ? 'directory for JSON' : 'defaults beside the PO'})
+  --check             Compare generated bytes without writing
+${'json' === format
+            ? '  --domain <domain>   Required text domain\n  --map <file.json>   Source paths to runtime script path arrays (many-to-many)'
+            : ''}
+
+Requires Language and Plural-Forms headers. Fuzzy, obsolete and untranslated
+entries are excluded. Input PO files are never changed. No PHP/WP-CLI runtime
+is needed; compilation validates data before independent atomic output writes.`,
+        options: {
+            output: { type: 'string' },
+            check: { type: 'boolean' },
+            ...('json' === format
+                ? {
+                    domain: { type: 'string' },
+                    map: { type: 'string' },
+                }
+                : {}),
+        },
+        async run({ values, positionals, cwd, logger }) {
+            if (1 !== positionals.length || !positionals[0]?.trim()) {
+                throw new ValidationError(`i18n-${format} requires exactly one input PO file.`);
+            }
+            const output = getString(values, 'output');
+            const map = getString(values, 'map');
+            if ('' === output?.trim() || '' === map?.trim()) {
+                throw new ValidationError('--output and --map paths must not be empty.');
+            }
+            let scriptMap;
+            if (map) {
+                const parsed = await readJson(resolve(cwd, map));
+                if (!parsed ||
+                    'object' !== typeof parsed ||
+                    Array.isArray(parsed)) {
+                    throw new ValidationError('The script map must be an object of source paths to runtime path arrays.');
+                }
+                scriptMap = parsed;
+            }
+            const result = await compileTranslations({
+                sourcePath: resolve(cwd, positionals[0]),
+                format,
+                ...(output ? { outputPath: resolve(cwd, output) } : {}),
+                domain: getString(values, 'domain'),
+                scriptMap,
+                check: getBoolean(values, 'check'),
+            });
+            const stale = result.outputs.filter((outputFile) => !outputFile.current);
+            for (const outputFile of result.outputs) {
+                logger.info(outputFile.outputPath);
+            }
+            for (const outputFile of stale) {
+                logger.error('Translation output is missing or stale.', {
+                    file: outputFile.outputPath,
+                    title: 'stale-translation',
+                });
+            }
+            logger.summary(() => `### wp-release i18n-${format}\n\n${result.messages} translated messages for ${result.locale}; ${result.outputs.length} outputs.\n`);
+            return { exitCode: stale.length ? 2 : 0, result };
+        },
+    };
+}

package/dist/commands/i18n-json.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("./command.ts").Command;
+export default _default;

package/dist/commands/i18n-json.js

@@ -0,0 +1,2 @@
+import { createI18nCompileCommand } from "./i18n-compile.js";
+export default createI18nCompileCommand('json');

package/dist/commands/i18n-mo.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("./command.ts").Command;
+export default _default;

package/dist/commands/i18n-mo.js

@@ -0,0 +1,2 @@
+import { createI18nCompileCommand } from "./i18n-compile.js";
+export default createI18nCompileCommand('mo');

package/dist/commands/i18n-php.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("./command.ts").Command;
+export default _default;

package/dist/commands/i18n-php.js

@@ -0,0 +1,2 @@
+import { createI18nCompileCommand } from "./i18n-compile.js";
+export default createI18nCompileCommand('php');

package/dist/commands/i18n-pot.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("./command.ts").Command;
+export default _default;

package/dist/commands/i18n-pot.js

@@ -0,0 +1,2 @@
+import { createI18nCommand } from "./i18n.js";
+export default createI18nCommand('pot');

package/dist/commands/i18n.d.ts

@@ -0,0 +1,12 @@
+import type { PackagePotResult } from '../i18n/generate.ts';
+import type { Command } from './command.ts';
+export interface I18nCommandResult {
+    packages: Array<PackagePotResult & {
+        package?: string;
+    }>;
+}
+/**
+ * Small command adapters share selection/reporting; domain logic stays in the library.
+ * @param operation
+ */
+export declare function createI18nCommand(operation: 'pot' | 'audit'): Command;

package/dist/commands/i18n.js

@@ -0,0 +1,174 @@
+import { resolve } from 'node:path';
+import { hasFatalDiagnostics } from "../i18n/catalog.js";
+import { extractCatalog, generatePackagePot } from "../i18n/generate.js";
+import { auditCatalog } from "../i18n/audit.js";
+import { resolveI18nPackages } from "../i18n/packages.js";
+import { ValidationError } from "../errors.js";
+import { getBoolean, getString, getStrings } from "./command.js";
+function cliOptions(values) {
+    const headers = {};
+    for (const header of getStrings(values, 'header')) {
+        const index = header.indexOf('=');
+        if (0 === index || !header) {
+            throw new ValidationError('--header requires NAME=VALUE, with an empty value allowed, or NAME to remove the header.');
+        }
+        if (-1 === index) {
+            headers[header] = false;
+        }
+        else {
+            headers[header.slice(0, index)] = header.slice(index + 1);
+        }
+    }
+    const domain = getString(values, 'domain');
+    const destination = getString(values, 'destination');
+    const fileComment = getString(values, 'file-comment');
+    return {
+        ...(undefined !== domain ? { domain } : {}),
+        ...(undefined !== destination ? { destination } : {}),
+        ...(undefined !== fileComment ? { fileComment } : {}),
+        ...(values.include
+            ? { include: getStrings(values, 'include') }
+            : {}),
+        ...(values.exclude
+            ? { exclude: getStrings(values, 'exclude') }
+            : {}),
+        ...(values.suppress
+            ? { suppress: getStrings(values, 'suppress') }
+            : {}),
+        ...(getBoolean(values, 'strict') ? { strict: true } : {}),
+        ...(getBoolean(values, 'all-domains') ? { allDomains: true } : {}),
+        ...(getBoolean(values, 'no-references')
+            ? { references: false }
+            : {}),
+        ...(getBoolean(values, 'no-legacy-globals')
+            ? { legacyGlobals: false }
+            : {}),
+        ...(Object.keys(headers).length ? { headers } : {}),
+    };
+}
+function report(context, diagnostics, sourceDir) {
+    for (const diagnostic of diagnostics) {
+        context.logger[diagnostic.severity](diagnostic.message, {
+            file: resolve(sourceDir, diagnostic.file),
+            line: diagnostic.line,
+            title: diagnostic.code,
+        });
+    }
+}
+/**
+ * Small command adapters share selection/reporting; domain logic stays in the library.
+ * @param operation
+ */
+export function createI18nCommand(operation) {
+    return {
+        name: `i18n-${operation}`,
+        usage: `i18n-${operation} [<source-dir>] [options]`,
+        summary: 'pot' === operation
+            ? 'Extract WordPress source strings into a reproducible POT.'
+            : 'Audit WordPress source strings without writing files.',
+        help: `Options:
+  --package <name>       Configured package (extraction overrides allowed)
+  --all                  All enabled configured WordPress packages
+  --source-dir <dir>     Plugin/theme directory, or positional argument (default .)
+  --domain <domain>      Select one domain (default Text Domain, then slug)
+  --all-domains          Explicitly combine domains
+  --include <glob>       Repeatable source globs, replacing inherited includes
+  --exclude <glob>       Repeatable exclusion globs, replacing inherited excludes
+  --destination <dir>    Package-relative POT directory
+  --header <NAME=VALUE>  Repeatable gettext header override; NAME alone removes it
+${'pot' === operation
+            ? '  --file-comment <text>  Static comment prepended to the POT\n'
+            : ''}
+  --no-references        Omit source references
+  --no-legacy-globals    JS requires imports or wp.i18n calls
+  --strict               Warnings fail with exit code 2
+${'pot' === operation
+            ? '  --output <file.pot>    Explicit output relative to cwd; one package only\n  --check                Compare bytes without writing'
+            : '  --suppress <code>      Repeatable audit finding codes to suppress'}
+
+No PHP, WordPress, WP-CLI or network needed. Distribution file rules do not apply.
+Each package writes atomically; a multi-package run is not a transaction.`,
+        options: {
+            package: { type: 'string' },
+            all: { type: 'boolean' },
+            'source-dir': { type: 'string' },
+            domain: { type: 'string' },
+            'all-domains': { type: 'boolean' },
+            include: { type: 'string', multiple: true },
+            exclude: { type: 'string', multiple: true },
+            destination: { type: 'string' },
+            header: { type: 'string', multiple: true },
+            'no-references': { type: 'boolean' },
+            'no-legacy-globals': { type: 'boolean' },
+            strict: { type: 'boolean' },
+            ...('pot' === operation
+                ? {
+                    'file-comment': { type: 'string' },
+                    output: { type: 'string' },
+                    check: { type: 'boolean' },
+                }
+                : { suppress: { type: 'string', multiple: true } }),
+        },
+        async run(context) {
+            const { values, positionals, cwd, configFile, logger } = context;
+            if (positionals.length > 1 ||
+                (positionals.length && undefined !== values['source-dir'])) {
+                throw new ValidationError('Pass only one source directory.');
+            }
+            const source = getString(values, 'source-dir');
+            if (undefined !== source && !source.trim()) {
+                throw new ValidationError('--source-dir must not be empty.');
+            }
+            const output = getString(values, 'output');
+            if (undefined !== output && !output.trim()) {
+                throw new ValidationError('--output must not be empty.');
+            }
+            const selected = await resolveI18nPackages({
+                cwd,
+                configFile,
+                package: getString(values, 'package'),
+                all: getBoolean(values, 'all'),
+                sourceDir: getString(values, 'source-dir') ?? positionals[0],
+                options: cliOptions(values),
+                validateOutputs: 'pot' === operation,
+                ...(output ? { outputPath: resolve(cwd, output) } : {}),
+            });
+            const result = { packages: [] };
+            let failed = false;
+            for (const pkg of selected) {
+                let generated;
+                if ('pot' === operation) {
+                    generated = await generatePackagePot({
+                        ...pkg,
+                        check: getBoolean(values, 'check'),
+                    });
+                }
+                else {
+                    const extracted = await extractCatalog(pkg);
+                    generated = {
+                        outputPath: pkg.outputPath,
+                        messages: extracted.catalog.messages.length,
+                        files: extracted.files,
+                        diagnostics: [
+                            ...extracted.diagnostics,
+                            ...auditCatalog(extracted.catalog, pkg.options.suppress),
+                        ],
+                        written: false,
+                        current: false,
+                    };
+                }
+                result.packages.push({
+                    ...generated,
+                    ...(pkg.package ? { package: pkg.package } : {}),
+                });
+                failed ||= hasFatalDiagnostics(generated.diagnostics, pkg.options.strict);
+                report(context, generated.diagnostics, pkg.sourceDir);
+                logger.info(`${pkg.package ?? pkg.sourceDir}: ${generated.messages} messages, ${generated.files} files.`);
+            }
+            logger.summary(() => `### wp-release i18n-${operation}\n\n${result.packages
+                .map((pkg) => `- ${pkg.package ?? pkg.outputPath}: ${pkg.messages} messages, ${pkg.diagnostics.length} diagnostics.`)
+                .join('\n')}\n`);
+            return { exitCode: failed ? 2 : 0, result };
+        },
+    };
+}