claude-plugin-wordpress-manager 1.4.0 → 1.7.0

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'"
+```

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

@@ -0,0 +1,177 @@
+# WP-CLI i18n Commands
+
+Use this file when working with WP-CLI's `i18n` command group for translation management.
+
+## Prerequisites
+
+```bash
+# WP-CLI i18n is built-in since WP-CLI 2.0
+wp i18n --help
+
+# If missing, install the i18n command package
+wp package install wp-cli/i18n-command
+```
+
+## make-pot — Generate POT template
+
+```bash
+# Basic usage (from plugin/theme root)
+wp i18n make-pot . languages/my-text-domain.pot
+
+# Full options
+wp i18n make-pot . languages/my-text-domain.pot \
+    --slug=my-plugin \
+    --domain=my-text-domain \
+    --include="src/,includes/,templates/" \
+    --exclude="node_modules/,vendor/,tests/,build/" \
+    --skip-js \
+    --skip-php \
+    --skip-block-json \
+    --skip-theme-json \
+    --skip-audit \
+    --headers='{"Report-Msgid-Bugs-To":"support@example.com","Last-Translator":"Dev Team"}' \
+    --file-comment="Copyright (c) 2026 My Company"
+```
+
+### Key options
+
+| Option | Purpose |
+|--------|---------|
+| `--domain=<domain>` | Only extract strings with this text domain |
+| `--include=<paths>` | Comma-separated list of directories to scan |
+| `--exclude=<paths>` | Comma-separated list of directories to skip |
+| `--skip-js` | Skip JavaScript file scanning |
+| `--skip-php` | Skip PHP file scanning |
+| `--skip-block-json` | Skip block.json translation extraction |
+| `--skip-theme-json` | Skip theme.json translation extraction |
+| `--skip-audit` | Skip string auditing (faster, no warnings) |
+| `--headers` | JSON object of PO headers |
+
+### What it scans
+
+- PHP: `__()`, `_e()`, `_x()`, `_ex()`, `_n()`, `_nx()`, `esc_html__()`, `esc_html_e()`, `esc_attr__()`, `esc_attr_e()`, `esc_html_x()`, `esc_attr_x()`
+- JS: `@wordpress/i18n` functions via static analysis
+- block.json: `title`, `description`, `keywords`, `styles[].label`, `variations[].title`
+- theme.json: Custom template names, style variation names
+
+## update-po — Merge new strings into PO files
+
+```bash
+# Update all PO files in the directory
+wp i18n update-po languages/my-text-domain.pot languages/
+
+# Update a specific PO file
+wp i18n update-po languages/my-text-domain.pot languages/my-text-domain-it_IT.po
+```
+
+This is equivalent to `msgmerge --update` but integrated into WP-CLI. Preserves existing translations and marks removed strings as obsolete.
+
+## make-mo — Compile PO to MO
+
+```bash
+# Compile all PO files in directory
+wp i18n make-mo languages/
+
+# Compile a specific file
+wp i18n make-mo languages/my-text-domain-it_IT.po
+```
+
+## make-json — Generate JS translation files
+
+```bash
+# Generate JSON files for all PO files
+wp i18n make-json languages/
+
+# Keep JS strings in PO files (don't purge)
+wp i18n make-json languages/ --no-purge
+
+# Pretty-print JSON output
+wp i18n make-json languages/ --pretty-print
+```
+
+Output: `{text-domain}-{locale}-{md5}.json` where `{md5}` is the hash of the relative JS file path.
+
+### When to use `--no-purge`
+
+- Use `--no-purge` if strings appear in both PHP and JS files
+- Without it, JS-only strings are removed from PO, breaking PHP translations if shared
+
+## make-php — Generate PHP translation files (WP 6.5+)
+
+```bash
+# Convert PO files to PHP format
+wp i18n make-php languages/
+```
+
+PHP translation files load faster than MO files. WordPress 6.5+ supports this format natively.
+
+## Complete workflow example
+
+```bash
+# 1. Generate fresh POT
+wp i18n make-pot . languages/my-text-domain.pot \
+    --exclude="node_modules/,vendor/"
+
+# 2. Update existing translations
+wp i18n update-po languages/my-text-domain.pot languages/
+
+# 3. (Translate the PO files — manual or via Poedit)
+
+# 4. Compile MO files
+wp i18n make-mo languages/
+
+# 5. Generate JSON for JavaScript
+wp i18n make-json languages/ --no-purge
+
+# 6. (Optional) Generate PHP translations
+wp i18n make-php languages/
+```
+
+## Audit strings
+
+The `make-pot` command includes a string auditor. Common warnings:
+
+| Warning | Meaning |
+|---------|---------|
+| `Mismatched placeholders` | Printf placeholders differ between singular/plural |
+| `Multiple text domains` | File mixes text domains |
+| `Missing translator comment` | Placeholder string without `/* translators: */` |
+
+Run the audit explicitly:
+```bash
+wp i18n make-pot . /dev/null --skip-js
+# Warnings are printed to stderr
+```
+
+## Language management
+
+```bash
+# Install a language pack for core
+wp language core install it_IT
+
+# Set site language
+wp site switch-language it_IT
+
+# List installed languages
+wp language core list --status=installed
+
+# Install plugin language pack
+wp language plugin install my-plugin it_IT
+
+# Install theme language pack
+wp language theme install my-theme it_IT
+```
+
+## Verification
+
+```bash
+# Verify POT is up to date (compare counts)
+wp i18n make-pot . /tmp/fresh.pot --quiet
+diff <(grep -c "^msgid" languages/my-text-domain.pot) <(grep -c "^msgid" /tmp/fresh.pot)
+
+# Check MO files are current (MO should be newer than PO)
+find languages/ -name "*.po" -newer languages/*.mo
+
+# Verify JSON files exist for JS translations
+ls languages/*.json
+```

package/skills/wp-i18n/scripts/i18n_inspect.mjs

@@ -0,0 +1,330 @@
+/**
+ * i18n_inspect.mjs — Detect internationalization setup in a WordPress project.
+ *
+ * Scans for text domain, .pot/.po/.mo files, i18n function usage,
+ * and WP-CLI i18n availability.
+ * Outputs a JSON report to stdout.
+ *
+ * Usage:
+ *   node i18n_inspect.mjs [--cwd=/path/to/check]
+ *
+ * Exit codes:
+ *   0 — i18n setup detected
+ *   1 — no i18n setup detected
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execSync } from "node:child_process";
+
+const TOOL_VERSION = "1.0.0";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function statSafe(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+function readFileSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJsonSafe(p) {
+  const raw = readFileSafe(p);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function execSafe(cmd, cwd, timeoutMs = 5000) {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout: timeoutMs, cwd, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readdirSafe(dir) {
+  try {
+    return fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parse --cwd argument
+// ---------------------------------------------------------------------------
+
+function parseCwd() {
+  const cwdArg = process.argv.find((a) => a.startsWith("--cwd="));
+  return cwdArg ? cwdArg.slice(6) : process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// Detect text domain
+// ---------------------------------------------------------------------------
+
+function detectTextDomain(cwd) {
+  const result = { found: false, domain: null, source: null };
+
+  // Check plugin header
+  const phpFiles = readdirSafe(cwd).filter((f) => f.endsWith(".php"));
+  for (const file of phpFiles) {
+    const content = readFileSafe(path.join(cwd, file));
+    if (!content) continue;
+
+    const domainMatch = content.match(/Text\s*Domain:\s*(\S+)/i);
+    if (domainMatch) {
+      result.found = true;
+      result.domain = domainMatch[1];
+      result.source = file;
+      return result;
+    }
+  }
+
+  // Check style.css (theme)
+  const styleContent = readFileSafe(path.join(cwd, "style.css"));
+  if (styleContent) {
+    const domainMatch = styleContent.match(/Text\s*Domain:\s*(\S+)/i);
+    if (domainMatch) {
+      result.found = true;
+      result.domain = domainMatch[1];
+      result.source = "style.css";
+      return result;
+    }
+  }
+
+  // Check block.json files
+  const blockJson = readJsonSafe(path.join(cwd, "block.json"));
+  if (blockJson?.textdomain) {
+    result.found = true;
+    result.domain = blockJson.textdomain;
+    result.source = "block.json";
+    return result;
+  }
+
+  const srcBlockJson = readJsonSafe(path.join(cwd, "src", "block.json"));
+  if (srcBlockJson?.textdomain) {
+    result.found = true;
+    result.domain = srcBlockJson.textdomain;
+    result.source = "src/block.json";
+    return result;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect translation files
+// ---------------------------------------------------------------------------
+
+function detectTranslationFiles(cwd) {
+  const result = { languagesDir: null, pot: [], po: [], mo: [], json: [] };
+
+  const langDirs = ["languages", "lang", "i18n"];
+  for (const dir of langDirs) {
+    const full = path.join(cwd, dir);
+    if (statSafe(full)?.isDirectory()) {
+      result.languagesDir = dir;
+      break;
+    }
+  }
+
+  if (!result.languagesDir) return result;
+
+  const files = readdirSafe(path.join(cwd, result.languagesDir));
+  for (const file of files) {
+    if (file.endsWith(".pot")) result.pot.push(file);
+    else if (file.endsWith(".po")) result.po.push(file);
+    else if (file.endsWith(".mo")) result.mo.push(file);
+    else if (file.endsWith(".json") && !file.startsWith(".")) result.json.push(file);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect i18n function usage
+// ---------------------------------------------------------------------------
+
+function detectI18nUsage(cwd) {
+  const result = { php: { detected: false, functions: {} }, js: { detected: false, functions: {} } };
+
+  // PHP i18n functions
+  const phpFunctions = ["__", "_e", "_x", "_ex", "_n", "_nx", "esc_html__", "esc_html_e", "esc_attr__", "esc_attr_e"];
+  const phpPattern = phpFunctions.map((f) => f.replace(/_/g, "_")).join("|");
+  const phpCount = execSafe(
+    `grep -rl --include="*.php" -E "(${phpPattern})\\s*\\(" . 2>/dev/null | wc -l`,
+    cwd
+  );
+
+  if (phpCount && parseInt(phpCount) > 0) {
+    result.php.detected = true;
+
+    // Count per function
+    for (const func of phpFunctions) {
+      const count = execSafe(
+        `grep -r --include="*.php" -c "${func}(" . 2>/dev/null | awk -F: '{s+=$2} END {print s}'`,
+        cwd
+      );
+      if (count && parseInt(count) > 0) {
+        result.php.functions[func] = parseInt(count);
+      }
+    }
+  }
+
+  // JS i18n functions (@wordpress/i18n)
+  const jsCount = execSafe(
+    `grep -rl --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" "@wordpress/i18n" . 2>/dev/null | wc -l`,
+    cwd
+  );
+
+  if (jsCount && parseInt(jsCount) > 0) {
+    result.js.detected = true;
+  }
+
+  // Also check for import
+  const jsImportCount = execSafe(
+    `grep -rl --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" "from '@wordpress/i18n'" . 2>/dev/null | wc -l`,
+    cwd
+  );
+  if (jsImportCount && parseInt(jsImportCount) > 0) {
+    result.js.detected = true;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Detect Domain Path header
+// ---------------------------------------------------------------------------
+
+function detectDomainPath(cwd) {
+  const phpFiles = readdirSafe(cwd).filter((f) => f.endsWith(".php"));
+  for (const file of phpFiles) {
+    const content = readFileSafe(path.join(cwd, file));
+    if (!content) continue;
+    const match = content.match(/Domain\s*Path:\s*(\S+)/i);
+    if (match) return match[1];
+  }
+
+  const styleContent = readFileSafe(path.join(cwd, "style.css"));
+  if (styleContent) {
+    const match = styleContent.match(/Domain\s*Path:\s*(\S+)/i);
+    if (match) return match[1];
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Detect load_textdomain calls
+// ---------------------------------------------------------------------------
+
+function detectTextdomainLoading(cwd) {
+  const functions = [
+    "load_plugin_textdomain",
+    "load_theme_textdomain",
+    "load_child_theme_textdomain",
+    "wp_set_script_translations",
+  ];
+
+  const detected = [];
+  for (const func of functions) {
+    const found = execSafe(
+      `grep -rl --include="*.php" "${func}" . 2>/dev/null | head -1`,
+      cwd
+    );
+    if (found) detected.push(func);
+  }
+
+  return detected;
+}
+
+// ---------------------------------------------------------------------------
+// Check WP-CLI i18n availability
+// ---------------------------------------------------------------------------
+
+function checkWpCliI18n(cwd) {
+  const wpCli = execSafe("command -v wp", cwd);
+  if (!wpCli) return { available: false };
+
+  const i18nHelp = execSafe("wp i18n --help 2>/dev/null", cwd);
+  return { available: !!i18nHelp };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwd = parseCwd();
+
+  if (!statSafe(cwd)?.isDirectory()) {
+    console.error(`Error: directory not found: ${cwd}`);
+    process.exit(1);
+  }
+
+  const textDomain = detectTextDomain(cwd);
+  const translationFiles = detectTranslationFiles(cwd);
+  const i18nUsage = detectI18nUsage(cwd);
+  const domainPath = detectDomainPath(cwd);
+  const textdomainLoading = detectTextdomainLoading(cwd);
+  const wpCliI18n = checkWpCliI18n(cwd);
+
+  const detected = textDomain.found || i18nUsage.php.detected || i18nUsage.js.detected || translationFiles.pot.length > 0;
+
+  const report = {
+    tool: "i18n_inspect",
+    version: TOOL_VERSION,
+    cwd,
+    detected,
+    textDomain,
+    domainPath,
+    textdomainLoading,
+    translationFiles,
+    i18nUsage,
+    wpCliI18n,
+    recommendations: [],
+  };
+
+  // Recommendations
+  if (!textDomain.found && (i18nUsage.php.detected || i18nUsage.js.detected)) {
+    report.recommendations.push("i18n functions used but no Text Domain header found. Add 'Text Domain:' to plugin/theme header.");
+  }
+  if (textDomain.found && translationFiles.pot.length === 0) {
+    report.recommendations.push("Text domain set but no .pot file found. Run: wp i18n make-pot . languages/" + textDomain.domain + ".pot");
+  }
+  if (translationFiles.po.length > 0 && translationFiles.mo.length === 0) {
+    report.recommendations.push("PO files found but no compiled MO files. Run: wp i18n make-mo languages/");
+  }
+  if (i18nUsage.js.detected && translationFiles.json.length === 0) {
+    report.recommendations.push("JS i18n detected but no JSON translation files. Run: wp i18n make-json languages/ --no-purge");
+  }
+  if (textDomain.found && textdomainLoading.length === 0) {
+    report.recommendations.push("Text domain found but no load_plugin_textdomain/load_theme_textdomain call detected.");
+  }
+  if (!domainPath && textDomain.found) {
+    report.recommendations.push("Consider adding 'Domain Path: /languages' to the plugin/theme header.");
+  }
+
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(detected ? 0 : 1);
+}
+
+main();

package/skills/wp-interactivity-api/SKILL.md

@@ -179,3 +179,7 @@ See `references/debugging.md`.
   - `references/server-side-rendering.md`
   - `references/directives-quickref.md`
   - `references/debugging.md`
+
+## Related skills
+
+- `wp-accessibility` — ARIA for interactive components, keyboard navigation, focus management, screen reader testing