localization

审计页面如何声明自己的语言和地区。返回 <html lang> 属性、Content-Language 响应头、全部 rel="alternate" hreflang 链接、从可见文本中实际检测到的语言，以及可选的地理定向 meta，从而看出站点的声明在哪里与实际内容不符。

使用场景

hreflang 审计

列出页面发布的备选语言链接，检查各语言之间的集合是否完整且互相对应。

发现语言标注错误的页面

把 html_lang 与 detected_language 对比。声明为 en 却实际是西班牙语的页面属于真实的 SEO 缺陷，这正是发现它的方法。

竞品语言覆盖

直接从竞争对手的 hreflang 集合中查看他们实际上线了哪些语言，而不是靠 URL 结构猜测。

CI 中的回归检查

部署后断言 language_count 与 is_multilingual，避免损坏的 i18n 构建在缺失一半语言的情况下悄悄上线。

地域定向清点

在整个站点收集 geo.region 与 geo.position meta，看看哪些页面带有区域信号。

本地化响应测试

在请求中发送 Accept-Language 偏好，观察服务器返回的内容是否随之变化。

Endpoint

POST/api/v1/tools/localization

Auth Required

Free 计划 1 req/s

2 credits

Parameters

Name	Type	Required	Default	Description
url	string	Required	-	要审计的页面。必须是有效的绝对 http 或 https URL。 Example: https://example.com/pricing
target_language	string	Optional	-	你期望的语言。会作为请求的 `Accept-Language` 发送并原样回显，同时与检测到的语言和 `html_lang` 比较以得出 `matches_target`。比较是精确匹配，因此 `es` 不会匹配 `es-ES`。 Example: es
target_country	string	Optional	-	你期望的国家/地区。会原样回显，并作为 `X-Country-Code` 请求头发送。该请求头是 CrawlForge 的约定而非标准，多数服务器会忽略它。 Example: ES
detect_language	boolean	Optional	true	从页面可见文本中检测语言。返回 ISO 639-1 代码；文本过短或语言无法识别时返回 `und`。设为 false 时 `detected_language` 始终为 `und`。 Example: true
extract_hreflang	boolean	Optional	true	收集 `rel="alternate"` hreflang 链接。设为 false 时 `alternate_languages` 返回空数组，同时会把 `language_count` 变为 0、`is_multilingual` 变为 false。 Example: true
check_geo_targeting	boolean	Optional	false	读取 `geo.region` 与 `geo.position` meta 标签。不请求时响应中不会出现 `geo_targeting` 对象。 Example: true
timeout	number	Optional	10000	抓取超时（毫秒），取值 1000 到 30000。 Example: 10000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

读取的信号

html_lang

<html> 元素上的 lang 属性——页面自称的语言。不存在时为 null。

content_language_header

Content-Language 响应头。它独立于 HTML，且经常与 HTML 相互矛盾。

alternate_languages

所有 <link rel="alternate" hreflang="…">，按文档顺序返回。x-default 与其他条目一样返回。

detected_language

在剥离 script 与 style 后，对页面可见文本做三元组检测。这是证据，而不是声明。

请求示例

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/localization \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "target_language": "es",
    "check_geo_targeting": true
  }'

响应示例

200 OK420ms

{
  "success": true,
  "data": {
    "url": "https://example.com/pricing",
    "detected_language": "en",
    "html_lang": "en-US",
    "content_language_header": "en-US",
    "alternate_languages": [
      {
        "lang": "en",
        "url": "https://example.com/pricing"
      },
      {
        "lang": "es",
        "url": "https://example.com/es/pricing"
      },
      {
        "lang": "zh-Hans",
        "url": "https://example.com/zh-Hans/pricing"
      },
      {
        "lang": "x-default",
        "url": "https://example.com/pricing"
      }
    ],
    "language_count": 4,
    "is_multilingual": true,
    "target_language": "es",
    "matches_target": false,
    "target_country": "ES",
    "geo_targeted": true,
    "geo_targeting": {
      "region": "US-CA",
      "position": "37.7749;-122.4194",
      "has_geo_meta": true
    }
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 420
}

Field Descriptions

data.detected_language从可见文本中检测到的 ISO 639-1 代码，或 `und`。请与 `html_lang` 对比——不一致就是发现

data.html_lang原样返回的 `lang` 属性，包含地区子标签。页面没有时为 `null`

data.content_language_header`Content-Language` 响应头，或 `null`

data.alternate_languages全部 hreflang 备选项，按文档顺序返回。标签内部的属性顺序无关紧要

data.language_count`alternate_languages` 的长度——不是去重后的语言数量

data.is_multilingual至少找到一个 hreflang 备选项时为 true

data.matches_target当 `target_language` 等于检测到的语言或 `html_lang` 时为 true。这是精确字符串比较，因此 `es` 对 `es-ES` 不成立

data.geo_targeted回显你发送的 `check_geo_targeting` 标志。它不是判定结果——判定请看 `geo_targeting.has_geo_meta`

data.geo_targeting.position原始 `geo.position` 内容，惯例格式为 `纬度;经度`

credits_used每个 URL 固定 2 credits

错误处理

URL 无效（400 Bad Request）

VALIDATION_ERROR。url 为必填且必须能解析为绝对 URL。timeout 超出 1000-30000 也返回同一状态码。

页面过大（413 Payload Too Large）

RESPONSE_TOO_LARGE。页面超过 25MB 读取上限，被直接拒绝而不是缓冲到内存。

目标站点超时（504 Gateway Timeout）

FETCH_TIMEOUT。页面在发送响应体的过程中停止响应。可以调高 timeout，最大 30000 毫秒。

抓取失败（502 Bad Gateway）

FETCH_FAILED。无法读取响应体——连接被重置，或响应体不是可解码的文本。

分析失败（500 Internal Server Error）

TOOL_ERROR。失败的调用不计费；只有审计成功后才会扣除 credits。

被 robots.txt 拦截（403 Forbidden）

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定，可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。

注意： 非 200 的页面同样会被分析而不是拒绝——带有合法 <html lang> 的 404 页面也会返回正常结果。如果你在意状态码，请用 fetch_url 单独检查。

credits 费用

2 credits

每个 URL 2 credits

单页固定价格，与启用哪些信号无关。失败的调用不计费。

包含内容：

提取 <html lang> 与 Content-Language

完整的 rel=alternate hreflang 集合，按文档顺序

对可见文本做三元组语言检测

geo.region 与 geo.position meta 标签

目标语言匹配判定

计划推荐：

Free 计划： 1,000 个一次性试用 credits = 500 个 URL

Hobby 计划： 5,000 credits = 2,500 个 URL（$19/mo）

Professional 计划： 50,000 credits = 25,000 个 URL（$99/mo）

相关工具

map_site

先列出站点 URL，再逐个语言版本审计（2 credits）

analyze_content

检测语言并给出关键词、情感与可读性（3 credits）

extract_metadata

提取 head 中的其余部分——OpenGraph、Twitter、canonical（1 credit）

fetch_url

使用自定义请求头抓取并查看原始响应（1 credit）

准备好试用 localization 了吗？免费注册，获取 1,000 credits，开始构建。

使用场景

hreflang 审计

列出页面发布的备选语言链接，检查各语言之间的集合是否完整且互相对应。

发现语言标注错误的页面

把 html_lang 与 detected_language 对比。声明为 en 却实际是西班牙语的页面属于真实的 SEO 缺陷，这正是发现它的方法。

竞品语言覆盖

直接从竞争对手的 hreflang 集合中查看他们实际上线了哪些语言，而不是靠 URL 结构猜测。

CI 中的回归检查

部署后断言 language_count 与 is_multilingual，避免损坏的 i18n 构建在缺失一半语言的情况下悄悄上线。

地域定向清点

在整个站点收集 geo.region 与 geo.position meta，看看哪些页面带有区域信号。

本地化响应测试

在请求中发送 Accept-Language 偏好，观察服务器返回的内容是否随之变化。

Parameters

Name	Type	Required	Default	Description
url	string	Required	-	要审计的页面。必须是有效的绝对 http 或 https URL。 Example: https://example.com/pricing
target_language	string	Optional	-	你期望的语言。会作为请求的 `Accept-Language` 发送并原样回显，同时与检测到的语言和 `html_lang` 比较以得出 `matches_target`。比较是精确匹配，因此 `es` 不会匹配 `es-ES`。 Example: es
target_country	string	Optional	-	你期望的国家/地区。会原样回显，并作为 `X-Country-Code` 请求头发送。该请求头是 CrawlForge 的约定而非标准，多数服务器会忽略它。 Example: ES
detect_language	boolean	Optional	true	从页面可见文本中检测语言。返回 ISO 639-1 代码；文本过短或语言无法识别时返回 `und`。设为 false 时 `detected_language` 始终为 `und`。 Example: true
extract_hreflang	boolean	Optional	true	收集 `rel="alternate"` hreflang 链接。设为 false 时 `alternate_languages` 返回空数组，同时会把 `language_count` 变为 0、`is_multilingual` 变为 false。 Example: true
check_geo_targeting	boolean	Optional	false	读取 `geo.region` 与 `geo.position` meta 标签。不请求时响应中不会出现 `geo_targeting` 对象。 Example: true
timeout	number	Optional	10000	抓取超时（毫秒），取值 1000 到 30000。 Example: 10000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

读取的信号

html_lang

<html> 元素上的 lang 属性——页面自称的语言。不存在时为 null。

content_language_header

Content-Language 响应头。它独立于 HTML，且经常与 HTML 相互矛盾。

alternate_languages

所有 <link rel="alternate" hreflang="…">，按文档顺序返回。x-default 与其他条目一样返回。

detected_language

在剥离 script 与 style 后，对页面可见文本做三元组检测。这是证据，而不是声明。

curl -X POST https://crawlforge.dev/api/v1/tools/localization \ -H "X-API-Key: cf_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/pricing", "target_language": "es", "check_geo_targeting": true }'

响应示例

200 OK420ms

{
  "success": true,
  "data": {
    "url": "https://example.com/pricing",
    "detected_language": "en",
    "html_lang": "en-US",
    "content_language_header": "en-US",
    "alternate_languages": [
      {
        "lang": "en",
        "url": "https://example.com/pricing"
      },
      {
        "lang": "es",
        "url": "https://example.com/es/pricing"
      },
      {
        "lang": "zh-Hans",
        "url": "https://example.com/zh-Hans/pricing"
      },
      {
        "lang": "x-default",
        "url": "https://example.com/pricing"
      }
    ],
    "language_count": 4,
    "is_multilingual": true,
    "target_language": "es",
    "matches_target": false,
    "target_country": "ES",
    "geo_targeted": true,
    "geo_targeting": {
      "region": "US-CA",
      "position": "37.7749;-122.4194",
      "has_geo_meta": true
    }
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 420
}

Field Descriptions

data.detected_language从可见文本中检测到的 ISO 639-1 代码，或 `und`。请与 `html_lang` 对比——不一致就是发现

data.html_lang原样返回的 `lang` 属性，包含地区子标签。页面没有时为 `null`

data.content_language_header`Content-Language` 响应头，或 `null`

data.alternate_languages全部 hreflang 备选项，按文档顺序返回。标签内部的属性顺序无关紧要

data.language_count`alternate_languages` 的长度——不是去重后的语言数量

data.is_multilingual至少找到一个 hreflang 备选项时为 true

data.matches_target当 `target_language` 等于检测到的语言或 `html_lang` 时为 true。这是精确字符串比较，因此 `es` 对 `es-ES` 不成立

data.geo_targeted回显你发送的 `check_geo_targeting` 标志。它不是判定结果——判定请看 `geo_targeting.has_geo_meta`

data.geo_targeting.position原始 `geo.position` 内容，惯例格式为 `纬度;经度`

credits_used每个 URL 固定 2 credits

错误处理

URL 无效（400 Bad Request）

VALIDATION_ERROR。url 为必填且必须能解析为绝对 URL。timeout 超出 1000-30000 也返回同一状态码。

页面过大（413 Payload Too Large）

RESPONSE_TOO_LARGE。页面超过 25MB 读取上限，被直接拒绝而不是缓冲到内存。

目标站点超时（504 Gateway Timeout）

FETCH_TIMEOUT。页面在发送响应体的过程中停止响应。可以调高 timeout，最大 30000 毫秒。

抓取失败（502 Bad Gateway）

FETCH_FAILED。无法读取响应体——连接被重置，或响应体不是可解码的文本。

分析失败（500 Internal Server Error）

TOOL_ERROR。失败的调用不计费；只有审计成功后才会扣除 credits。

被 robots.txt 拦截（403 Forbidden）

注意： 非 200 的页面同样会被分析而不是拒绝——带有合法 <html lang> 的 404 页面也会返回正常结果。如果你在意状态码，请用 fetch_url 单独检查。

credits 费用

2 credits

每个 URL 2 credits

单页固定价格，与启用哪些信号无关。失败的调用不计费。

包含内容：

提取 <html lang> 与 Content-Language

完整的 rel=alternate hreflang 集合，按文档顺序

对可见文本做三元组语言检测

geo.region 与 geo.position meta 标签

目标语言匹配判定

计划推荐：

Free 计划： 1,000 个一次性试用 credits = 500 个 URL

Hobby 计划： 5,000 credits = 2,500 个 URL（$19/mo）

Professional 计划： 50,000 credits = 25,000 个 URL（$99/mo）