claude-plugin-wordpress-manager 2.2.0 → 2.3.0

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

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

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

package/skills/wp-multilang-network/references/seo-international.md

@@ -0,0 +1,213 @@
+# International SEO
+
+Use this file when optimizing a multi-language WordPress Multisite network for international search — Google Search Console per language, language-specific sitemaps, schema localization, and performance per region.
+
+## International SEO Fundamentals
+
+| Principle | Description |
+|-----------|-------------|
+| One page per language | Each language has its own URL (no dynamic translation) |
+| Unique content | Translations should be human-quality, not raw machine output |
+| Hreflang everywhere | Every page declares all its language alternates |
+| Language-specific sitemaps | One XML sitemap per sub-site/language |
+| GSC per property | Separate Search Console properties for monitoring |
+
+## Google Search Console Setup
+
+### Per-Language Properties
+
+For a multisite with subdirectories:
+
+```
+Property 1: https://example.com/       (English — main)
+Property 2: https://example.com/it/     (Italian)
+Property 3: https://example.com/de/     (German)
+Property 4: https://example.com/fr/     (French)
+```
+
+For subdomains:
+
+```
+Property 1: https://example.com          (English)
+Property 2: https://it.example.com       (Italian)
+Property 3: https://de.example.com       (German)
+```
+
+### International Targeting
+
+1. Open each language property in GSC
+2. Go to Legacy tools → International Targeting
+3. Set target country (optional — only if site targets a specific country, not just a language)
+4. Monitor hreflang errors in the same section
+
+### Per-Language Monitoring
+
+For each language property, monitor:
+- **Coverage:** Indexed pages count (should match published pages on that sub-site)
+- **Performance:** Clicks, impressions, CTR, position — filter by country
+- **Sitemaps:** Verify language-specific sitemap is submitted and processed
+
+## Language-Specific XML Sitemaps
+
+Each WordPress sub-site in the multisite network generates its own sitemap:
+
+```
+https://example.com/sitemap_index.xml          (English)
+https://example.com/it/sitemap_index.xml       (Italian)
+https://example.com/de/sitemap_index.xml       (German)
+```
+
+### Sitemap Index at Network Level
+
+Create a network-level sitemap index that references all sub-site sitemaps:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <sitemap>
+    <loc>https://example.com/sitemap_index.xml</loc>
+    <lastmod>2025-01-15</lastmod>
+  </sitemap>
+  <sitemap>
+    <loc>https://example.com/it/sitemap_index.xml</loc>
+    <lastmod>2025-01-14</lastmod>
+  </sitemap>
+  <sitemap>
+    <loc>https://example.com/de/sitemap_index.xml</loc>
+    <lastmod>2025-01-13</lastmod>
+  </sitemap>
+</sitemapindex>
+```
+
+### Hreflang in Sitemaps
+
+For maximum hreflang coverage, include language alternates in each 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/" />
+  <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/produkte/" />
+  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/products/" />
+</url>
+```
+
+**Note:** If using the hreflang mu-plugin in `<head>`, you can skip sitemap hreflang. Using both is not harmful but adds maintenance.
+
+## Structured Data Localization
+
+### Schema.org `inLanguage` Property
+
+Add language to all structured data:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "WebPage",
+  "name": "Benefici dell'Acqua di Cactus",
+  "inLanguage": "it",
+  "url": "https://example.com/it/benefici-acqua-cactus/",
+  "isPartOf": {
+    "@type": "WebSite",
+    "name": "DolceZero Italia",
+    "url": "https://example.com/it/",
+    "inLanguage": "it"
+  }
+}
+```
+
+### Localized Organization Schema
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "DolceZero",
+  "url": "https://example.com/",
+  "alternateName": ["DolceZero Italia", "DolceZero Deutschland"],
+  "contactPoint": [
+    {
+      "@type": "ContactPoint",
+      "telephone": "+39-xxx-xxx-xxxx",
+      "contactType": "customer service",
+      "areaServed": "IT",
+      "availableLanguage": "Italian"
+    },
+    {
+      "@type": "ContactPoint",
+      "telephone": "+49-xxx-xxx-xxxx",
+      "contactType": "customer service",
+      "areaServed": "DE",
+      "availableLanguage": "German"
+    }
+  ]
+}
+```
+
+## Canonical URLs in Multi-Language Context
+
+| Scenario | Canonical Rule |
+|----------|---------------|
+| English product page | Self-canonical: `https://example.com/products/cactus-water/` |
+| Italian product page | Self-canonical: `https://example.com/it/prodotti/acqua-cactus/` |
+| English = Italian (untranslated) | **Do NOT canonical Italian → English** — either translate or noindex |
+| URL with `?lang=` parameter | Canonical → clean URL without parameter |
+
+**Critical rule:** Never use canonical across languages. Each language URL is canonical for its language. Use hreflang to declare relationships.
+
+## Avoiding Duplicate Content
+
+| Issue | Solution |
+|-------|----------|
+| Untranslated pages showing English on Italian site | Set as `noindex` until translated, or serve 404 |
+| Machine-translated thin content | Block from indexing; translate properly or remove |
+| Same content on main site and language site | Ensure distinct translations; use hreflang for signals |
+| Language switcher creating `?lang=` URLs | Canonical to clean URL; use path-based routing |
+
+## Performance: CDN per Region
+
+### CloudFlare Configuration
+
+```
+CDN cache by language:
+- English:  Edge servers worldwide (default)
+- Italian:  Prioritize EU-South edge locations
+- German:   Prioritize EU-Central edge locations
+- Japanese: Prioritize Asia-Pacific edge locations
+```
+
+### Image Localization
+
+- Product images: shared across languages (CDN serves nearest edge)
+- Marketing banners: may differ per language (upload per sub-site)
+- OG images: localized per language (localized text overlays)
+
+## Measuring International SEO
+
+### Metrics per Language
+
+| Metric | Source | Frequency |
+|--------|--------|-----------|
+| Organic traffic by language | GA4 (filter by page path prefix) | Weekly |
+| Rankings by country | GSC Performance → Country filter | Weekly |
+| Indexed pages per language | GSC Coverage per property | Monthly |
+| Hreflang errors | GSC International Targeting | Monthly |
+| Conversion rate by language | WooCommerce + GA4 | Monthly |
+
+### Success Indicators
+
+- Indexed pages per language ≈ published pages per sub-site
+- Zero hreflang errors in GSC
+- Organic traffic growing in target language markets
+- Conversion rate per language within 20% of primary language
+
+## Decision Checklist
+
+1. Is GSC set up per language property? → Create and verify each
+2. Are language-specific sitemaps submitted? → One per sub-site
+3. Is `inLanguage` set in structured data? → Add to schema on each sub-site
+4. Are canonicals self-referencing per language (never cross-language)? → Audit sample pages
+5. Are untranslated pages noindexed? → Never show English content as Italian page
+6. Is CDN configured for international edge delivery? → Check CDN dashboard
+7. Are international SEO metrics tracked per language? → Set up monthly report