npm - claude-plugin-wordpress-manager - Versions diffs - 2.2.1 → 2.3.0 - Mend

claude-plugin-wordpress-manager 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/skills/wp-multilang-network/references/hreflang-config.md ADDED Viewed

@@ -0,0 +1,198 @@
+# Hreflang Configuration
+Use this file when implementing hreflang tags across a WordPress Multisite network — tag format, mu-plugin auto-generation, validation tools, and common mistakes.
+## Hreflang Tag Format
+Hreflang tells search engines which language/region a page targets and where alternate versions exist:
+```html
+<!-- On the English page -->
+<link rel="alternate" hreflang="en" href="https://example.com/about/" />
+<link rel="alternate" hreflang="it" href="https://example.com/it/chi-siamo/" />
+<link rel="alternate" hreflang="de" href="https://example.com/de/ueber-uns/" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/about/" />
+```
+### Language Code Reference
+| Code | Language | Notes |
+|------|----------|-------|
+| `en` | English | Use `en-us`, `en-gb` for regional |
+| `it` | Italian | |
+| `de` | German | Use `de-at` for Austrian German |
+| `fr` | French | Use `fr-ca` for Canadian French |
+| `es` | Spanish | Use `es-mx` for Mexican Spanish |
+| `pt` | Portuguese | Use `pt-br` for Brazilian Portuguese |
+| `zh-hans` | Chinese (Simplified) | |
+| `zh-hant` | Chinese (Traditional) | |
+| `x-default` | Fallback/default | One per page set |
+### Rules
+1. **Self-referencing required:** Every page must include an hreflang tag pointing to itself
+2. **Reciprocal required:** If page A links to page B with hreflang, page B must link back to page A
+3. **x-default:** One page per set should be designated as the default (usually English or main language)
+4. **Absolute URLs:** Always use full absolute URLs in href attributes
+5. **One tag per language-region:** Don't duplicate language codes
+## Implementation Methods
+### Method 1: HTML `<head>` Tags (Recommended)
+```html
+<head>
+  <link rel="alternate" hreflang="en" href="https://example.com/products/" />
+  <link rel="alternate" hreflang="it" href="https://example.com/it/prodotti/" />
+  <link rel="alternate" hreflang="x-default" href="https://example.com/products/" />
+</head>
+```
+### Method 2: HTTP Headers (for non-HTML content)
+```
+Link: <https://example.com/products/>; rel="alternate"; hreflang="en",
+      <https://example.com/it/prodotti/>; rel="alternate"; hreflang="it"
+```
+### Method 3: XML Sitemap
+```xml
+<url>
+  <loc>https://example.com/products/</loc>
+  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/products/" />
+  <xhtml:link rel="alternate" hreflang="it" href="https://example.com/it/prodotti/" />
+</url>
+```
+## mu-plugin for Automatic Hreflang Generation
+This mu-plugin automatically generates hreflang tags across a multisite network by matching content via slug:
+```php
+<?php
+/**
+ * Plugin Name: Multisite Hreflang Generator
+ * Description: Automatically generates hreflang tags across multisite network.
+ * Version: 1.0.0
+ */
+add_action('wp_head', function () {
+    if (!is_multisite()) return;
+    $current_blog_id = get_current_blog_id();
+    $current_path = trailingslashit(parse_url(get_permalink(), PHP_URL_PATH));
+    // Map blog IDs to language codes
+    $language_map = [
+        1 => 'en',       // Main site = English
+        2 => 'it',       // /it/ sub-site
+        3 => 'de',       // /de/ sub-site
+        4 => 'fr',       // /fr/ sub-site
+        // Add more as needed
+    ];
+    // Get current post slug for matching
+    $current_slug = '';
+    if (is_singular()) {
+        $current_slug = get_post_field('post_name', get_queried_object_id());
+    }
+    if (empty($current_slug)) return;
+    $sites = get_sites(['number' => 100]);
+    $alternates = [];
+    foreach ($sites as $site) {
+        $lang = $language_map[$site->blog_id] ?? null;
+        if (!$lang) continue;
+        switch_to_blog($site->blog_id);
+        // Find matching content by slug
+        $matched_post = get_page_by_path($current_slug, OBJECT, ['post', 'page', 'product']);
+        if ($matched_post && $matched_post->post_status === 'publish') {
+            $alternates[] = [
+                'lang' => $lang,
+                'href' => get_permalink($matched_post->ID),
+            ];
+        }
+        restore_current_blog();
+    }
+    // Only output if we found at least 2 alternates (including self)
+    if (count($alternates) < 2) return;
+    // Output hreflang tags
+    foreach ($alternates as $alt) {
+        printf(
+            '<link rel="alternate" hreflang="%s" href="%s" />' . "\n",
+            esc_attr($alt['lang']),
+            esc_url($alt['href'])
+        );
+    }
+    // x-default = main site (blog_id 1)
+    $default = array_filter($alternates, fn($a) => $a['lang'] === ($language_map[1] ?? 'en'));
+    if (!empty($default)) {
+        printf(
+            '<link rel="alternate" hreflang="x-default" href="%s" />' . "\n",
+            esc_url(reset($default)['href'])
+        );
+    }
+});
+```
+**Installation:**
+1. Save as `wp-content/mu-plugins/multisite-hreflang.php`
+2. Update `$language_map` with your blog IDs and language codes
+3. Content matching is by slug — ensure translated pages share the same slug or use a custom meta field for cross-referencing
+## Hreflang Validation
+### Google Search Console
+1. Go to International Targeting report
+2. Check for hreflang errors: missing return tags, unknown language codes, conflicting tags
+3. Verify per-language properties are set up (if using subdomains/domains)
+### Online Validators
+| Tool | URL | Checks |
+|------|-----|--------|
+| Hreflang Tags Checker | `hreflang.org` | Tag syntax, return links, x-default |
+| Ahrefs Hreflang Audit | Ahrefs Site Audit | Reciprocal links, missing alternates |
+| Screaming Frog | Desktop crawler | Bulk hreflang validation |
+### Manual Verification
+```bash
+# Check hreflang tags on a page
+curl -s https://example.com/products/ | grep -i "hreflang"
+# Verify reciprocal: check that the Italian page links back
+curl -s https://example.com/it/prodotti/ | grep -i "hreflang"
+```
+## Common Mistakes
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| Missing self-referencing tag | Search engines ignore the set | Always include hreflang for current page |
+| Missing reciprocal (A→B but not B→A) | Both tags get ignored | Ensure all pages in set link to each other |
+| Wrong language codes | Tags treated as invalid | Use ISO 639-1 codes, verify spelling |
+| Relative URLs in href | Tags get ignored | Always use absolute URLs with protocol |
+| Mixing hreflang methods (head + sitemap) | Potential conflicts | Choose one method and use it consistently |
+| Pointing hreflang to redirecting URLs | Tag gets ignored | Point to final destination URL |
+| Duplicate language codes on same page | Ambiguous signal | One tag per language-region combination |
+## Decision Checklist
+1. Are all language sites created in the multisite network? → Verify with `list_sites`
+2. Is the `$language_map` in the mu-plugin correct? → Map each blog_id to its language code
+3. Do translated pages share slugs for matching? → If not, use custom meta field for cross-reference
+4. Are hreflang tags present on all public pages? → Spot-check with `curl | grep hreflang`
+5. Are reciprocal tags correct? → Check both directions for 3+ sample pages
+6. Is `x-default` set to the main language site? → Verify in page source
+7. Is Google Search Console showing no hreflang errors? → Check International Targeting report

package/skills/wp-multilang-network/references/language-routing.md ADDED Viewed

@@ -0,0 +1,234 @@
+# Language Routing
+Use this file when configuring how users are directed to the correct language version — browser language detection, geo-IP redirect, language switcher widgets, and cookie-based preferences.
+## Browser Language Detection
+The `Accept-Language` HTTP header indicates the user's preferred languages:
+```
+Accept-Language: it-IT,it;q=0.9,en-US;q=0.8,en;q=0.7
+```
+### PHP Detection (mu-plugin)
+```php
+<?php
+/**
+ * Language redirect based on Accept-Language header.
+ * Only redirects on first visit (no cookie set yet).
+ */
+add_action('template_redirect', function () {
+    if (!is_multisite() || is_admin()) return;
+    // Skip if user has language preference cookie
+    if (isset($_COOKIE['wp_lang_pref'])) return;
+    // Skip if already on a language sub-site
+    $current_blog = get_current_blog_id();
+    if ($current_blog !== 1) return; // Only redirect from main site
+    $accepted = $_SERVER['HTTP_ACCEPT_LANGUAGE'] ?? '';
+    $preferred_lang = substr($accepted, 0, 2); // Get primary language code
+    $language_sites = [
+        'it' => '/it/',
+        'de' => '/de/',
+        'fr' => '/fr/',
+        'es' => '/es/',
+    ];
+    if (isset($language_sites[$preferred_lang])) {
+        $target = home_url($language_sites[$preferred_lang]);
+        // Set cookie so we don't redirect again
+        setcookie('wp_lang_pref', $preferred_lang, time() + (365 * DAY_IN_SECONDS), '/');
+        wp_redirect($target, 302); // 302 = temporary (important for SEO)
+        exit;
+    }
+});
+```
+**Important:** Always use 302 (temporary) redirect for language detection, never 301 (permanent). A 301 would cache the redirect for all users, regardless of their language.
+## Geo-IP Based Language Redirect
+Use server-side geo-IP to redirect by country:
+### Nginx Configuration
+```nginx
+# Requires ngx_http_geoip2_module
+geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
+    $geoip2_country_code default=US country iso_code;
+}
+server {
+    # Redirect Italian visitors to /it/
+    if ($geoip2_country_code = "IT") {
+        set $lang_redirect "/it/";
+    }
+    if ($geoip2_country_code = "DE") {
+        set $lang_redirect "/de/";
+    }
+    # Only redirect if no cookie and on root
+    location = / {
+        if ($cookie_wp_lang_pref = "") {
+            return 302 $scheme://$host$lang_redirect;
+        }
+    }
+}
+```
+### CloudFlare Workers
+```javascript
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+    const country = request.cf?.country || 'US';
+    const hasPref = request.headers.get('cookie')?.includes('wp_lang_pref');
+    if (url.pathname === '/' && !hasPref) {
+      const langMap = { IT: '/it/', DE: '/de/', FR: '/fr/', ES: '/es/' };
+      if (langMap[country]) {
+        return Response.redirect(url.origin + langMap[country], 302);
+      }
+    }
+    return fetch(request);
+  }
+};
+```
+## Language Switcher Widget
+### HTML/CSS Language Switcher
+```html
+<nav class="language-switcher" aria-label="Language selection">
+  <ul>
+    <li><a href="https://example.com/about/" hreflang="en" lang="en">English</a></li>
+    <li><a href="https://example.com/it/chi-siamo/" hreflang="it" lang="it">Italiano</a></li>
+    <li><a href="https://example.com/de/ueber-uns/" hreflang="de" lang="de">Deutsch</a></li>
+    <li><a href="https://example.com/fr/a-propos/" hreflang="fr" lang="fr">Français</a></li>
+  </ul>
+</nav>
+```
+### WordPress Widget (mu-plugin)
+```php
+add_action('widgets_init', function () {
+    register_widget('Multilang_Switcher_Widget');
+});
+class Multilang_Switcher_Widget extends WP_Widget {
+    public function __construct() {
+        parent::__construct('multilang_switcher', 'Language Switcher');
+    }
+    public function widget($args, $instance) {
+        $sites = get_sites(['number' => 20]);
+        $language_names = [
+            1 => ['code' => 'en', 'name' => 'English'],
+            2 => ['code' => 'it', 'name' => 'Italiano'],
+            3 => ['code' => 'de', 'name' => 'Deutsch'],
+            // Add more...
+        ];
+        echo $args['before_widget'];
+        echo '<nav class="language-switcher" aria-label="Language"><ul>';
+        foreach ($sites as $site) {
+            $lang = $language_names[$site->blog_id] ?? null;
+            if (!$lang) continue;
+            $url = get_home_url($site->blog_id);
+            $active = ($site->blog_id === get_current_blog_id()) ? ' class="active"' : '';
+            printf('<li%s><a href="%s" hreflang="%s" lang="%s">%s</a></li>',
+                $active, esc_url($url), esc_attr($lang['code']),
+                esc_attr($lang['code']), esc_html($lang['name'])
+            );
+        }
+        echo '</ul></nav>';
+        echo $args['after_widget'];
+    }
+}
+```
+## URL Structure Consistency
+Ensure consistent URL patterns across all language sites:
+| English (primary) | Italian | German | Rule |
+|-------------------|---------|--------|------|
+| `/about/` | `/it/chi-siamo/` | `/de/ueber-uns/` | Translated slugs (better UX) |
+| `/about/` | `/it/about/` | `/de/about/` | Same slugs (easier hreflang matching) |
+| `/products/shoes/` | `/it/prodotti/scarpe/` | `/de/produkte/schuhe/` | Full translation |
+**Recommendation:** Use **same slugs** for easier hreflang matching via the mu-plugin. If translated slugs are preferred for UX, maintain a cross-reference table or use the multilingual plugin's content connections.
+## Cookie-Based Language Preference
+Store user's explicit language choice to persist across sessions:
+```php
+// When user clicks language switcher, set preference cookie
+add_action('init', function () {
+    if (isset($_GET['set_lang'])) {
+        $lang = sanitize_text_field($_GET['set_lang']);
+        $allowed = ['en', 'it', 'de', 'fr', 'es'];
+        if (in_array($lang, $allowed, true)) {
+            setcookie('wp_lang_pref', $lang, time() + (365 * DAY_IN_SECONDS), '/');
+        }
+    }
+});
+```
+**Priority order for language selection:**
+1. Explicit choice (cookie from language switcher click) — highest
+2. URL path (user navigated to `/it/` directly)
+3. Browser `Accept-Language` header (auto-detect)
+4. Geo-IP (server-side guess)
+5. Default language (x-default / main site) — lowest
+## Headless Frontend Language Routing
+### Next.js i18n
+```javascript
+// next.config.js
+module.exports = {
+  i18n: {
+    locales: ['en', 'it', 'de', 'fr'],
+    defaultLocale: 'en',
+    localeDetection: true, // Auto-detect from Accept-Language
+  },
+};
+```
+### Nuxt i18n Module
+```javascript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+  i18n: {
+    locales: ['en', 'it', 'de', 'fr'],
+    defaultLocale: 'en',
+    strategy: 'prefix_except_default', // /it/about, /de/about, /about (en)
+    detectBrowserLanguage: {
+      useCookie: true,
+      cookieKey: 'i18n_redirected',
+    },
+  },
+});
+```
+## Decision Checklist
+1. Should language be detected automatically or only via switcher? → Auto-detect on first visit, respect explicit choice after
+2. Is geo-IP available at the hosting/CDN level? → CloudFlare/nginx = yes; shared hosting = maybe not
+3. Are redirect rules using 302 (not 301)? → 301 caches per-user, breaks multi-language
+4. Is a language switcher present on all pages? → Add to header/footer template
+5. Is cookie-based preference persisted? → Set on switcher click, check before redirect
+6. For headless: is frontend i18n routing configured? → Next.js `i18n` or Nuxt i18n module

package/skills/wp-multilang-network/references/network-architecture.md ADDED Viewed

@@ -0,0 +1,119 @@
+# Network Architecture
+Use this file when designing the multi-language WordPress Multisite network — choosing between subdomains, subdirectories, or separate domains, selecting a multilingual plugin, and establishing site creation workflows.
+## Architecture Patterns
+| Pattern | Example | Pros | Cons |
+|---------|---------|------|------|
+| **Subdirectory** | `example.com/it/`, `example.com/de/` | Shares domain authority, easy SSL, one hosting | Less geographic signal, shared server resources |
+| **Subdomain** | `it.example.com`, `de.example.com` | Separate GSC properties, clear language signal | SSL per subdomain, DNS configuration needed |
+| **Separate domains** | `example.it`, `example.de` | Strongest geo-targeting signal, full independence | Multiple hosting/SSL/DNS, no shared authority |
+### When to Choose Each
+**Subdirectory (recommended for most):**
+- Starting a multilingual site with shared content
+- Budget-conscious (one hosting, one SSL)
+- Want to inherit domain authority across languages
+- 2–5 languages
+**Subdomain:**
+- Each language needs significant independence
+- Different teams manage different languages
+- Want separate Google Search Console properties
+- 3–10 languages
+**Separate domains:**
+- Strong country-specific targeting needed (ccTLDs)
+- Completely independent content per market
+- Enterprise with per-country marketing teams
+- Already owns country domains
+## Sub-Site Creation Workflow
+Using multisite MCP tools to create language sub-sites:
+```bash
+# 1. List existing sites
+list_sites()
+# 2. Create language sub-sites (one per language)
+ms_create_site(domain="example.com", path="/it/", title="Example - Italiano")
+ms_create_site(domain="example.com", path="/de/", title="Example - Deutsch")
+ms_create_site(domain="example.com", path="/fr/", title="Example - Français")
+ms_create_site(domain="example.com", path="/es/", title="Example - Español")
+# 3. Verify all sites created
+list_sites()
+```
+### Naming Conventions
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Site slug/path | ISO 639-1 language code | `/it/`, `/de/`, `/fr/` |
+| Site title | `{Brand} - {Language Name}` | "DolceZero - Italiano" |
+| Admin email | Shared network admin email | `admin@example.com` |
+| Language constant | WordPress locale code | `it_IT`, `de_DE`, `fr_FR` |
+**For regional variants:**
+- Use ISO 639-1 + country: `pt-br` (Brazilian Portuguese), `zh-cn` (Simplified Chinese)
+- Path: `/pt-br/`, `/zh-cn/`
+## Shared vs Independent Content
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| **Shared + translated** | Same content structure, translated per language | Marketing sites, blogs |
+| **Shared core + local** | Common pages translated, plus local-only content | E-commerce with local products |
+| **Fully independent** | Each site has its own editorial calendar | News sites, regional publications |
+## Network Plugin Management
+### Network-Activated Plugins (shared across all sites)
+Plugins that should be network-activated for consistency:
+- Multilingual plugin (WPML, Polylang, MultilingualPress)
+- SEO plugin (Yoast, Rank Math)
+- Caching plugin (WP Super Cache, W3 Total Cache)
+- Security plugin (Wordfence, Sucuri)
+```bash
+# Network-activate a plugin (WP-CLI)
+wp plugin activate yoast-seo --network
+# Or via MCP tool
+ms_network_activate_plugin(plugin="wordpress-seo/wp-seo.php")
+```
+### Per-Site Plugins
+Plugins that may differ per language site:
+- Payment gateways (region-specific)
+- Legal compliance (GDPR, cookie consent varies by country)
+- Local directory integrations
+## Multilingual Plugin Comparison
+| Feature | WPML | Polylang | MultilingualPress |
+|---------|------|----------|-------------------|
+| **Architecture** | Single-site (can work with multisite) | Single-site (multisite add-on available) | Native multisite |
+| **License** | Paid ($39–$159/yr) | Free core + paid add-ons | Paid (€199/yr) |
+| **Translation management** | Built-in TM, XLIFF export | Manual or XLIFF | Content connections between sites |
+| **String translation** | Yes (wpml-string-translation) | Polylang Pro | Via WordPress i18n |
+| **WooCommerce support** | WPML WooCommerce Multilingual | WooCommerce Polylang | Native multisite WC |
+| **Performance impact** | Medium (additional DB queries) | Low | Low (native multisite) |
+| **Best for** | Single-site multilingual | Small sites, budget-friendly | Multisite-native workflows |
+### Recommendation
+For a **Multisite multi-language network**, prefer **MultilingualPress** (native multisite design) or **WPML** (most feature-rich). Polylang is best for single-site setups.
+## Decision Checklist
+1. How many languages are needed now and in 2 years? → 2–5 = subdirectory; 5+ = subdomain
+2. Do language sites share content or are they independent? → Shared = translation plugin; Independent = just multisite
+3. Is the team centralized or per-country? → Centralized = shared admin; Per-country = per-site admins
+4. Is WooCommerce involved? → Yes = verify plugin WC compatibility
+5. What's the budget for multilingual plugin licensing? → Free = Polylang; Paid = WPML or MultilingualPress