Repository navigation
Add generate-pot: the POT file from WP-CLI, and whether a string changed #25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
cbbdcb7
Add generate-pot: the POT file from WP-CLI, and whether a string changed
larodiel f4e7cde
generate-pot downloads and checks wp-cli with the shared phar helper
larodiel 70e75a6
generate-pot ignores the stamped fields in the POT header entry only
larodiel 9dd8c13
generate-pot makes the .distignore and submodule exclusions relative …
larodiel 256c64b
generate-pot keeps a .distignore rule that starts with a wildcard as …
larodiel f064f63
generate-pot says make-pot matches every exclusion at any depth, a le…
larodiel File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| # generate-pot | ||
|
|
||
| Generates a plugin's POT file with `wp i18n make-pot`, and says whether its strings changed. | ||
|
|
||
| ```yaml | ||
| - uses: actions/checkout@v6 | ||
| with: | ||
| persist-credentials: false | ||
|
|
||
| # PHP has to be on the runner: wp-cli runs on it. | ||
| - uses: shivammathur/setup-php@v2 | ||
| with: | ||
| php-version: '8.2' | ||
| coverage: none | ||
|
|
||
| - id: pot | ||
| uses: stellarwp/plugin-toolbox/.github/actions/generate-pot@v1 | ||
| with: | ||
| pot-path: lang/my-plugin.pot | ||
|
|
||
| - if: steps.pot.outputs.changed == 'yes' | ||
| run: echo "Commit ${{ steps.pot.outputs.pot-path }} and push it to translation here." | ||
| ``` | ||
|
|
||
| Build the assets first when the plugin ships compiled JavaScript with strings in it. The action | ||
| writes the POT and commits nothing. | ||
|
|
||
| ## What it runs | ||
|
|
||
| ``` | ||
| wp i18n make-pot <source-path> <pot-path> --skip-audit [--domain=…] [--headers=…] [--exclude=…] | ||
| ``` | ||
|
|
||
| wp-cli is release 2.12.0, pinned in [`generate-pot.js`](generate-pot.js) with its sha512. The phar | ||
| is downloaded into the runner's temp directory, never the checkout, and checked before it runs. A | ||
| phar that does not match is deleted and the step fails. A later step of the same job reuses the | ||
| download, and checks it again. | ||
|
|
||
| ## What is left out | ||
|
|
||
| Three lists are joined into `--exclude`, each entry once: | ||
|
|
||
| - The lines of `.distignore`, when the checkout has one: what the zip leaves out is not translated. | ||
| Empty lines and `#` comments are skipped. | ||
| - The path of each git submodule, read from `.gitmodules`. A submodule has its own text domain and | ||
| its own POT, and its strings do not belong in this one. | ||
| - The lines of the `exclude` input, passed as given. | ||
|
|
||
| make-pot matches an exclusion against paths relative to `source-path`, so the `.distignore` and | ||
| submodule paths are made relative to it first: with `source-path: src`, `src/admin` becomes | ||
| `admin`, and a path outside `src`, such as `/tests`, is dropped. A `.distignore` line with no `/` | ||
| in it, such as `node_modules`, is a name that matches at any depth, and is kept as it is, and so is | ||
| a line whose first part holds a `*`, such as `**/private/*.php`. | ||
|
|
||
| make-pot matches every exclusion at any depth, and drops a leading `/`: `/src/admin/` with | ||
| `source-path: src` becomes `admin`, which also leaves out `src/modules/admin/`, and `/tests` with | ||
| `source-path: .` also leaves out `src/tests/`. No `--exclude` value matches only at the top of the | ||
| scanned directory. When a directory deeper in the source has the same name as one `.distignore` | ||
| leaves out, rename one of them or narrow `source-path`. | ||
|
|
||
| With none of them, make-pot uses its own defaults. | ||
|
|
||
| ```yaml | ||
| - uses: stellarwp/plugin-toolbox/.github/actions/generate-pot@v1 | ||
| with: | ||
| pot-path: languages/my-plugin.pot | ||
| domain: my-plugin | ||
| headers: '{"Report-Msgid-Bugs-To": "https://example.com/support", "Last-Translator": "", "Language-Team": ""}' | ||
| exclude: | | ||
| *.js.map | ||
| src/**/*.js | ||
| ``` | ||
|
|
||
| ## The changed check | ||
|
|
||
| make-pot stamps the time (`POT-Creation-Date`), the plugin version (`Project-Id-Version`) and its | ||
| own version (`X-Generator`) on every run, so the file differs each time even with the same strings. | ||
| The check leaves out these three lines of the header entry only: a translation entry that holds one | ||
| of the names is compared like any other. | ||
|
|
||
| | The POT | `changed` | The file | | ||
| |---|---|---| | ||
| | is not tracked by git: a new POT | `yes` | kept | | ||
| | differs from the tracked one in anything else | `yes` | kept | | ||
| | differs in those three header lines only, or not at all | `no` | put back with `git checkout` | | ||
|
|
||
| A second run therefore leaves nothing to commit. The check needs a git checkout, at any depth. | ||
|
|
||
| ## Inputs | ||
|
|
||
| | Input | Default | | | ||
| |---|---|---| | ||
| | `pot-path` | required | Where the POT is written, relative to the checkout, e.g. `lang/my-plugin.pot`. | | ||
| | `source-path` | `.` | The directory scanned for strings, relative to the checkout. | | ||
| | `domain` | | The text domain, passed as `--domain`. Empty leaves it to make-pot. | | ||
| | `headers` | | POT headers to set, as a JSON object of strings in a string. Empty sets none. | | ||
| | `exclude` | | Extra exclusions, one per line, relative to `source-path`, added to `.distignore` and the submodule paths. | | ||
| | `working-directory` | | Where the repository is checked out. Empty is the workspace. | | ||
|
|
||
| ## Outputs | ||
|
|
||
| | Output | | | ||
| |---|---| | ||
| | `pot-path` | The POT, relative to the checkout, as given. | | ||
| | `changed` | `yes` when the POT is new or its strings changed, `no` otherwise. | | ||
|
|
||
| ## How it runs | ||
|
|
||
| The logic is in [`generate-pot.js`](generate-pot.js), run by `actions/github-script`, so there is | ||
| no dependency to install and nothing to build. It needs `php`, `curl` and `git` on the runner. | ||
|
|
||
| Run its tests locally: `npm install` once in the toolbox, then | ||
| `node --test tests/actions/generate-pot/generate-pot.test.js`. They stand in for the download and | ||
| for wp-cli, and run the changed check against a real git repository. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # Generates a plugin's POT file with `wp i18n make-pot`, and says whether its strings changed, so a | ||
| # caller commits and pushes a POT only when there is something new to translate. It writes the POT | ||
| # and commits nothing. | ||
| # | ||
| # The logic lives in generate-pot.js, run by actions/github-script, so there is no dependency to | ||
| # install and nothing to build. wp-cli is a pinned release, downloaded into the runner's temp | ||
| # directory and checked against its sha512 before it runs on the runner's PHP. | ||
| name: Generate POT | ||
| description: Generates the POT file of a plugin with wp-cli and says whether its strings changed | ||
|
|
||
| inputs: | ||
| pot-path: | ||
| description: >- | ||
| Where the POT is written, relative to the checkout, e.g. `lang/the-events-calendar.pot` or | ||
| `languages/give.pot`. Empty, absolute or outside the checkout fails before anything runs. | ||
| required: true | ||
| source-path: | ||
| description: 'The directory scanned for strings, relative to the checkout.' | ||
| required: false | ||
| default: '.' | ||
| domain: | ||
| description: >- | ||
| The text domain to extract, passed as `--domain`. Empty leaves it to make-pot, which reads the | ||
| `Text Domain` header of the plugin, or uses the directory name. | ||
| required: false | ||
| default: '' | ||
| headers: | ||
| description: >- | ||
| POT headers to set, as a JSON object of strings in a string, passed as `--headers`, e.g. | ||
| `'{"Report-Msgid-Bugs-To": "https://example.com/support"}'`. Anything else fails before | ||
| anything runs. Empty sets none. | ||
| required: false | ||
| default: '' | ||
| exclude: | ||
| description: >- | ||
| Extra files and directories to leave out, one per line, as `--exclude` takes them: relative to | ||
| `source-path`, e.g. `*.js.map`. They are added to the lines of `.distignore` and the git | ||
| submodule paths, which are always left out once made relative to `source-path`; the ones | ||
| outside it are dropped. | ||
| required: false | ||
| default: '' | ||
| working-directory: | ||
| description: >- | ||
| Where the repository is checked out, relative to the workspace or absolute. Empty is the | ||
| workspace. A directory that is not there fails before anything runs. | ||
| required: false | ||
| default: '' | ||
|
|
||
| outputs: | ||
| pot-path: | ||
| description: 'The POT, relative to the checkout, as given.' | ||
| value: ${{ steps.pot.outputs.pot-path }} | ||
| changed: | ||
| description: >- | ||
| `yes` when the POT is new or its strings changed. `no` when the POT git tracks differs only in | ||
| the `POT-Creation-Date`, `Project-Id-Version` and `X-Generator` headers, or not at all; the | ||
| file is then put back as it was. | ||
| value: ${{ steps.pot.outputs.changed }} | ||
|
|
||
| runs: | ||
| using: 'composite' | ||
| steps: | ||
| - name: Generate the POT and check whether the strings changed | ||
| id: pot | ||
| uses: actions/github-script@v9 | ||
| env: | ||
| # github-script's require() resolves against the workspace of the repository being built, | ||
| # not this action's directory, so the path has to be passed in. github.action_path is the | ||
| # documented expression for it. | ||
| ACTION_PATH: ${{ github.action_path }} | ||
| # Read from process.env rather than interpolated into the script, so an input is data and | ||
| # never part of the program. | ||
| INPUT_POT_PATH: ${{ inputs.pot-path }} | ||
| INPUT_SOURCE_PATH: ${{ inputs.source-path }} | ||
| INPUT_DOMAIN: ${{ inputs.domain }} | ||
| INPUT_HEADERS: ${{ inputs.headers }} | ||
| INPUT_EXCLUDE: ${{ inputs.exclude }} | ||
| INPUT_WORKING_DIRECTORY: ${{ inputs.working-directory }} | ||
| with: | ||
| script: | | ||
| const { runGeneratePot } = require(`${process.env.ACTION_PATH}/generate-pot.js`) | ||
| await runGeneratePot({ core, exec, env: process.env }) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Qualify the narrower source-path workaround.
If wanted strings exist in both
src/modules/adminandsrc/public, narrowingsource-pathtosrc/modulesomits the latter from the POT. The action scans only the selected source directory. (raw.githubusercontent.com)State that this workaround is safe only when all wanted strings are inside the narrower directory.