Updating a translation page shouldn't overwrite the existing translation

[tomasciccola]

This is a follow up to #169

When updating a page content in english, we should have a way of not overwriting the existing translated content in portuguese and spanish. This means that, when generating translations we should:

• check that there's already a translated page
• if that's the case, we shouldn't skip the translation, we should create a new page in the same group in notion, with original-translated-title-{date-of-new-translation}.md push to the content branch repo, and push that version to notion with the language label language-automated (taking care that we put that page having the same parent that every language)
• we should allow content creators to freely delete this newly generated content so that we don't pollute notion with a lot of generated translation pages

Additionally, we should have scripts that allows testing this locally.

• scripts/run-single-page-translation.ts could test that when we run the translation flow again, we don't overwrite the original page, and create a new one in the i18n tree of the repo
• another script scripts/push-new-translation-to-notion that pushes that newly translated content to notion, to test that it puts the new translated page with the right language label and in the correct spot

A page that we can use to test this is ending a project. We could:

• run the run-single-page-translation script, and check that its correctly translated
• edit the english content, run the script again and test that it creates a copy
• run scripts/push-new-translation-to-notion and see that it puts the new translated page with the correct label and location in the notion ui.

We still need to decide if hooking all this up as a workflow should live on this issue, or should be a follow up

[luandro]

Implementation Spec: No-Overwrite Translation Strategy

Problem

When English content is updated and bun run notion:translate runs, existing human-reviewed PT/ES translations are overwritten — createNotionPageWithBlocks() deletes all blocks and recreates them.

Solution

Never overwrite or delete anything. When a translation already exists and English is newer, always create a brand new automated sibling page. Previous automated pages are left untouched — content creators can delete them manually from Notion when no longer needed.

Behavior

Scenario	Current (broken)	New
No existing translation	Create page	Create page (same)
Existing translation, English not newer	Skip	Skip (same)
Existing translation, English newer	Overwrite	Create new automated sibling
Repeat run	Overwrite again	Create another new automated page
Toggle/category section	Overwrite _category_.json	Skip with log

Each run always produces a new page — nothing is ever overwritten or deleted.

Key Design Decisions

1. Language labels: Portuguese-automated / Spanish-automated as new Language select values in Notion (manual prerequisite)
2. Disk output: ./automated-translations/{lang}/{filename}-{YYYY-MM-DDTHHmm}.md — datetime suffix prevents same-day collisions; outside Docusaurus scan, never rendered
3. Notion blocks sidecar: .notion.json saved alongside markdown for the push script (no markdown→blocks converter exists)
4. forceCreate in createNotionPageWithBlocks: Always creates a new page — never searches DB by title+language, never updates, never deletes blocks. Without this, the DB search could match a previous automated page with the same title and accidentally update it.
5. localOnly mode: Filesystem check for existing i18n files replaces Notion API, with deterministic filename fallback when cache absent
6. CI is manual-only: Translation runs are triggered manually, not on a schedule. Each run creates new pages — automatic daily runs would accumulate pages indefinitely.

Pipeline Flow

English page edited → bun run notion:translate
  → findTranslationPage() checks for existing PT/ES page
  → needsTranslationUpdate() returns updateKind

  If no translation exists     → CREATE new page (processSinglePageTranslation)
  If translation empty         → CREATE new page into empty stub (processSinglePageTranslation)
  If translation exists + newer English → ALWAYS CREATE NEW automated sibling
  If translation exists + not newer     → SKIP
  If verification error                 → CREATE NEW automated sibling (safe default)

New Scripts

• scripts/run-single-page-translation.ts — Local test: runs translation, verifies automated files created and originals untouched. Default test page: 2331b08162d58090ab6ad6c1c5f60dda ("Ending a Project")
• scripts/push-new-translation-to-notion.ts — Reads automated translation + .notion.json sidecar, pushes to Notion with correct language label and parent relation

Files Modified

File	Change
scripts/constants.ts	AUTOMATED_OUTPUT_DIRS, helpers (getAutomatedLanguageCode, etc.)
scripts/notion-fetch/pageGrouping.ts	Add "portuguese-automated": "pt", "spanish-automated": "es" to locale map
scripts/notion-translate/translateBlocks.ts	Add forceCreate param — always notion.pages.create(), never update/delete
scripts/notion-translate/index.ts	updateKind discriminant, processAutomatedTranslation(), saveAutomatedTranslationToDisk(), restructured decision logic
.gitignore	Add automated-translations/

Edge Cases Handled

• localOnly mode: Filesystem probe for existing i18n files; deterministic filename fallback when cache absent
• Double suffix guard: getAutomatedLanguageCode() is idempotent
• Notion API v5: Pre-flight validation gated on DATABASE_ID; warns if only DATA_SOURCE_ID
• Block translation: translateNotionBlocksDirectly() called for Notion writes
• Verification errors: Routes to automated path (never risks overwriting)
• Toggle sections: Skipped — _category_.json meaningless outside Docusaurus
• Repeat runs: Always create new page with fresh datetime timestamp — no deduplication, no deletion
• Same-day runs: Datetime suffix (YYYY-MM-DDTHHmm) prevents disk collisions

Prerequisites

1. Add Portuguese-automated and Spanish-automated as select options on the Language property in Notion
2. Test page "Ending a Project" (ID: 2331b08162d58090ab6ad6c1c5f60dda) accessible
3. CI workflow: translation runs must be triggered manually (not scheduled) — each run creates new pages

Verification

• bun test — zero regressions
• Existing translations never overwritten or deleted
• Automated files in automated-translations/, never in i18n/
• Repeat run creates a new page (not updating previous)
• Toggle pages skipped with log
• Push script reads .notion.json sidecar, correct label + parent in Notion