Pricing

from $0.005 / actor start

Hreflang Tags Auditor

Audit a public page's hreflang alternate tags in one API call. Reports x-default, duplicate and invalid values, self-reference, score, and recommendations for international SEO QA.

Pricing

from $0.005 / actor start

Rating

0.0

(0)

Developer

Sanskar Jaiswal

Actor stats

Bookmarked

Total users

Monthly active users

17 days ago

Last modified

Dockerfile

FROM apify/actor-node:22

COPY package*.json ./
RUN npm --quiet set progress=false && npm install --omit=dev

COPY . ./

CMD ["npm", "start"]

package.json

{
  "name": "hreflang-tags-auditor",
  "version": "0.1.0",
  "description": "Apify Actor that audits public pages for hreflang alternate tag coverage, duplicates, invalid language codes, and SEO localization issues.",
  "type": "module",
  "private": true,
  "main": "src/main.js",
  "scripts": {
    "start": "node src/main.js",
    "test": "node --test test/*.test.js",
    "lint": "node --check src/main.js"
  },
  "dependencies": {
    "apify": "^3.4.5"
  },
  "devDependencies": {}
}

.actor/actor.json

{
  "actorSpecification": 1,
  "name": "hreflang-tags-auditor",
  "title": "Hreflang Tags Auditor",
  "description": "Audit one public page for hreflang alternate tags, x-default, duplicate language targets, invalid values, and localization SEO issues.",
  "version": "0.1",
  "buildTag": "latest",
  "meta": {
    "templateId": "js-start"
  },
  "input": "./input_schema.json",
  "output": "./output_schema.json",
  "storages": {
    "dataset": "./dataset_schema.json"
  },
  "dockerfile": "./Dockerfile",
  "defaultRunOptions": {
    "build": "latest",
    "timeoutSecs": 60,
    "memoryMbytes": 512
  }
}

.actor/dataset_schema.json

{
  "actorSpecification": 1,
  "views": {
    "overview": {
      "title": "Hreflang audits",
      "transformation": {
        "fields": ["inputUrl", "normalizedInputUrl", "status", "ok", "tagCount", "uniqueHreflangCount", "hasXDefault", "score", "grade", "issues", "recommendations", "checkedAt"]
      },
      "display": {
        "component": "table",
        "properties": {
          "inputUrl": { "label": "Input URL", "format": "link" },
          "normalizedInputUrl": { "label": "Normalized URL", "format": "link" },
          "status": { "label": "HTTP status" },
          "ok": { "label": "OK" },
          "tagCount": { "label": "Tags" },
          "uniqueHreflangCount": { "label": "Unique hreflang" },
          "hasXDefault": { "label": "x-default" },
          "score": { "label": "Score" },
          "grade": { "label": "Grade" },
          "issues": { "label": "Issues" },
          "recommendations": { "label": "Recommendations" },
          "checkedAt": { "label": "Checked at", "format": "date" }
        }
      }
    }
  },
  "fields": {
    "inputUrl": { "type": "string" },
    "normalizedInputUrl": { "type": "string" },
    "status": { "type": ["integer", "null"] },
    "ok": { "type": "boolean" },
    "tagCount": { "type": "integer" },
    "uniqueHreflangCount": { "type": "integer" },
    "hasXDefault": { "type": "boolean" },
    "score": { "type": "integer" },
    "grade": { "type": "string" },
    "issues": { "type": "array", "items": { "type": "string" } },
    "recommendations": { "type": "array", "items": { "type": "string" } },
    "checkedAt": { "type": "string" }
  }
}

.actor/input_schema.json

{
  "title": "Hreflang Tags Auditor Input",
  "description": "Enter one public HTTP or HTTPS page URL to audit its hreflang alternate tags for international SEO QA.",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "startUrl": {
      "title": "Page URL",
      "type": "string",
      "description": "Public HTTP or HTTPS page URL to audit. Credentials and private network targets are rejected.",
      "editor": "textfield",
      "prefill": "https://example.com"
    },
    "timeoutSeconds": {
      "title": "Timeout seconds",
      "type": "integer",
      "description": "Request timeout for the page fetch.",
      "editor": "number",
      "default": 10,
      "minimum": 3,
      "maximum": 30
    }
  },
  "required": ["startUrl"]
}

.actor/output_schema.json

{
  "actorOutputSchemaVersion": 1,
  "title": "Hreflang audit output",
  "properties": {
    "results": {
      "type": "string",
      "title": "Hreflang audits",
      "template": "{{links.apiDefaultDatasetUrl}}/items"
    }
  }
}

src/main.js

1import { Actor } from 'apify';
2import dns from 'node:dns/promises';
3import net from 'node:net';
4import { fileURLToPath } from 'node:url';
5
6const USER_AGENT = 'HreflangTagsAuditor/0.1 (+https://apify.com)';
7const MAX_BODY_BYTES = 2_000_000;
8
9function isPrivateIPv4(ip) {
10  const parts = ip.split('.').map(Number);
11  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;
12  const [a, b] = parts;
13  return a === 10
14    || (a === 172 && b >= 16 && b <= 31)
15    || (a === 192 && b === 168)
16    || a === 127
17    || a === 0
18    || (a === 169 && b === 254);
19}
20
21function isPrivateIPv6(ip) {
22  const normalized = ip.toLowerCase();
23  return normalized === '::1'
24    || normalized.startsWith('fc')
25    || normalized.startsWith('fd')
26    || normalized.startsWith('fe80:');
27}
28
29export async function normalizeAndValidateUrl(rawUrl) {
30  if (!rawUrl || typeof rawUrl !== 'string') throw new Error('startUrl is required');
31  if (/^[a-z][a-z0-9+.-]*:/i.test(rawUrl) && !/^https?:\/\//i.test(rawUrl)) {
32    throw new Error('Only HTTP and HTTPS URLs are supported');
33  }
34
35  const withScheme = /^https?:\/\//i.test(rawUrl) ? rawUrl : `https://${rawUrl}`;
36  const url = new URL(withScheme);
37  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Only HTTP and HTTPS URLs are supported');
38  if (!url.hostname || url.username || url.password) throw new Error('URL must be public and must not include credentials');
39
40  const literalType = net.isIP(url.hostname);
41  if (literalType === 4 && isPrivateIPv4(url.hostname)) throw new Error('Private IPv4 targets are blocked');
42  if (literalType === 6 && isPrivateIPv6(url.hostname)) throw new Error('Private IPv6 targets are blocked');
43
44  const records = literalType ? [{ address: url.hostname, family: literalType }] : await dns.lookup(url.hostname, { all: true });
45  for (const record of records) {
46    if (record.family === 4 && isPrivateIPv4(record.address)) throw new Error('DNS resolves to a private IPv4 address; blocked for SSRF safety');
47    if (record.family === 6 && isPrivateIPv6(record.address)) throw new Error('DNS resolves to a private IPv6 address; blocked for SSRF safety');
48  }
49  return url;
50}
51
52function clampInteger(value, fallback, min, max) {
53  const parsed = Number(value);
54  if (!Number.isFinite(parsed)) return fallback;
55  return Math.min(Math.max(Math.trunc(parsed), min), max);
56}
57
58function attrsFromTag(tag) {
59  const attrs = {};
60  for (const match of tag.matchAll(/([\w:-]+)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/g)) {
61    attrs[match[1].toLowerCase()] = match[2].replace(/^['"]|['"]$/g, '').trim();
62  }
63  return attrs;
64}
65
66function extractCanonical(html, baseUrl) {
67  for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
68    const attrs = attrsFromTag(match[0]);
69    if ((attrs.rel || '').toLowerCase().split(/\s+/).includes('canonical') && attrs.href) {
70      try { return new URL(attrs.href, baseUrl).href; } catch { return attrs.href; }
71    }
72  }
73  return null;
74}
75
76export function parseHreflangTags(html, baseUrl) {
77  const tags = [];
78  for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
79    const attrs = attrsFromTag(match[0]);
80    const rels = (attrs.rel || '').toLowerCase().split(/\s+/);
81    if (!rels.includes('alternate') || !attrs.hreflang || !attrs.href) continue;
82    let href = attrs.href;
83    try { href = new URL(attrs.href, baseUrl).href; } catch {}
84    tags.push({ hreflang: attrs.hreflang.toLowerCase(), href });
85  }
86  return tags;
87}
88
89function scoreHreflang({ tags, canonicalUrl, pageUrl, status, error }) {
90  const issues = [];
91  const recommendations = [];
92  let score = 100;
93
94  if (error) {
95    return { score: 0, grade: 'F', issues: [error], recommendations: ['Verify the URL is public, reachable, and returns HTML.'] };
96  }
97  if (!status || status >= 400) {
98    score -= 40;
99    issues.push(`HTTP status is ${status || 'unknown'}`);
100    recommendations.push('Audit a live 2xx HTML page.');
101  }
102  if (tags.length === 0) {
103    score -= 45;
104    issues.push('No hreflang tags found');
105    recommendations.push('Add rel="alternate" hreflang tags for localized page variants when targeting multiple languages or regions.');
106  }
107
108  const byLang = new Map();
109  const invalid = [];
110  const duplicates = [];
111  const page = new URL(pageUrl);
112  for (const tag of tags) {
113    if (tag.hreflang !== 'x-default' && !/^[a-z]{2,3}(-[a-z0-9]{2,8})?$/i.test(tag.hreflang)) invalid.push(tag.hreflang);
114    if (byLang.has(tag.hreflang)) duplicates.push(tag.hreflang);
115    byLang.set(tag.hreflang, (byLang.get(tag.hreflang) || 0) + 1);
116    try {
117      const target = new URL(tag.href);
118      if (page.protocol === 'https:' && target.protocol === 'http:') {
119        issues.push(`HTTP hreflang target for ${tag.hreflang}`);
120      }
121    } catch {
122      invalid.push(`${tag.hreflang}: invalid href`);
123    }
124  }
125
126  if (invalid.length) {
127    score -= 20;
128    issues.push(`Invalid hreflang values: ${[...new Set(invalid)].join(', ')}`);
129    recommendations.push('Use valid ISO language codes, optional region codes, or x-default.');
130  }
131  if (duplicates.length) {
132    score -= 15;
133    issues.push(`Duplicate hreflang values: ${[...new Set(duplicates)].join(', ')}`);
134    recommendations.push('Keep one target URL per hreflang value on a page.');
135  }
136  if (tags.length > 1 && !byLang.has('x-default')) {
137    score -= 10;
138    issues.push('Missing x-default tag');
139    recommendations.push('Add hreflang="x-default" for the default language or country selector page.');
140  }
141  const selfReferences = tags.some((tag) => tag.href === pageUrl || (canonicalUrl && tag.href === canonicalUrl));
142  if (tags.length && !selfReferences) {
143    score -= 15;
144    issues.push('No self-referencing hreflang tag');
145    recommendations.push('Include a hreflang tag for the current page language that points to the canonical URL.');
146  }
147
148  const bounded = Math.max(0, score);
149  const grade = bounded >= 90 ? 'A' : bounded >= 75 ? 'B' : bounded >= 60 ? 'C' : bounded >= 45 ? 'D' : 'F';
150  return { score: bounded, grade, issues: [...new Set(issues)], recommendations: [...new Set(recommendations)] };
151}
152
153async function fetchHtml(url, timeoutSeconds) {
154  await normalizeAndValidateUrl(url.href);
155  const controller = new AbortController();
156  const timeout = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
157  try {
158    const response = await fetch(url, {
159      redirect: 'manual',
160      signal: controller.signal,
161      headers: { 'user-agent': USER_AGENT, accept: 'text/html,*/*;q=0.1' },
162    });
163    const location = response.headers.get('location');
164    if (location && response.status >= 300 && response.status < 400) {
165      const next = new URL(location, url.href);
166      await normalizeAndValidateUrl(next.href);
167      return fetchHtml(next, timeoutSeconds);
168    }
169    const body = (await response.text()).slice(0, MAX_BODY_BYTES);
170    return { status: response.status, finalUrl: url.href, contentType: response.headers.get('content-type') || '', body };
171  } finally {
172    clearTimeout(timeout);
173  }
174}
175
176export async function auditHreflangTags(input) {
177  const startUrl = await normalizeAndValidateUrl(input.startUrl);
178  const timeoutSeconds = clampInteger(input.timeoutSeconds, 10, 3, 30);
179  const checkedAt = new Date().toISOString();
180  let fetched = null;
181  let error = null;
182
183  try {
184    fetched = await fetchHtml(startUrl, timeoutSeconds);
185  } catch (caught) {
186    error = caught.message;
187  }
188
189  const finalUrl = fetched?.finalUrl || startUrl.href;
190  const html = fetched?.body || '';
191  const tags = parseHreflangTags(html, finalUrl);
192  const canonicalUrl = extractCanonical(html, finalUrl);
193  const scored = scoreHreflang({ tags, canonicalUrl, pageUrl: finalUrl, status: fetched?.status, error });
194
195  return {
196    inputUrl: input.startUrl,
197    normalizedInputUrl: startUrl.href,
198    finalUrl,
199    status: fetched?.status || null,
200    ok: !error && fetched?.status >= 200 && fetched?.status < 400,
201    checkedAt,
202    canonicalUrl,
203    tagCount: tags.length,
204    uniqueHreflangCount: new Set(tags.map((tag) => tag.hreflang)).size,
205    hasXDefault: tags.some((tag) => tag.hreflang === 'x-default'),
206    hreflangTags: tags,
207    score: scored.score,
208    grade: scored.grade,
209    issues: scored.issues,
210    recommendations: scored.recommendations,
211    error,
212  };
213}
214
215const isExecutedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
216
217if (process.env.NODE_ENV !== 'test' && isExecutedDirectly) {
218  await Actor.init();
219  try {
220    const input = await Actor.getInput();
221    const result = await auditHreflangTags(input || {});
222    await Actor.pushData(result);
223    await Actor.setValue('OUTPUT', result);
224    Actor.log.info('Hreflang audit complete', { finalUrl: result.finalUrl, score: result.score, grade: result.grade });
225  } finally {
226    await Actor.exit();
227  }
228}

test/main.test.js

1import assert from 'node:assert/strict';
2import { test } from 'node:test';
3import { auditHreflangTags, normalizeAndValidateUrl, parseHreflangTags } from '../src/main.js';
4
5test('blocks non-public and credentialed targets', async () => {
6  await assert.rejects(() => normalizeAndValidateUrl('ftp://example.com'), /Only HTTP/);
7  await assert.rejects(() => normalizeAndValidateUrl('https://user:pass@example.com'), /credentials/);
8  await assert.rejects(() => normalizeAndValidateUrl('http://127.0.0.1'), /Private IPv4/);
9});
10
11test('parses hreflang alternate tags and resolves relative URLs', () => {
12  const tags = parseHreflangTags(`
13    <link rel="canonical" href="https://example.com/en/">
14    <link rel="alternate" hreflang="en" href="/en/">
15    <link href="https://example.com/fr/" hreflang="fr-FR" rel="alternate">
16    <link rel="stylesheet" href="/app.css">
17  `, 'https://example.com/en/page');
18  assert.deepEqual(tags, [
19    { hreflang: 'en', href: 'https://example.com/en/' },
20    { hreflang: 'fr-fr', href: 'https://example.com/fr/' },
21  ]);
22});
23
24test('audits duplicate and missing x-default hreflang issues', async () => {
25  const originalFetch = globalThis.fetch;
26  globalThis.fetch = async () => new Response(`
27    <html><head>
28      <link rel="canonical" href="https://example.com/en/">
29      <link rel="alternate" hreflang="en" href="https://example.com/en/">
30      <link rel="alternate" hreflang="en" href="https://example.com/en-copy/">
31      <link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/">
32    </head></html>
33  `, { status: 200, headers: { 'content-type': 'text/html' } });
34
35  try {
36    const result = await auditHreflangTags({ startUrl: 'https://example.com/en/' });
37    assert.equal(result.tagCount, 3);
38    assert.equal(result.uniqueHreflangCount, 2);
39    assert.equal(result.hasXDefault, false);
40    assert.match(result.issues.join(' '), /Duplicate hreflang values/);
41    assert.match(result.issues.join(' '), /Missing x-default/);
42  } finally {
43    globalThis.fetch = originalFetch;
44  }
45});

Hreflang Tags Extractor

benthepythondev/hreflang-tags-extractor

Extract hreflang alternate tags from international SEO pages.

Ben

Hreflang Tag Validator - Audit rel=alternate hreflang for SEO

scrappy_garden/hreflang-tag-validator

Validate hreflang implementation (<link rel="alternate" hreflang=...>) to prevent international SEO issues. Detects missing/duplicate hreflangs, invalid language-region codes, missing self reference, and optional reciprocal hreflang checks.

Bikram Adhikari

Hreflang Tag Checker — International SEO Audit

q_services/hreflang-tag-checker

Extract and validate hreflang tags from web pages for international SEO audits and monitoring.

Q Services

Hreflang Tag Checker API | SEO Validator

andok/hreflang-checker

Bulk validate website hreflang tags for international SEO. Audit multi-language sites for missing x-default tags, bidirectional errors, and ISO code compliance.

Andok

Canonical & Hreflang SEO Auditor

glowing_glove/canonical-hreflang-auditor

Audit canonical URLs, hreflang annotations, duplicate language targets, and international SEO signals.

Ushba Khan

Canonical Hreflang Auditor

junipr/canonical-hreflang-auditor

Audit canonical and hreflang relationships, reciprocal tags, conflicts, and international SEO risks.

junipr

Canonical/Hreflang Bulk QA

checksmithcats/canonical-hreflang-bulk-qa

Scan public static HTML for canonical and hreflang link-tag signals before launches, migrations, or template changes.

Checksmith Cats

Public Localization & International SEO Signal Agent

jacksu/public-localization-seo-signal-agent

Analyze public pages for hreflang, x-default, HTML language, canonical alignment, language switcher links, locale matrix evidence, and international SEO risks.

jack su

Hreflang Validator

sootesting/hreflang-validator

Validate hreflang international-SEO annotations in bulk — detect missing x-default, broken reciprocal linking, and malformed annotations that cause Google to ignore your localized pages. One clean report per URL. Pay-per-event: $0.01 per batch of up to 200 pages.

soot

Technical On-Page SEO & Meta Auditor

gp005/seo-onpage-auditor

Audit any website's on-page SEO: titles, meta descriptions, H1 tags, canonical URLs, hreflang, Open Graph, Twitter Cards, JSON-LD schema, broken links, image alt text, and robots compliance. Single polite crawl, first-party domains only.