fix(i18n): Spanish translations missing for 8 pages — automation silently failing

[luandro]

What's Happening

The translation automation runs for both Portuguese and Spanish each time the script executes, but for 8 specific pages, something goes wrong when it tries to create the Spanish version — either the pages exist in Notion with a slightly wrong label that the script can't find, or the page creation quietly fails without raising an alarm. Portuguese is generating 36 pages fine, but Spanish is only getting 28, which means those 8 are getting silently skipped.

Confirmed Gap

	Portuguese	Spanish
Generated files	36	28
Content size	134 KB	69 KB
Missing	0	8 pages

Missing Spanish Files

i18n/es/docusaurus-plugin-content-docs/current/customizing-comapeo/building-a-custom-categories-set.md
i18n/es/docusaurus-plugin-content-docs/current/customizing-comapeo/planning-and-preparing-for-a-project.md
i18n/es/docusaurus-plugin-content-docs/current/exchanging-project-data/understanding-how-exchange-works.md
i18n/es/docusaurus-plugin-content-docs/current/exchanging-project-data/using-exchange-offline.md
i18n/es/docusaurus-plugin-content-docs/current/getting-started-essentials/uninstalling-comapeo.md
i18n/es/docusaurus-plugin-content-docs/current/managing-projects/changing-categories-set.md
i18n/es/docusaurus-plugin-content-docs/current/troubleshooting/common-solutions.md
i18n/es/docusaurus-plugin-content-docs/current/troubleshooting/troubleshooting-setup-and-customization.md

What the Automation Does (All Configs Are Correct)

Every config layer is properly set up — constants.ts, docusaurus.config.ts, translate-docs.yml, and the translation loop all include Spanish. The problem is runtime behavior, not configuration.

The script uses a 3-tier lookup (findTranslationPage() in scripts/notion-translate/index.ts:321-425) to find existing Spanish pages in Notion:

1. Tier 1 — Query by Parent item relation + Language = "Spanish"
2. Tier 2 — Fallback: query all pages with Language = "Spanish", match by page ID
3. Tier 3 — Walk Notion block hierarchy for sibling pages

When all 3 return null, the script should create a new Spanish translation. For these 8 pages, creation is either silently failing or errors are swallowed into failedTranslations count.

Most Likely Root Causes

1. Silent failures during Spanish page creation (most likely)

• OpenAI rate limit, Notion write permission, or page-size issue for those 8 specific pages
• Errors are caught and counted as failedTranslations without surfacing in CI

2. Incorrect Language property in Notion for those 8 pages

• Spanish translation pages may exist in Notion tagged with a variant (e.g. "español", "ES", "Spanish (ES)") instead of exact "Spanish"
• All 3 lookup tiers fail the exact string match childLanguage === targetLanguage

3. Missing Parent item relation in Notion

• Spanish pages exist but have no relation to their English source page
• Treated as non-existent → creation attempt fails silently

Verification Steps

Quick diagnostic — run locally and filter output:

bun notion:translate 2>&1 | grep -i "spanish\|es\|fail\|skip\|error"

Check Notion directly for each of the 8 missing pages:

• Does a Spanish sibling page exist?
• Is Language property set to exactly "Spanish" (not a variant)?
• Does it have a Parent item relation pointing to the English page?

Check translation summary — after a run, look for Spanish failedTranslations > 0 vs Portuguese failedTranslations = 0.

Key Files

File	Line(s)	Relevance
scripts/constants.ts	43–56	Language definitions (correct)
scripts/notion-translate/index.ts	103–145	findSiblingTranslations()
scripts/notion-translate/index.ts	321–425	findTranslationPage() 3-tier lookup
scripts/notion-translate/index.ts	493–543	needsTranslationUpdate() create-vs-skip
scripts/notion-translate/index.ts	956–969	Skip-existing guard
.github/workflows/translate-docs.yml	173	Translation CI (no filtering)