claude-plugin-wordpress-manager 1.5.0 → 1.7.1

package/skills/wp-i18n/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: wp-i18n
+description: "Use when internationalizing WordPress plugins or themes: PHP gettext functions (__/esc_html__/etc.), JavaScript i18n (@wordpress/i18n), .pot/.po/.mo translation workflow, WP-CLI i18n commands, RTL stylesheet support, and multilingual plugin setup (Polylang/WPML)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. WP-CLI required for i18n make-pot/make-json."
+version: 1.0.0
+source: "vinmor/wordpress-manager"
+---
+
+# WP i18n
+
+## When to use
+
+- Adding internationalization (i18n) to a WordPress plugin or theme
+- Preparing a plugin or theme for WordPress.org submission (i18n is required)
+- Generating `.pot` template files from source code
+- Adding JavaScript translations via `@wordpress/i18n`
+- Supporting right-to-left (RTL) languages such as Arabic, Hebrew, or Persian
+- Setting up a multilingual WordPress site with Polylang or WPML
+
+## Inputs required
+
+- **Repo root** — path to the plugin or theme project directory
+- **Text domain** — the unique slug used in all gettext calls (matches the plugin/theme slug)
+- **Project kind** — `plugin` or `theme` (determines how text domain is loaded)
+- **Target languages** — locale codes for translations (e.g., `it_IT`, `de_DE`, `ar`)
+- **Whether JS translation is needed** — true if the project has JavaScript files with user-facing strings
+
+## Procedure
+
+### 0) Detect i18n status
+
+Run the detection script to assess the current state of internationalization:
+
+```bash
+node skills/wp-i18n/scripts/i18n_inspect.mjs --cwd=/path/to/project
+node skills/wp-project-triage/scripts/detect_wp_project.mjs
+```
+
+The i18n inspection script outputs JSON with:
+- `textDomain` — the text domain declared in the plugin/theme header
+- `phpI18n` — count and distribution of PHP gettext function usage
+- `jsI18n` — whether `@wordpress/i18n` is installed and configured
+- `translationFiles` — existing .pot, .po, .mo, and .json files
+- `issues[]` — problems found with severity and suggested fixes
+
+If the project has no i18n at all, start from step 1. If partial i18n exists, jump to the step that addresses the gaps.
+
+### 1) PHP internationalization
+
+Wrap all user-facing strings in PHP files with the appropriate gettext function:
+
+| Function | Use case |
+|----------|----------|
+| `__('text', 'domain')` | Return translated string |
+| `_e('text', 'domain')` | Echo translated string |
+| `esc_html__('text', 'domain')` | Return translated + HTML-escaped |
+| `esc_html_e('text', 'domain')` | Echo translated + HTML-escaped |
+| `esc_attr__('text', 'domain')` | Return translated + attribute-escaped |
+| `_n('single', 'plural', $count, 'domain')` | Pluralization |
+| `_x('text', 'context', 'domain')` | Disambiguation context |
+| `sprintf(__('Hello %s', 'domain'), $name)` | Variable substitution |
+
+Key rules:
+- The text domain **must** match the `Text Domain:` header in the main plugin file or `style.css`
+- Never pass variables as the first argument — strings must be literal for extraction
+- Use `sprintf()` / `printf()` for dynamic content, never string concatenation
+- Load the text domain: `load_plugin_textdomain()` on `init` or `load_theme_textdomain()` on `after_setup_theme`
+
+Read: `references/php-i18n.md`
+
+### 2) JavaScript internationalization
+
+For JavaScript files with user-facing strings, use `@wordpress/i18n`:
+
+```js
+import { __, _n, _x, sprintf } from '@wordpress/i18n';
+const label = __('Save Changes', 'my-plugin');
+```
+
+Setup requires:
+1. Add `@wordpress/i18n` as a dependency (or use `wp-scripts` which includes it)
+2. Register script translations in PHP via `wp_set_script_translations()`
+3. Generate JSON translation files from `.po` files via `wp i18n make-json`
+4. For blocks, set the `textdomain` field in `block.json`
+
+Read: `references/js-i18n.md`
+
+### 3) Translation file workflow
+
+The WordPress translation pipeline has four file types:
+
+1. **`.pot`** — Template with all extractable strings (generated, never edited manually)
+2. **`.po`** — Per-locale translations (human-edited or via Poedit/GlotPress)
+3. **`.mo`** — Compiled binary for PHP runtime (generated from `.po`)
+4. **`.json`** — Compiled translations for JavaScript (generated from `.po`)
+
+File naming: `{text-domain}-{locale}.{po|mo}` (e.g., `my-plugin-it_IT.po`)
+
+Workflow: extract → `.pot` → create/update `.po` → compile `.mo` + `.json`
+
+Read: `references/translation-workflow.md`
+
+### 4) WP-CLI i18n commands
+
+```bash
+wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
+wp i18n make-json languages/ --no-purge
+wp i18n make-mo languages/
+wp i18n update-po languages/my-plugin.pot languages/
+```
+
+Integrate into `package.json`:
+```json
+{
+  "scripts": {
+    "i18n:pot": "wp i18n make-pot . languages/my-plugin.pot",
+    "i18n:json": "wp i18n make-json languages/ --no-purge",
+    "i18n:mo": "wp i18n make-mo languages/",
+    "i18n:build": "npm run i18n:pot && npm run i18n:mo && npm run i18n:json"
+  }
+}
+```
+
+Read: `references/wpcli-i18n.md`
+
+### 5) RTL support
+
+WordPress auto-loads `style-rtl.css` when the locale is RTL:
+- Use CSS logical properties (`margin-inline-start` vs `margin-left`)
+- Use `@wordpress/scripts` with `rtlcss` to auto-generate RTL stylesheets
+- Use `is_rtl()` in PHP for conditional logic
+- Test with an RTL locale (Arabic `ar` or Hebrew `he_IL`)
+
+Read: `references/rtl-support.md`
+
+### 6) Multilingual site setup
+
+For content translation (not just UI strings):
+- **Polylang** (free) — `pll_register_string()`, `pll__()`, `pll_e()`
+- **WPML** (paid) — `wpml-config.xml` for custom post types and taxonomies
+- Both require hreflang tags and a language switcher
+
+Read: `references/multilingual-setup.md`
+
+## Verification
+
+- `.pot` file generates without errors: `wp i18n make-pot . languages/<domain>.pot`
+- Translations load in the UI: switch locale and confirm translated strings
+- RTL renders correctly: switch to Arabic and check layout
+- Text domain matches: `Text Domain:` header matches domain in all gettext calls
+- JS translations work: `wp.i18n.__()` returns translated strings in browser console
+- No untranslated strings: search for hardcoded user-facing strings
+
+Re-run: `node skills/wp-i18n/scripts/i18n_inspect.mjs --cwd=/path`
+
+## Failure modes / debugging
+
+- **Translations not loading** — `load_plugin_textdomain()` missing or called on wrong hook; `languages/` path incorrect
+- **Wrong text domain** — domain in gettext calls must exactly match `Text Domain:` header
+- **JS translations missing** — `wp_set_script_translations()` must be called after `wp_enqueue_script()`; JSON files must exist with correct handle-based naming
+- **`.mo` not found** — file must follow `{domain}-{locale}.mo` naming convention
+- **Plural forms broken** — verify `Plural-Forms` header in `.po` matches target language
+- **`make-pot` misses strings** — strings with variables or concatenation cannot be extracted; refactor to literals with `sprintf()`
+- **RTL layout broken** — hardcoded `left`/`right` in CSS; use logical properties or `rtlcss`
+
+## Escalation
+
+- WordPress i18n Handbook: https://developer.wordpress.org/plugins/internationalization/
+- CLDR Plural Rules: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+- Translator Handbook: https://make.wordpress.org/polyglots/handbook/

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

@@ -0,0 +1,201 @@
+# JavaScript Internationalization
+
+Use this file when internationalizing JavaScript code in WordPress blocks, plugins, and themes.
+
+## @wordpress/i18n package
+
+### Installation
+
+```bash
+npm install @wordpress/i18n
+```
+
+### Core functions
+
+```js
+import { __, _x, _n, _nx, sprintf } from '@wordpress/i18n';
+
+// Simple translation
+const label = __('Save', 'my-text-domain');
+
+// With context
+const post = _x('Post', 'verb', 'my-text-domain');
+
+// Plurals
+const message = sprintf(
+    _n('%d item', '%d items', count, 'my-text-domain'),
+    count
+);
+
+// Plurals with context
+const posts = sprintf(
+    _nx('%d post', '%d posts', count, 'blog posts', 'my-text-domain'),
+    count
+);
+```
+
+### sprintf for variable substitution
+
+```js
+import { __, sprintf } from '@wordpress/i18n';
+
+// Positional placeholders
+const text = sprintf(
+    /* translators: 1: product name, 2: price */
+    __('%1$s costs %2$s', 'my-text-domain'),
+    productName,
+    price
+);
+
+// %s placeholder
+const greeting = sprintf(
+    /* translators: %s: user name */
+    __('Hello, %s!', 'my-text-domain'),
+    userName
+);
+```
+
+## Block editor (Gutenberg) usage
+
+### Block registration
+
+```js
+import { registerBlockType } from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+
+registerBlockType('my-plugin/my-block', {
+    title: __('My Block', 'my-text-domain'),
+    description: __('A custom block.', 'my-text-domain'),
+    keywords: [
+        __('example', 'my-text-domain'),
+        __('custom', 'my-text-domain'),
+    ],
+    // ...
+});
+```
+
+### InspectorControls
+
+```js
+import { InspectorControls } from '@wordpress/block-editor';
+import { PanelBody, ToggleControl } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+<InspectorControls>
+    <PanelBody title={__('Settings', 'my-text-domain')}>
+        <ToggleControl
+            label={__('Show title', 'my-text-domain')}
+            help={__('Toggle the title visibility.', 'my-text-domain')}
+            checked={showTitle}
+            onChange={(val) => setAttributes({ showTitle: val })}
+        />
+    </PanelBody>
+</InspectorControls>
+```
+
+## Translation file loading
+
+### For blocks (block.json method — recommended)
+
+```json
+{
+    "name": "my-plugin/my-block",
+    "title": "My Block",
+    "textdomain": "my-text-domain"
+}
+```
+
+WordPress automatically loads translation files for blocks with `textdomain` in `block.json`.
+
+### For non-block scripts
+
+Register script translations in PHP:
+
+```php
+add_action('init', function() {
+    wp_set_script_translations(
+        'my-script-handle',    // Same handle used in wp_register_script
+        'my-text-domain',
+        plugin_dir_path(__FILE__) . 'languages'
+    );
+});
+```
+
+### Translation file format
+
+JS translations use JSON (JED format). Generated by WP-CLI:
+
+```bash
+wp i18n make-json languages/ --no-purge
+```
+
+Output files: `my-text-domain-{locale}-{md5hash}.json`
+
+## block.json translatable fields
+
+These fields are automatically translated when `textdomain` is set:
+
+```json
+{
+    "title": "My Block",
+    "description": "Block description here.",
+    "keywords": ["example", "demo"],
+    "styles": [
+        { "name": "default", "label": "Default" },
+        { "name": "fancy", "label": "Fancy" }
+    ],
+    "variations": [
+        {
+            "name": "wide",
+            "title": "Wide",
+            "description": "Wide layout variation."
+        }
+    ],
+    "textdomain": "my-text-domain"
+}
+```
+
+## Common mistakes
+
+### Do NOT use template literals for translation keys
+
+```js
+// WRONG — extraction tools cannot parse
+const text = __(`Hello ${name}`, 'my-text-domain');
+
+// CORRECT
+const text = sprintf(__('Hello %s', 'my-text-domain'), name);
+```
+
+### Do NOT use dynamic text domains
+
+```js
+// WRONG
+const text = __(message, domain);
+
+// CORRECT — literal string only
+const text = __('Hello', 'my-text-domain');
+```
+
+### Do NOT concatenate inside translation calls
+
+```js
+// WRONG
+const text = __('Total: ' + count + ' items', 'my-text-domain');
+
+// CORRECT
+const text = sprintf(__('Total: %d items', 'my-text-domain'), count);
+```
+
+## Verification
+
+```bash
+# Generate POT from JS files
+wp i18n make-pot . languages/my-text-domain.pot --include="src/**/*.js,src/**/*.jsx"
+
+# Generate JSON translation files
+wp i18n make-json languages/ --no-purge
+
+# Check for untranslated strings in JS
+grep -rn "['\"]\`" --include="*.js" --include="*.jsx" src/ | grep -v "__\|_x\|_n\|sprintf"
+```

package/skills/wp-i18n/references/multilingual-setup.md

@@ -0,0 +1,219 @@
+# Multilingual Setup
+
+Use this file when configuring WordPress for multilingual content delivery.
+
+## Plugin-based solutions
+
+### WPML (commercial)
+
+Most widely used. Supports posts, pages, custom post types, taxonomies, strings, menus, and widgets.
+
+```php
+// Check if WPML is active
+if (defined('ICL_SITEPRESS_VERSION')) {
+    // WPML-specific code
+}
+
+// Get current language
+$current_lang = apply_filters('wpml_current_language', null);
+
+// Get element translation
+$translated_id = apply_filters('wpml_object_id', $post_id, 'post', true, 'it');
+
+// Switch language in a template
+do_action('wpml_switch_lang', 'it');
+// ... output Italian content
+do_action('wpml_switch_lang', null); // reset
+```
+
+Theme/plugin compatibility header:
+```php
+/**
+ * Plugin Name: My Plugin
+ * WPML Compatible: yes
+ */
+```
+
+### Polylang (free + pro)
+
+```php
+// Check if Polylang is active
+if (function_exists('pll_current_language')) {
+    $lang = pll_current_language();
+}
+
+// Get translated post ID
+$translated_id = pll_get_post($post_id, 'it');
+
+// Get translated term ID
+$translated_term = pll_get_term($term_id, 'it');
+
+// Register a string for translation
+pll_register_string('my-string-name', 'Default text', 'My Plugin');
+
+// Get translated string
+$text = pll__('Default text');
+// or echo
+pll_e('Default text');
+```
+
+### TranslatePress (visual)
+
+Frontend visual editing — translates directly on the page.
+
+```php
+// Check if TranslatePress is active
+if (class_exists('TRP_Translate_Press')) {
+    // TranslatePress-specific code
+}
+```
+
+## URL structure options
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| Subdirectories | `example.com/it/` | Simple, single domain | Shared hosting limits |
+| Subdomains | `it.example.com` | Separate analytics | DNS setup required |
+| Domains | `example.it` | Best for SEO by country | Multiple SSL certs |
+| URL parameter | `example.com?lang=it` | Easiest setup | Worst for SEO |
+
+Recommended: **subdirectories** for most projects.
+
+## Making plugins translation-compatible
+
+### String registration (WPML)
+
+```php
+// Register admin strings
+add_action('init', function() {
+    if (function_exists('icl_register_string')) {
+        icl_register_string('my-plugin', 'CTA Button Text', get_option('my_cta_text'));
+    }
+});
+
+// Retrieve translated string
+function get_my_cta_text() {
+    $text = get_option('my_cta_text');
+    if (function_exists('icl_t')) {
+        return icl_t('my-plugin', 'CTA Button Text', $text);
+    }
+    return $text;
+}
+```
+
+### wpml-config.xml
+
+Required for WPML to know which custom fields and options to translate:
+
+```xml
+<wpml-config>
+    <custom-fields>
+        <custom-field action="translate">subtitle</custom-field>
+        <custom-field action="copy">price</custom-field>
+        <custom-field action="ignore">internal_notes</custom-field>
+    </custom-fields>
+    <admin-texts>
+        <key name="my_plugin_options">
+            <key name="cta_text" />
+            <key name="footer_text" />
+        </key>
+    </admin-texts>
+    <custom-types>
+        <custom-type translate="1">product</custom-type>
+    </custom-types>
+    <taxonomies>
+        <taxonomy translate="1">product_category</taxonomy>
+    </taxonomies>
+</wpml-config>
+```
+
+Place at plugin or theme root. WPML reads it automatically.
+
+## Multilingual REST API
+
+### WPML
+
+```bash
+# Get posts in Italian
+curl "https://site.com/wp-json/wp/v2/posts?lang=it"
+
+# Requires WPML REST API addon or custom filter
+```
+
+### Polylang
+
+```bash
+# Polylang adds ?lang= support to REST API
+curl "https://site.com/wp-json/wp/v2/posts?lang=it"
+```
+
+### Custom REST language filtering
+
+```php
+add_filter('rest_post_query', function($args, $request) {
+    $lang = $request->get_param('lang');
+    if ($lang && function_exists('pll_current_language')) {
+        $args['lang'] = $lang;
+    }
+    return $args;
+}, 10, 2);
+```
+
+## hreflang tags
+
+Essential for SEO — tells search engines which language version to show:
+
+```php
+add_action('wp_head', function() {
+    // WPML handles this automatically
+    // For custom implementations:
+    $languages = [
+        'en' => 'https://example.com/page/',
+        'it' => 'https://example.com/it/pagina/',
+        'de' => 'https://example.com/de/seite/',
+    ];
+    foreach ($languages as $lang => $url) {
+        printf('<link rel="alternate" hreflang="%s" href="%s" />' . "\n",
+            esc_attr($lang), esc_url($url));
+    }
+    // x-default for language selector/default page
+    printf('<link rel="alternate" hreflang="x-default" href="%s" />' . "\n",
+        esc_url($languages['en']));
+});
+```
+
+## WooCommerce multilingual
+
+### WPML + WooCommerce Multilingual
+
+- Synchronizes products, variations, attributes across languages
+- Multi-currency support
+- Translated emails and checkout
+
+```php
+// Get translated product ID
+$translated_product_id = apply_filters('wpml_object_id', $product_id, 'product', true, 'it');
+
+// Get price in current currency
+// Handled automatically by WooCommerce Multilingual
+```
+
+### Polylang + Hyyan WooCommerce Polylang Integration
+
+Free alternative. Syncs stock, prices, and product data.
+
+## Verification
+
+```bash
+# Check hreflang tags
+curl -s https://site.com/ | grep -i "hreflang"
+
+# Verify language switcher works
+curl -s -o /dev/null -w "%{http_code}" https://site.com/it/
+
+# Check WPML config file exists (for WPML-compatible plugins)
+ls wpml-config.xml
+
+# Verify translated content exists
+wp post list --lang=it --post_type=page --fields=ID,post_title
+```