claude-plugin-wordpress-manager 1.5.0 → 1.7.1

package/skills/wp-i18n/references/php-i18n.md

@@ -0,0 +1,196 @@
+# PHP Internationalization
+
+Use this file when internationalizing PHP code in WordPress plugins and themes.
+
+## Core translation functions
+
+### Simple strings
+
+```php
+// Return translated string
+$text = __('Hello World', 'my-text-domain');
+
+// Echo translated string
+_e('Hello World', 'my-text-domain');
+```
+
+### Strings with context
+
+```php
+// "Post" as a verb vs noun
+$verb = _x('Post', 'verb', 'my-text-domain');
+$noun = _x('Post', 'noun', 'my-text-domain');
+
+// Echo version
+_ex('Post', 'verb', 'my-text-domain');
+```
+
+### Strings with variables
+
+```php
+// Single placeholder
+$text = sprintf(
+    /* translators: %s: user display name */
+    __('Welcome, %s!', 'my-text-domain'),
+    $user->display_name
+);
+
+// Multiple placeholders (use numbered)
+$text = sprintf(
+    /* translators: 1: product name, 2: price */
+    __('%1$s costs %2$s', 'my-text-domain'),
+    $product_name,
+    $price
+);
+```
+
+### Plurals
+
+```php
+$text = sprintf(
+    /* translators: %d: number of items */
+    _n('%d item', '%d items', $count, 'my-text-domain'),
+    $count
+);
+
+// With context
+$text = sprintf(
+    _nx('%d post', '%d posts', $count, 'blog posts', 'my-text-domain'),
+    $count
+);
+```
+
+## Escaping functions
+
+Always use escaping variants when outputting to HTML:
+
+```php
+// Escape for HTML content
+echo esc_html__('Safe text', 'my-text-domain');
+esc_html_e('Safe text', 'my-text-domain');
+
+// Escape for HTML attributes
+echo esc_attr__('attribute value', 'my-text-domain');
+esc_attr_e('attribute value', 'my-text-domain');
+
+// With context
+echo esc_html_x('Post', 'verb', 'my-text-domain');
+```
+
+### When to use which
+
+| Context | Function |
+|---------|----------|
+| HTML content | `esc_html__()` / `esc_html_e()` |
+| HTML attributes | `esc_attr__()` / `esc_attr_e()` |
+| URLs | `esc_url()` around `__()` |
+| JavaScript strings | `esc_js()` around `__()` |
+| Already-safe internal use | `__()` / `_e()` |
+
+## Text domain loading
+
+### Plugins
+
+```php
+add_action('init', function() {
+    load_plugin_textdomain(
+        'my-text-domain',
+        false,
+        dirname(plugin_basename(__FILE__)) . '/languages'
+    );
+});
+```
+
+### Themes
+
+```php
+add_action('after_setup_theme', function() {
+    load_theme_textdomain(
+        'my-text-domain',
+        get_template_directory() . '/languages'
+    );
+});
+
+// Child theme
+add_action('after_setup_theme', function() {
+    load_child_theme_textdomain(
+        'my-child-domain',
+        get_stylesheet_directory() . '/languages'
+    );
+});
+```
+
+### WordPress 6.7+ (automatic loading)
+
+Since WordPress 6.7, translation files placed in `wp-content/languages/plugins/` or `wp-content/languages/themes/` are loaded automatically. Manual `load_plugin_textdomain()` is still recommended as a fallback.
+
+## Common mistakes
+
+### Do NOT concatenate translatable strings
+
+```php
+// WRONG — translators cannot reorder
+__('There are ' . $count . ' items', 'my-text-domain');
+
+// CORRECT
+sprintf(__('There are %d items', 'my-text-domain'), $count);
+```
+
+### Do NOT use variables as text domain
+
+```php
+// WRONG — tools cannot extract
+__('Hello', $domain);
+
+// CORRECT — literal string only
+__('Hello', 'my-text-domain');
+```
+
+### Do NOT translate HTML
+
+```php
+// WRONG — HTML in translatable string
+__('<strong>Warning:</strong> This is dangerous', 'my-text-domain');
+
+// CORRECT — separate HTML from text
+'<strong>' . esc_html__('Warning:', 'my-text-domain') . '</strong> '
+    . esc_html__('This is dangerous', 'my-text-domain');
+```
+
+### Do NOT split sentences
+
+```php
+// WRONG — sentence split across calls
+__('Click ', 'my-text-domain') . '<a>' . __('here', 'my-text-domain') . '</a>';
+
+// CORRECT — full sentence with placeholder
+sprintf(
+    /* translators: %s: link HTML */
+    __('Click %s for details', 'my-text-domain'),
+    '<a href="...">' . esc_html__('here', 'my-text-domain') . '</a>'
+);
+```
+
+## Translator comments
+
+Add context for translators with `/* translators: */` comments:
+
+```php
+/* translators: %s: date in ISO 8601 format */
+sprintf(__('Published on %s', 'my-text-domain'), $date);
+
+/* translators: 1: opening link tag, 2: closing link tag */
+sprintf(__('Read the %1$sfull article%2$s', 'my-text-domain'), '<a href="...">', '</a>');
+```
+
+These comments must appear on the line immediately before the translation function call.
+
+## Verification
+
+```bash
+# Check for missing text domains
+wp i18n make-pot . languages/my-text-domain.pot --slug=my-text-domain
+
+# Audit for untranslated strings
+grep -rn "echo \"\|echo '" --include="*.php" | grep -v "__\|_e\|esc_"
+```

package/skills/wp-i18n/references/rtl-support.md

@@ -0,0 +1,206 @@
+# RTL (Right-to-Left) Support
+
+Use this file when adding right-to-left language support to WordPress themes and plugins.
+
+## RTL languages
+
+Arabic (`ar`), Hebrew (`he`), Persian/Farsi (`fa`), Urdu (`ur`), Pashto (`ps`), Sindhi (`sd`), Kurdish (Sorani) (`ckb`), Uyghur (`ug`), Divehi (`dv`).
+
+## How WordPress handles RTL
+
+WordPress automatically:
+1. Sets `dir="rtl"` on `<html>` when the locale is RTL
+2. Adds `class="rtl"` to `<body>`
+3. Loads `*-rtl.css` stylesheets (if they exist) instead of `*.css`
+
+Check direction in PHP:
+```php
+if (is_rtl()) {
+    // RTL-specific logic
+}
+```
+
+Check in JavaScript:
+```js
+const isRtl = document.documentElement.dir === 'rtl';
+// or
+const isRtl = document.body.classList.contains('rtl');
+```
+
+## CSS approach: Logical properties (recommended)
+
+Modern CSS logical properties handle both LTR and RTL automatically:
+
+```css
+/* AVOID physical properties */
+.card {
+    margin-left: 20px;      /* LTR only */
+    padding-right: 10px;    /* LTR only */
+    text-align: left;       /* LTR only */
+    float: left;            /* LTR only */
+    border-left: 1px solid; /* LTR only */
+}
+
+/* USE logical properties */
+.card {
+    margin-inline-start: 20px;     /* left in LTR, right in RTL */
+    padding-inline-end: 10px;      /* right in LTR, left in RTL */
+    text-align: start;             /* left in LTR, right in RTL */
+    float: inline-start;           /* left in LTR, right in RTL */
+    border-inline-start: 1px solid; /* left in LTR, right in RTL */
+}
+```
+
+### Logical property mapping
+
+| Physical | Logical | LTR | RTL |
+|----------|---------|-----|-----|
+| `left` | `inline-start` | left | right |
+| `right` | `inline-end` | right | left |
+| `margin-left` | `margin-inline-start` | margin-left | margin-right |
+| `margin-right` | `margin-inline-end` | margin-right | margin-left |
+| `padding-left` | `padding-inline-start` | padding-left | padding-right |
+| `padding-right` | `padding-inline-end` | padding-right | padding-left |
+| `border-left` | `border-inline-start` | border-left | border-right |
+| `text-align: left` | `text-align: start` | left | right |
+| `float: left` | `float: inline-start` | left | right |
+
+### Shorthand
+
+```css
+/* Physical: top right bottom left */
+margin: 10px 20px 10px 0;
+
+/* Logical */
+margin-block: 10px;         /* top and bottom */
+margin-inline: 0 20px;      /* start and end */
+```
+
+## CSS approach: RTL stylesheets (legacy)
+
+### Automatic RTL generation
+
+```bash
+# Generate RTL stylesheets with rtlcss
+npx rtlcss style.css style-rtl.css
+
+# Watch mode
+npx rtlcss -w src/style.css dist/style-rtl.css
+```
+
+### rtlcss directives
+
+Control flipping with comments:
+
+```css
+/* rtl:ignore — skip this rule */
+.icon-arrow {
+    /* rtl:ignore */
+    transform: rotate(45deg);
+}
+
+/* rtl:remove — remove this rule in RTL */
+.ltr-only {
+    /* rtl:remove */
+    float: left;
+}
+
+/* rtl:raw — insert raw CSS in RTL */
+.custom {
+    /* rtl:raw:
+    float: right;
+    */
+}
+```
+
+### Enqueuing RTL stylesheets
+
+WordPress handles this automatically when you enqueue properly:
+
+```php
+wp_enqueue_style('my-style', plugins_url('css/style.css', __FILE__));
+// WordPress will automatically load css/style-rtl.css in RTL contexts
+// IF the RTL file exists in the same directory
+```
+
+For custom paths:
+```php
+wp_style_add_data('my-style', 'rtl', 'replace');
+// WordPress will load style-rtl.css instead of style.css
+```
+
+Or add an independent RTL stylesheet:
+```php
+wp_style_add_data('my-style', 'rtl', plugin_dir_url(__FILE__) . 'css/custom-rtl.css');
+```
+
+## Block editor RTL support
+
+### Block styles
+
+```css
+/* Use logical properties in block stylesheets */
+.wp-block-my-plugin-card {
+    padding-inline-start: 1rem;
+    border-inline-start: 3px solid var(--wp--preset--color--primary);
+}
+```
+
+### useBlockProps and direction
+
+```js
+import { useBlockProps } from '@wordpress/block-editor';
+
+export default function Edit() {
+    const blockProps = useBlockProps();
+    // blockProps automatically inherits the document direction
+    return <div {...blockProps}>Content</div>;
+}
+```
+
+## Icons and directional elements
+
+Flip directional icons in RTL:
+
+```css
+/* Arrows, chevrons, navigation icons */
+.rtl .icon-arrow-right {
+    transform: scaleX(-1);
+}
+
+/* Or with logical approach */
+[dir="rtl"] .icon-next {
+    transform: scaleX(-1);
+}
+```
+
+Do NOT flip:
+- Clocks (always clockwise)
+- Media playback controls (play/pause universal)
+- Checkmarks
+- Phone icons
+- Logos and brand marks
+
+## Testing RTL
+
+```bash
+# Switch site to Arabic
+wp site switch-language ar
+
+# Switch back to English
+wp site switch-language en_US
+```
+
+Quick browser test: add `dir="rtl"` to `<html>` in DevTools.
+
+WordPress admin: Settings → General → Site Language → Arabic (or any RTL language).
+
+## Verification checklist
+
+- [ ] All CSS uses logical properties (or RTL stylesheets exist)
+- [ ] No hardcoded `left`/`right` in positioning
+- [ ] Directional icons flip correctly
+- [ ] Text alignment uses `start`/`end` not `left`/`right`
+- [ ] Flexbox/Grid layout respects direction
+- [ ] RTL stylesheets are properly enqueued with `wp_style_add_data`
+- [ ] Tested with at least one RTL locale (Arabic recommended)

package/skills/wp-i18n/references/translation-workflow.md

@@ -0,0 +1,178 @@
+# Translation Workflow
+
+Use this file when managing the .pot/.po/.mo translation file lifecycle.
+
+## File types
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `.pot` | Template — master list of all translatable strings | Portable Object Template |
+| `.po` | Translation — human-editable translations for a locale | Portable Object |
+| `.mo` | Compiled — binary version loaded by PHP at runtime | Machine Object |
+| `.json` | JS translations — JED format for `@wordpress/i18n` | JSON |
+
+## Directory structure
+
+```
+my-plugin/
+├── languages/
+│   ├── my-text-domain.pot              # Template
+│   ├── my-text-domain-it_IT.po         # Italian translations
+│   ├── my-text-domain-it_IT.mo         # Compiled Italian
+│   ├── my-text-domain-it_IT-{hash}.json  # JS Italian translations
+│   └── my-text-domain-de_DE.po         # German translations
+```
+
+Naming convention: `{text-domain}-{locale}.{ext}`
+
+Common locales: `it_IT`, `de_DE`, `fr_FR`, `es_ES`, `pt_BR`, `ja`, `zh_CN`, `ar`
+
+## Step 1: Generate POT file
+
+```bash
+# From plugin root
+wp i18n make-pot . languages/my-text-domain.pot
+
+# With options
+wp i18n make-pot . languages/my-text-domain.pot \
+    --slug=my-plugin \
+    --domain=my-text-domain \
+    --include="src/,includes/" \
+    --exclude="node_modules/,vendor/,tests/" \
+    --headers='{"Report-Msgid-Bugs-To":"https://github.com/user/repo/issues"}'
+```
+
+The `make-pot` command scans:
+- PHP files for `__()`, `_e()`, `esc_html__()`, etc.
+- JS/JSX files for `@wordpress/i18n` calls
+- `block.json` files for translatable fields (title, description, keywords)
+
+## Step 2: Create/update PO files
+
+### From scratch
+
+```bash
+# Create a new PO file for Italian
+msginit --input=languages/my-text-domain.pot \
+        --output-file=languages/my-text-domain-it_IT.po \
+        --locale=it_IT
+```
+
+### Update existing PO with new strings
+
+```bash
+# Merge new POT into existing PO (preserves existing translations)
+wp i18n update-po languages/my-text-domain.pot languages/
+```
+
+Or with `msgmerge`:
+```bash
+msgmerge --update languages/my-text-domain-it_IT.po languages/my-text-domain.pot
+```
+
+## Step 3: Translate
+
+### Using a PO editor
+
+Recommended tools:
+- **Poedit** (desktop, free + pro) — the standard tool
+- **GlotPress** (web-based, used by WordPress.org)
+- **Loco Translate** (WordPress plugin, in-dashboard editing)
+
+### PO file format
+
+```po
+#: src/includes/class-main.php:42
+#. translators: %s: site name
+msgid "Welcome to %s"
+msgstr "Benvenuto su %s"
+
+#: src/includes/class-main.php:55
+msgid "Save Changes"
+msgstr "Salva Modifiche"
+
+#: src/includes/class-main.php:60
+msgctxt "verb"
+msgid "Post"
+msgstr "Pubblica"
+
+#: src/includes/class-main.php:70
+msgid "%d item"
+msgid_plural "%d items"
+msgstr[0] "%d elemento"
+msgstr[1] "%d elementi"
+```
+
+## Step 4: Compile MO files
+
+```bash
+# Compile all PO files to MO
+wp i18n make-mo languages/
+
+# Or with msgfmt
+msgfmt languages/my-text-domain-it_IT.po -o languages/my-text-domain-it_IT.mo
+```
+
+## Step 5: Generate JSON for JavaScript
+
+```bash
+# Generate JSON from PO files (for wp_set_script_translations)
+wp i18n make-json languages/ --no-purge
+```
+
+`--no-purge` keeps the JS strings in the PO file (useful if you also use them server-side).
+
+## Automation: Build script integration
+
+### package.json
+
+```json
+{
+    "scripts": {
+        "i18n:pot": "wp i18n make-pot . languages/my-text-domain.pot --exclude=node_modules/,vendor/",
+        "i18n:update": "wp i18n update-po languages/my-text-domain.pot languages/",
+        "i18n:mo": "wp i18n make-mo languages/",
+        "i18n:json": "wp i18n make-json languages/ --no-purge",
+        "i18n:build": "npm run i18n:pot && npm run i18n:update && npm run i18n:mo && npm run i18n:json"
+    }
+}
+```
+
+### Pre-release checklist
+
+1. Run `wp i18n make-pot` to capture all new strings
+2. Run `wp i18n update-po` to merge into existing translations
+3. Send updated PO files to translators
+4. Compile MO files after translations are complete
+5. Generate JSON files for JS strings
+6. Test each locale by switching `WPLANG` in `wp-config.php`
+
+## WordPress.org translation (GlotPress)
+
+For plugins/themes hosted on WordPress.org:
+1. Set `Text Domain` and `Domain Path` in the plugin header
+2. Upload the POT file to SVN `trunk/languages/`
+3. Translations are crowdsourced via translate.wordpress.org
+4. Users receive translations automatically via WordPress updates
+
+Plugin header:
+```php
+/**
+ * Plugin Name: My Plugin
+ * Text Domain: my-text-domain
+ * Domain Path: /languages
+ */
+```
+
+## Verification
+
+```bash
+# Check PO file for errors
+msgfmt --check languages/my-text-domain-it_IT.po
+
+# Count translated/untranslated strings
+msgfmt --statistics languages/my-text-domain-it_IT.po
+
+# Verify text domain consistency
+grep -rn "__('" --include="*.php" src/ | grep -v "'my-text-domain'"
+```