claude-plugin-wordpress-manager 2.2.1 → 2.3.1

package/skills/wp-multilang-network/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: wp-multilang-network
+description: |
+  This skill should be used when the user asks to "set up multilingual site",
+  "multisite per language", "hreflang tags", "international SEO", "translate site
+  network", "language-specific sub-sites", "multi-language WordPress", "localize
+  content across sites", "content translation sync", "geo-targeting",
+  or mentions orchestrating a WordPress Multisite network where each sub-site
+  serves a different language or locale.
+version: 1.0.0
+---
+
+## Overview
+
+Multi-Language Network uses WordPress Multisite to create a coordinated network where each sub-site serves a different language or locale. Content is synchronized across sites via translation plugins or manual workflows, with hreflang tags ensuring search engines serve the correct language variant to users.
+
+This skill orchestrates existing multisite MCP tools (10 tools), the `wp-i18n` skill for translation best practices, and multilingual plugin workflows (WPML, Polylang, MultilingualPress). No new tools are required.
+
+## When to Use
+
+- User needs international presence with 2+ languages
+- "Set up Italian and Spanish versions of our site"
+- "Add hreflang tags across our multisite network"
+- "Translate content and keep translations in sync"
+- "Set up language-specific sub-sites"
+- "Configure international SEO for multiple languages"
+- "Redirect users based on browser language"
+
+## Multi-Language Network vs Single-Site Plugin
+
+| Aspect | Multisite Network | Single-Site Plugin |
+|--------|------------------|-------------------|
+| Scalability | Excellent — independent sites per language | Good for 2–5 languages, complex beyond |
+| SEO control | Full — separate sitemaps, robots.txt, GSC per site | Shared — one sitemap with hreflang |
+| Content independence | Each site can have unique content | All content on one database |
+| Maintenance overhead | Higher — plugins/themes per site (unless network-activated) | Lower — one site to maintain |
+| Performance | Better — smaller DB per language | Can degrade with many languages |
+| Domain flexibility | Subdomains, subdirectories, or separate domains | Subdirectories or query params |
+| Plugin compatibility | Standard WP plugins work per-site | Must be compatible with multilingual plugin |
+
+## Prerequisites
+
+- WordPress Multisite enabled (reference: `wp-multisite` skill)
+- WP-CLI access for network operations
+- Multilingual plugin installed (WPML, Polylang, or MultilingualPress)
+- DNS configured for subdomains or subdirectories
+
+## Prerequisites / Detection
+
+```bash
+node skills/wp-multilang-network/scripts/multilang_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script checks Multisite status, multilingual plugins, sub-site count, language patterns in slugs, hreflang presence, and WPLANG configuration.
+
+## Multi-Language Network Operations Decision Tree
+
+1. **What multi-language task?**
+
+   - "set up multisite per language" / "create language sites" / "network architecture"
+     → **Network Architecture** — Read: `references/network-architecture.md`
+
+   - "hreflang" / "language alternates" / "x-default" / "hreflang tags"
+     → **Hreflang Configuration** — Read: `references/hreflang-config.md`
+
+   - "translate content" / "sync content" / "keep translations in sync" / "translation workflow"
+     → **Content Synchronization** — Read: `references/content-sync.md`
+
+   - "language switcher" / "language detection" / "redirect by language" / "browser language"
+     → **Language Routing** — Read: `references/language-routing.md`
+
+   - "international SEO" / "geo-targeting" / "language sitemaps" / "search console per language"
+     → **International SEO** — Read: `references/seo-international.md`
+
+2. **Common workflow (new multi-language network):**
+   1. Assess current network: `list_sites` + run `multilang_inspect.mjs`
+   2. Create language sub-sites: `ms_create_site` per language (slug = ISO 639-1 code)
+   3. Install and configure multilingual plugin network-wide
+   4. Set up hreflang tags (mu-plugin or plugin)
+   5. Establish content sync workflow (manual or plugin-assisted)
+   6. Configure language routing and switcher widget
+   7. Set up per-language XML sitemaps
+   8. Verify with international SEO checklist
+
+## Recommended Agent
+
+`wp-site-manager` — handles multisite network operations, sub-site management, and cross-site coordination.
+
+## Additional Resources
+
+### Reference Files
+
+| File | Description |
+|------|-------------|
+| **`references/network-architecture.md`** | Subdomain vs subdirectory vs domains, plugin comparison, naming conventions |
+| **`references/hreflang-config.md`** | Hreflang format, mu-plugin auto-generation, validation, common mistakes |
+| **`references/content-sync.md`** | WPML/Polylang/MultilingualPress workflows, translation status tracking |
+| **`references/language-routing.md`** | Browser detection, geo-IP redirect, language switcher, cookie preference |
+| **`references/seo-international.md`** | GSC per language, language sitemaps, schema localization, CDN per region |
+
+### Related Skills
+
+- `wp-multisite` — multisite network management (10 MCP tools)
+- `wp-i18n` — internationalization and localization best practices
+- `wp-headless` — headless frontend with i18n routing (Next.js i18n, Nuxt i18n)
+- `wp-programmatic-seo` — scalable page generation (complement for multi-language SEO)
+- `wp-content` — content management for each language sub-site

package/skills/wp-multilang-network/references/content-sync.md

@@ -0,0 +1,182 @@
+# Content Synchronization
+
+Use this file when establishing content translation and synchronization workflows across a WordPress Multisite network — plugin-specific workflows, manual sync procedures, and translation status tracking.
+
+## Synchronization Strategies
+
+| Strategy | Description | Effort | Best For |
+|----------|-------------|--------|----------|
+| **Manual** | Create content independently per site | High ongoing | Fully independent content |
+| **Semi-automatic** | Create on primary, replicate structure, translate manually | Medium | Shared structure, unique translations |
+| **Fully automatic** | Plugin syncs content, human reviews translation | Low ongoing | High-volume, similar content |
+
+## WPML Network Mode
+
+WPML can operate across multisite with the "WPML for Multisite" add-on:
+
+### Setup
+
+1. Network-activate WPML on all sites
+2. Configure primary language per site (each site = one language)
+3. Enable translation management across network
+
+### Workflow
+
+```
+1. Create content on primary site (e.g., English)
+2. WPML sends content to translation queue
+3. Translator works via WPML Translation Management or XLIFF export
+4. Translated content auto-publishes on target language site
+5. WPML maintains content connections (post ID mapping)
+```
+
+### Key WPML Functions
+
+```php
+// Get translation of a post on another site
+$translated_id = apply_filters('wpml_object_id', $post_id, 'post', false, 'it');
+
+// Get all translations of current post
+$translations = apply_filters('wpml_active_languages', null);
+```
+
+## Polylang for Multisite
+
+Polylang's multisite extension assigns one language per sub-site:
+
+### Setup
+
+1. Install Polylang Pro + Polylang for Multisite
+2. Assign language to each sub-site in Network Admin → Sites → Polylang
+3. Configure which content types are translatable
+
+### Workflow
+
+```
+1. Create post on primary site
+2. Polylang shows "Translate" button for each target language
+3. Click creates a linked draft on the target language site
+4. Translator fills in translation
+5. Publish triggers hreflang auto-generation
+```
+
+### Polylang API
+
+```php
+// Get translation link
+$translation_id = pll_get_post($post_id, 'it');
+
+// Get language of current post
+$language = pll_get_post_language($post_id);
+
+// Set translation relationship
+pll_set_post_language($post_id, 'it');
+```
+
+## MultilingualPress
+
+MultilingualPress is built specifically for WordPress Multisite:
+
+### Setup
+
+1. Install and network-activate MultilingualPress
+2. Go to Network Admin → MultilingualPress → set language per site
+3. Define content relationships between sites
+
+### Workflow
+
+```
+1. Create content on any site in the network
+2. In the editor, MultilingualPress shows "Translation" metabox
+3. Select target sites and either:
+   a. Copy content (for later manual translation)
+   b. Link existing content on target site
+4. MultilingualPress maintains bidirectional content connections
+5. Hreflang tags generated automatically from connections
+```
+
+### Advantages for Multisite
+
+- Native multisite architecture (no complex DB tables like WPML)
+- Each site has its own standard WP database tables
+- Content connections stored as post meta (lightweight)
+- Works with standard WordPress REST API per-site
+
+## Manual Sync Workflow
+
+When no multilingual plugin is used, sync content manually via MCP tools:
+
+```bash
+# 1. Create content on primary site
+switch_site(site_id=1)  # Switch to English site
+create_content(type="post", title="Cactus Water Benefits", slug="cactus-water-benefits",
+  content="...", status="publish")
+
+# 2. Replicate structure on Italian site
+switch_site(site_id=2)  # Switch to Italian site
+create_content(type="post", title="Benefici dell'Acqua di Cactus", slug="cactus-water-benefits",
+  content="[Italian translation]", status="draft")
+
+# 3. Replicate on German site
+switch_site(site_id=3)  # Switch to German site
+create_content(type="post", title="Vorteile von Kaktuswasser", slug="cactus-water-benefits",
+  content="[German translation]", status="draft")
+
+# 4. Switch back to primary
+switch_site(site_id=1)
+```
+
+**Important:** Keep the **slug identical** across all language sites for hreflang matching (the mu-plugin matches by slug).
+
+## Translation Status Tracking
+
+Track the translation state of each content piece:
+
+| Status | Meaning | Visual Indicator |
+|--------|---------|-----------------|
+| `untranslated` | No translation exists on target site | Red dot |
+| `draft` | Translation created but not reviewed | Yellow dot |
+| `pending_review` | Translation complete, awaiting review | Orange dot |
+| `published` | Translation live and approved | Green dot |
+| `outdated` | Source content updated after translation | Blue dot with warning |
+
+### Custom Meta for Tracking
+
+```php
+// On the primary site post, track translation status
+update_post_meta($post_id, '_translation_status_it', 'published');
+update_post_meta($post_id, '_translation_status_de', 'draft');
+update_post_meta($post_id, '_translation_status_fr', 'untranslated');
+
+// When source is updated, mark translations as outdated
+add_action('post_updated', function ($post_id) {
+    $languages = ['it', 'de', 'fr', 'es'];
+    foreach ($languages as $lang) {
+        $current = get_post_meta($post_id, "_translation_status_{$lang}", true);
+        if ($current === 'published') {
+            update_post_meta($post_id, "_translation_status_{$lang}", 'outdated');
+        }
+    }
+});
+```
+
+## Media Library Sharing
+
+By default, each multisite sub-site has its own media library. Options for sharing:
+
+| Approach | Plugin | Description |
+|----------|--------|-------------|
+| **Network Media Library** | Network Media Library plugin | Shared library accessible from all sites |
+| **Global Media** | Network Shared Media plugin | Central media site, others embed |
+| **Manual upload** | None | Upload same images per site (wasteful but independent) |
+
+**Recommendation:** Use Network Media Library for brand assets (logo, product images) that are identical across languages. Allow per-site uploads for language-specific images (localized banners, team photos).
+
+## Decision Checklist
+
+1. Which sync strategy: manual, semi-automatic, or fully automatic? → Match to team size and budget
+2. Is a multilingual plugin chosen and installed? → MultilingualPress for multisite-native; WPML for feature-rich
+3. Are content connections established between sites? → Verify via plugin admin or custom meta
+4. Do translated pages use matching slugs for hreflang? → Audit sample pages
+5. Is translation status tracked? → Custom meta or plugin dashboard
+6. Is the media library shared or per-site? → Shared for brand assets, per-site for localized content

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

@@ -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