From 46da408fc88f901838dfb9af221b2b881cbd4619 Mon Sep 17 00:00:00 2001 From: Dennis Ploetner Date: Wed, 22 Oct 2025 12:10:12 +0200 Subject: [PATCH] Documentation added --- AGENTS.md | 19 +++++++++++++++++ README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9a7d11d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# Repository Guidelines + +## Project Structure & Module Organization +Source code lives under `src/`, with `ComposerPlugin.php` bootstrapping the Composer integration and the `Commands/` directory holding the WP-CLI subcommands (`MakePotCommand`, `MakeJsonCommand`, etc.). Shared helpers such as `ShellRunner.php` and `I18nConfig.php` sit at the root of `src/` for reuse. Tests live in `tests/Commands` and mirror the command class names. Composer metadata (`composer.json`, `phpstan.neon.dist`, `phpunit.xml.dist`) resides at the project root; avoid editing `vendor/` manually. + +## Build, Test, and Development Commands +Run `composer install` after cloning to pull dependencies and register the plugin. Use `composer qa` for the quick pre-flight check (PHPCS with WPCS ruleset plus PHPStan level 10). Execute `composer tests` for the PHPUnit suite, and `composer tests:coverage` when you need HTML coverage output in `tests/coverage/`. Fix formatting automatically with `composer cs:fix`. + +## Coding Style & Naming Conventions +We target PHP 7.4+ and follow PSR-4 autoloading (`lloc\ComposerI18nScripts\` namespace). Adopt the WordPress Coding Standards with four-space indentation, snake_case function names when calling WP APIs, and StudlyCase class names that end with `Command` for WP-CLI handlers. Mirror class names in file names, and keep configuration arrays ordered consistently to aid PHPStan. Before committing, run `composer cs` to confirm a clean lint baseline. + +## Testing Guidelines +Cover new functionality with PHPUnit tests under `tests/Commands`, using the `*Test` suffix. When introducing a command or helper, add the companion test class and describe edge cases. Prefer data providers for repetitive scenarios and assert exit codes plus generated file paths. Run `composer tests` before pushing; if you alter CLI output or file generation, assert on the rendered strings or fixtures. Keep the coverage directory out of version control. + +## Commit & Pull Request Guidelines +Commit messages are short, present-tense imperatives (`Add MakePot command`, `Raise PHPStan level`). Squash noisy fix-ups locally. Each pull request should include a concise summary, linked GitHub issues (`Fixes #123`), notable commands you ran, and screenshots or sample output when altering CLI behaviour. Mention whether documentation in `README.md` or this guide needs updates. + +## Localization Workflow Tips +Command classes convert translation templates into multiple formats; leverage existing helpers (`ShellRunner`) instead of spawning custom shell logic. When adding options, document them in the command’s PHPDoc and update related tests to cover both WP-CLI arguments and generated artifacts. Validate that generated `.pot` and `.json` files respect WordPress locale conventions to keep downstream usage smooth. diff --git a/README.md b/README.md index 0e1e6e0..07a4775 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,63 @@ # Composer i18n Scripts -Simplify the internationalization of your WordPress plugin or theme using WP-CLI — powered by Composer. +Automate the internationalization workflow of your WordPress plugin or theme by wiring WP-CLI translation tools into familiar Composer commands. +## Requirements +- PHP 7.4+ and Composer 2.6+ (Composer plugin API 2.6 is required) +- WP-CLI 2.12+ available on your `$PATH` +- A WordPress plugin or theme with `Text Domain` and `Domain Path` headers defined + +## Installation +```bash +composer require --dev lloc/composer-i18n-scripts +``` +Composer automatically registers the plugin; no manual bootstrap code is needed. Running `composer install` on the project will keep the plugin active for all contributors. + +## Configuration +The plugin inspects your project root to infer settings: +- Themes: reads `style.css` +- Plugins: reads the main plugin file (matching the directory name or `index.php`) + +Provide headers like the following so WP-CLI receives the right text domain and language directory: +```php +/* +Plugin Name: Sample Plugin +Text Domain: sample-plugin +Domain Path: /languages +*/ +``` +If no metadata is found, defaults are `Text Domain: messages` and `Domain Path: /languages`. + +## Usage +Run the commands from the WordPress project root so that `wp` can load your environment. + +| Command | Purpose | +| ------- | ------- | +| `composer i18n:make-pot` | Scan the source directory and generate `languages/.pot`. | +| `composer i18n:create-po ` | Copy the `.pot` file to a locale-specific `.po` file (e.g. `de_DE`). | +| `composer i18n:update-po` | Merge the current `.pot` changes into every `.po` in `languages/`. | +| `composer i18n:make-mo` | Compile all `.po` files into `.mo` binaries. | +| `composer i18n:make-php` | Export `.po` translations into PHP array files for performance-sensitive setups. | +| `composer i18n:make-json` | Build JavaScript translation catalogs (`*.json`) without purging existing assets. | + +Example workflow: +```bash +composer i18n:make-pot +composer i18n:update-po +composer i18n:make-json +composer i18n:make-mo +``` + +## Development +- `composer install` – install dependencies and register the plugin +- `composer qa` – PHPCS (WordPress Coding Standards) + PHPStan level 10 +- `composer tests` – run PHPUnit suite under `tests/Commands` +- `composer tests:coverage` – generate HTML coverage in `tests/coverage/` +- `composer cs:fix` – automatically fix style violations + +Refer to `AGENTS.md` for contributor conventions, coding standards, and pull request expectations. + +## Troubleshooting +- **“Text domain is not set”**: ensure your plugin/theme headers declare `Text Domain` and `Domain Path`. +- **WP-CLI not found**: verify `wp` is installed globally or provide an absolute path (e.g. symlink `wp` into `/usr/local/bin`). +- **Translations not picking up new strings**: rerun `composer i18n:make-pot` before updating `.po` files so the template is up to date.