our-claude-skills/custom-skills/26-seo-international/SKILL.md

---
name: 26-seo-international
description: |
  International SEO audit and hreflang validation for multi-language and multi-region websites.
  Triggers: hreflang, international SEO, multi-language, multi-region, content parity, x-default, ccTLD, 다국어 SEO.
---

# International SEO Audit

## Purpose

Audit international SEO implementation: hreflang tags, URL structure patterns, content parity across language versions, redirect logic, and Korean expansion strategies. Identify issues preventing proper multi-language indexing.

## Core Capabilities

1. **Hreflang Validation** - Bidirectional links, self-reference, x-default, language code validation
2. **URL Structure Analysis** - ccTLD vs subdomain vs subdirectory pattern detection
3. **Content Parity Audit** - Page count comparison, key page availability across languages
4. **Redirect Logic Audit** - IP-based, Accept-Language redirects, forced redirect detection
5. **Korean Expansion** - Priority markets (ja, zh, en), CJK URL issues, regional search engines

## Data Source Selection

International SEO spans **hreflang validation** (crawl-derived), **content parity** (crawl-derived), and **per-country traffic** (modelled). Pick one backend per data class.

| Backend | Best for | Notes |
|---|---|---|
| **OurSEO** (CLI + MCP) | **Default** — hreflang validation, content parity, redirect logic, fix engine | CLI: `our collect crawl`, `our audit tech`, `our fix hreflang`. MCP: `mcp__ourseo__crawl_website`, `mcp__ourseo__audit_page`. Only backend that owns the hreflang FIX path. |
| **Ahrefs MCP** (`mcp__ahrefs__*`) | Per-country traffic distribution; hreflang issues from Ahrefs site audit | `web-analytics-countries`, `site-explorer-metrics-by-country`, `site-audit-issues`. |
| **Semrush MCP** (`mcp__semrush__*`) | Per-database organic visibility (compare `kr`, `jp`, `us`, etc.) | `organic_research` with different `database` params; `siteaudit_research` for site-audit issues. |
| **OurSEO CLI — Naver / per-region SERP** | Korean expansion + regional search engine SERP checks | `our research naver serp`, `our research keywords compare --engines naver`. |
| **WebSearch / WebFetch** | Test geo/Accept-Language redirect behaviour, verify ccTLD handling | Required for redirect-logic audit — can't be done via SEO MCPs. |
| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Per-country SERP fallback when `our` CLI isn't running | `serp_organic_live_advanced` with `location_code` per country. |

### How to pick

1. **User named a backend explicitly** → use it.
2. **User preference memory** — read `feedback_seo_tool_preferences.md`; honor the task-type default.
3. **Task is hreflang validation / parity / fix** → use **OurSEO** (CLI primary, MCP for Desktop). No alternative owns the fix engine.
4. **Task is per-country traffic distribution** → Ahrefs `web-analytics-countries` or Semrush `organic_research` across multiple `database` values.
5. **Task is redirect-logic audit** (IP-based / Accept-Language) → WebFetch with explicit headers.
6. **Default**: **OurSEO crawl + hreflang audit** for the validation work; Semrush MCP for cross-market visibility.
7. **Still ambiguous + non-trivial** → ask once via `AskUserQuestion`.

### Backend call patterns

**OurSEO CLI (default — hreflang validation + fix):**
```bash
our collect crawl https://<site> --max-pages 200
our audit tech https://<site>
our fix hreflang --site https://<site>
```

**OurSEO MCP (Claude Desktop):**
```
mcp__ourseo__crawl_website(url="<site>", max_pages=200)
mcp__ourseo__audit_page(url="<url>", audit_type="tech")
```

**Ahrefs MCP (per-country traffic):**
```
mcp__ahrefs__web-analytics-countries(domain="<site>")
mcp__ahrefs__site-explorer-metrics-by-country(target="<site>")
mcp__ahrefs__site-audit-issues(project_id="<id>")
```

**Semrush MCP (cross-market visibility):**
```
mcp__semrush__organic_research(query="<site>", database="kr")
mcp__semrush__organic_research(query="<site>", database="jp")
mcp__semrush__siteaudit_research(query="<site>", database="us")
```

**Redirect-logic audit (manual):**
```
WebFetch: https://<site>/ with Accept-Language: ko-KR
WebFetch: https://<site>/ with Accept-Language: ja-JP
WebFetch: https://<site>/ with Accept-Language: en-US
# Compare redirect chains; flag forced geo/language redirects.
```

Always record the chosen data source(s) in the report **Overview** so future audits can compare like-for-like.

## Workflow

### 1. Hreflang Validation
1. Fetch target URL and extract hreflang tags (HTML head, HTTP headers)
2. If sitemap provided, also extract xhtml:link hreflang from XML sitemap
3. Validate language codes (ISO 639-1) and region codes (ISO 3166-1)
4. Check bidirectional links (if A references B, B must reference A)
5. Verify self-referencing tags on each page
6. Check x-default tag presence and validity
7. Detect conflicting hreflang for same language-region
8. Report all errors with severity levels

### 2. URL Structure Analysis
1. Crawl known language versions of the site
2. Classify pattern: ccTLD (example.kr), subdomain (ko.example.com), subdirectory (example.com/ko/)
3. Check consistency across all language versions
4. Provide recommendation based on business context

### 3. Content Parity Audit
1. Discover all language versions from hreflang tags
2. Count pages per language version
3. Check availability of key pages (home, about, contact, products/services)
4. Compare content freshness (last modified dates) across versions
5. Flag significant gaps in content availability

### 4. Redirect Logic Audit
1. Test URL with different Accept-Language headers (ko, en, ja, zh)
2. Check if redirects are forced (no way to override) vs suggested (banner/popup)
3. Flag forced geo/language redirects as anti-pattern
4. Recommend proper implementation (suggest, do not force)

### 5. Korean Expansion Analysis (Optional)
1. Analyze current traffic by country via our-seo-agent CLI or pre-fetched data
2. Recommend priority target markets for Korean businesses
3. Check CJK-specific URL encoding issues
4. Advise on regional search engines (Naver, Baidu, Yahoo Japan)

## Output Format

```markdown
## 다국어 SEO 감사: [domain]

### Hreflang 검증
- 검사 페이지 수: [count]
- 오류: [count] (심각 [count], 경고 [count])
- 양방향 링크 누락: [list]
- 자기참조 누락: [list]
- x-default: [있음/없음]

### URL 구조
- 패턴: [ccTLD/subdomain/subdirectory]
- 일관성: [양호/비일관]
- 권장사항: [recommendation]

### 콘텐츠 동등성
| 언어 | 페이지 수 | 핵심 페이지 | 최신성 점수 |
|------|----------|------------|-----------|
| ko   | 150      | 5/5        | 90        |
| en   | 120      | 4/5        | 75        |

### 리다이렉트 로직
- IP 기반 리다이렉트: [있음/없음]
- 언어 기반 리다이렉트: [있음/없음]
- 강제 리다이렉트: [있음/없음] (없어야 정상)

### 종합 점수: [score]/100

### 권장 조치사항
1. [Priority fixes in Korean]
```

## Notion Output (Required)

All audit reports MUST be saved to OurDigital SEO Audit Log:
- **Database ID**: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
- **Properties**: Issue (title), Site (url), Category (International SEO), Priority, Found Date, Audit ID
- **Language**: Korean with English technical terms
- **Audit ID Format**: INTL-YYYYMMDD-NNN

## Limitations

- Cannot detect server-side IP-based redirects without proxy testing
- Content language detection requires sufficient text content
- Large sites (10,000+ pages) require sampling approach
- Sitemap-based hreflang requires XML sitemap access