Install
Terminal · npx$
npx skills add https://github.com/coreyhaines31/marketingskills --skill seo-auditWorks with Paperclip
How Seo Hreflang fits into a Paperclip company.
Seo Hreflang drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.
S
SaaS FactoryPaired
Pre-configured AI company — 18 agents, 18 skills, one-time purchase.
$27$59
Explore packSource file
SKILL.md255 linesExpandCollapse
---name: seo-hreflangdescription: > Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags".user-invokable: trueargument-hint: "[url]"license: MITmetadata: author: AgriciDaniel version: "1.9.0" category: seo--- # Hreflang & International SEO Validate existing hreflang implementations or generate correct hreflang tagsfor multi-language and multi-region sites. Supports HTML, HTTP header, andXML sitemap implementations. ## Validation Checks ### 1. Self-Referencing Tags- Every page must include an hreflang tag pointing to itself- The self-referencing URL must exactly match the page's canonical URL- Missing self-referencing tags cause Google to ignore the entire hreflang set ### 2. Return Tags- If page A links to page B with hreflang, page B must link back to page A- Every hreflang relationship must be bidirectional (A→B and B→A)- Missing return tags invalidate the hreflang signal for both pages- Check all language versions reference each other (full mesh) ### 3. x-default Tag- Required: designates the fallback page for unmatched languages/regions- Typically points to the language selector page or English version- Only one x-default per set of alternates- Must also have return tags from all other language versions ### 4. Language Code Validation- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)- Common errors: - `eng` instead of `en` (ISO 639-2, not valid for hreflang) - `jp` instead of `ja` (incorrect code for Japanese) - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`) ### 5. Region Code Validation- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`)- Format: `language-REGION` (lowercase language, uppercase region)- Common errors: - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code) - `es-LA` (Latin America is not a country; use specific countries) - Region without language prefix ### 6. Canonical URL Alignment- Hreflang tags must only appear on canonical URLs- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored- The canonical URL and hreflang URL must match exactly (including trailing slashes)- Non-canonical pages should not be in any hreflang set ### 7. Protocol Consistency- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)- Mixed HTTP/HTTPS in hreflang sets causes validation failures- After HTTPS migration, update all hreflang tags to HTTPS ### 8. Cross-Domain Support- Hreflang works across different domains (e.g., example.com and example.de)- Cross-domain hreflang requires return tags on both domains- Verify both domains are verified in Google Search Console- Sitemap-based implementation recommended for cross-domain setups ## Common Mistakes | Issue | Severity | Fix ||-------|----------|-----|| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL || Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates || Missing x-default | High | Add x-default pointing to fallback/selector page || Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes || Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes || Hreflang on non-canonical URL | High | Move hreflang to canonical URL only || HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS || Trailing slash inconsistency | Medium | Match canonical URL format exactly || Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) || Language without region when needed | Low | Add region qualifier for geo-targeted content | ## Implementation Methods ### Method 1: HTML Link TagsBest for: Sites with <50 language/region variants per page. ```html<link rel="alternate" hreflang="en-US" href="https://example.com/page" /><link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" /><link rel="alternate" hreflang="fr" href="https://example.com/fr/page" /><link rel="alternate" hreflang="x-default" href="https://example.com/page" />``` Place in `<head>` section. Every page must include all alternates including itself. ### Method 2: HTTP HeadersBest for: Non-HTML files (PDFs, documents). ```Link: <https://example.com/page>; rel="alternate"; hreflang="en-US", <https://example.com/fr/page>; rel="alternate"; hreflang="fr", <https://example.com/page>; rel="alternate"; hreflang="x-default"``` Set via server configuration or CDN rules. ### Method 3: XML Sitemap (Recommended for large sites)Best for: Sites with many language variants, cross-domain setups, or 50+ pages. See Hreflang Sitemap Generation section below. ### Method Comparison| Method | Best For | Pros | Cons ||--------|----------|------|------|| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats `<head>`, hard to maintain at scale || HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML || XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance | ## Hreflang Generation ### Process1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)2. **Map page equivalents**: Match corresponding pages across languages/regions3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-14. **Generate tags**: Create hreflang tags for each page including self-referencing5. **Verify return tags**: Confirm all relationships are bidirectional6. **Add x-default**: Set fallback for each page set7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML) ## Hreflang Sitemap Generation ### Sitemap with Hreflang```xml<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"> <url> <loc>https://example.com/page</loc> <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" /> <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" /> <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" /> <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" /> </url> <url> <loc>https://example.com/fr/page</loc> <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" /> <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" /> <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" /> <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" /> </url></urlset>``` Key rules:- Include the `xmlns:xhtml` namespace declaration- Every `<url>` entry must include ALL language alternates (including itself)- Each alternate must appear as a separate `<url>` entry with its own full set- Split at 50,000 URLs per sitemap file ## Output ### Hreflang Validation Report #### Summary- Total pages scanned: XX- Language variants detected: XX- Issues found: XX (Critical: X, High: X, Medium: X, Low: X) #### Validation Results| Language | URL | Self-Ref | Return Tags | x-default | Status ||----------|-----|----------|-------------|-----------|--------|| en-US | https://... | ✅ | ✅ | ✅ | ✅ || fr | https://... | ❌ | ⚠️ | ✅ | ❌ || de | https://... | ✅ | ❌ | ✅ | ❌ | ### Generated Hreflang Tags- HTML `<link>` tags (if HTML method chosen)- HTTP header values (if header method chosen)- `hreflang-sitemap.xml` (if sitemap method chosen) ### Recommendations- Missing implementations to add- Incorrect codes to fix- Method migration suggestions (e.g., HTML to sitemap for scale) ## Cultural Adaptation Assessment When analyzing a multi-language site, go beyond technical hreflang validation to assesswhether the content is culturally adapted for each target market. Load `references/cultural-profiles.md` for pre-built profiles (DACH, Francophone, Hispanic, Japanese). **Assessment steps:**1. Identify all language versions and their target markets2. Load the relevant cultural profile(s)3. Check CTAs match cultural expectations (direct vs indirect)4. Check trust signals are locale-appropriate (certifications, legal pages)5. Check for foreign brand references on localized pages6. Check number/date/currency formatting consistency7. Flag cultural adaptation issues as Medium severity **Output:** Cultural Adaptation Score per language version (0-100) with specific findings. ## Content Parity Audit **Command:** `/seo hreflang audit <directory-or-url>` Audit content parity across all language versions of a site or local content directory. Load `references/content-parity.md` for the full parity matrix and scoring methodology. **What it checks:**- Page existence across all declared languages- Section structure equivalence (H2/H3 count)- SEO element parity (title, meta, schema localization)- Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)- Freshness tracking (stale translations detected via timestamps)- Cultural marker scanning (foreign brands, wrong legal references, untranslated elements) **Output:** Parity matrix table with per-page scores and prioritized action items. ## Locale Format Validation Load `references/locale-formats.md` for number, date, currency, address, and phone formatreference tables per locale. **Checks:**- Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages)- Date format matches locale expectations- Currency symbols and placement correct for target market- Phone numbers use international format with correct country code ## Reference Files Load on-demand as needed (do NOT load all at startup):- `references/cultural-profiles.md`: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles- `references/locale-formats.md`: Number, date, currency, address, phone format tables per locale- `references/content-parity.md`: Content parity audit methodology and scoring ## Error Handling | Scenario | Action ||----------|--------|| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. || No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. || Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. || Cultural profile not available for language | Use the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile. || Content parity directory empty | Report that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis. |