Batch translation can silently skip pages missing relation

[luandro]

Summary

Investigation of the historical report "Automated translation did not work for the troubleshooting pages" suggests the primary failure mode was not toggle blocks themselves, but the translation pipeline's dependency on the Notion Parent item / Sub-item relation model.

In batch mode, English pages selected for translation can be skipped when they do not have a Parent item relation, even though the job appears to run normally. This matches the reported symptom: translation starts, takes time, but no new translated pages appear.

What we found

Most likely root cause

The batch translation workflow requires Parent item to determine where translated sibling pages should be created in Notion.

Current code path:

• fetchPublishedEnglishPages() fetches all English pages in Ready for translation and expands Sub-item relations without requiring the pages to be top-level first.
• During processLanguageTranslations(), each page is checked for Parent item.
• If Parent item is missing, the page is skipped with a warning instead of translated.
• The same relation is later used to create/update the translated sibling page.

Relevant code:

• scripts/notion-translate/index.ts:268
• scripts/notion-translate/index.ts:913
• scripts/notion-translate/index.ts:1161
• scripts/fetchNotionData.ts:122

Why troubleshooting pages were implicated

The original report suspected troubleshooting pages because they use toggles heavily. After reviewing the code, toggles do not look like the direct blocker for Notion page creation.

The stronger explanation is that those pages were probably modeled in Notion in a way that did not populate the expected Sub-item / Parent item relations for the English pages being batch translated.

Repo guidance already assumes this relation model:

• context/repository-guidelines.md:44

What is probably not the root cause

Toggle blocks themselves are likely a red herring for the original failure.

Current translation block handling:

• recursively fetches and translates nested child blocks
• does not special-case toggles as unsupported
• only skips child_page, child_database, and unsupported

Relevant code:

• scripts/notion-translate/translateBlocks.ts:33
• scripts/notion-translate/translateBlocks.ts:150

There is toggle-specific logic in translation, but it affects localized docs output on disk, not whether translated Notion pages get created:

• toggle sections are saved as _category_.json folders instead of markdown pages
• scripts/notion-translate/index.ts:671

Current status

This looks mostly historical on current main, but the workflow assumption still exists.

What changed:

• On 2026-02-12, commit 05b73dc added explicit handling/tests around missing parent relations and fallback logic for targeted --page-id runs.
• On 2026-03-11, commit 5ff26bf fixed a separate toggle-output issue related to translated toggle labels.

Tests now codify the current behavior:

• missing Parent item in batch mode => page is skipped, non-critical failure
• targeted single-page mode can bypass the parent check and use fallback lookup

Relevant tests:

• scripts/notion-translate/index.test.ts:1529
• scripts/notion-translate/index.test.ts:575
• scripts/notion-translate/index.test.ts:1631

Why this still matters

Even if the original report is mostly addressed, the underlying behavior is still risky:

• batch translation may appear to succeed while skipping eligible content
• the warning is easy to miss operationally
• content editors may not realize that relation modeling in Notion is a hard requirement for translation

Suggested follow-up

Option 1: Improve workflow/documentation

Document more explicitly that pages must be modeled with the expected Sub-item / Parent item relations before batch translation will work.

Option 2: Improve batch translation behavior

Align batch mode with the fallback logic already used in targeted single-page mode:

• attempt translation using page hierarchy / sibling lookup when Parent item is missing
• only skip after that fallback fails
• surface skipped-page counts more prominently in job output

Option 3: Tighten operational feedback

Treat skipped translation candidates caused by missing parent relations as a more visible warning or failure condition in CI / job summaries.

Confidence / limitations

This investigation is based on repository code, tests, and git history. It does not include a live rerun against the original troubleshooting pages in Notion, so the exact historical page modeling has not been directly verified.