Batch translation can silently skip pages missing Parent item 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.

[luandro]

Update after team feedback:

The earlier Parent item / Sub-item theory now looks too strong. If troubleshooting pages were created through the same button flow as the rest of the content, and every content page already had the expected subpage/container structure and properties, then missing relations are probably not the main explanation here.

The more plausible failure mode is now in translation page discovery / placement, not page eligibility.

Two code paths look especially suspicious:

1. New translated pages are created as database entries, not true Notion child pages.
   The translation code creates pages with parent: { type: "data_source_id" } and then links them back via the Parent item relation, rather than creating them as actual nested page children under the source container.
   Relevant code:

   • scripts/notion-translate/translateBlocks.ts:340
   • scripts/notion-translate/translateBlocks.ts:423

   If the troubleshooting workflow expected translated pages to visibly appear as nested subpages under the same container element, this could make the automation look like it did nothing even if records were created.

2. Existing translation lookup / reuse is not scoped tightly enough.
   When the code does not already have an existingPageId, it queries for an existing translated page by title + language across the whole data source, not by parent/container.
   Relevant code:

   • scripts/notion-translate/translateBlocks.ts:345

   That means common troubleshooting titles could cause the workflow to update or relink an existing translation elsewhere instead of creating a visible new sibling where the team expected it.

There is also a separate skip path where a translation is treated as already up to date if a matching translation page exists and has meaningful content:

• scripts/notion-translate/index.ts:493

So at this point I would reframe the issue as:

• probably not a toggle-content problem
• probably not a missing Parent item data-entry problem if the team confirms those relations existed
• more likely a translation identity / placement mismatch between how source pages are structured in Notion and how the automation creates or reuses translated pages

This investigation is still based on code and history rather than a live rerun against the original troubleshooting batch, but the new feedback makes this revised theory a better fit than the original relation-gap explanation.