docs: add translation image stabilization specification for issue #137

[luandro]

Summary

This PR adds a comprehensive technical specification document for addressing issue #137 - replacing expiring Notion/S3 image URLs in translated documentation with stable canonical /images/... paths.

Problem

The Notion translation workflow (scripts/notion-translate/index.ts) produces translated Markdown with expiring Notion/S3 image URLs that break over time (~1 hour expiration). Meanwhile, the English fetch pipeline already handles this correctly by downloading images to static/images/ and rewriting URLs.

Solution Overview

The specification proposes integrating the existing image processing pipeline into the translation flow:

1. Pre-translation: Call processAndReplaceImages() to stabilize image URLs before sending to OpenAI
2. Post-translation: Call validateAndFixRemainingImages() as a safety net to catch any remaining S3 URLs

This approach reuses existing, tested code rather than creating new image handling logic.

What's Included

📄 TRANSLATION_IMAGE_STABILIZATION_SPEC.md containing:

• Technical analysis with current vs proposed pipeline flow diagrams
• Key code locations (exact file/line references)
• Implementation design with code examples
• Testing requirements and acceptance criteria (from issue Notion translation pipeline: replace expiring Notion/S3 image URLs with canonical /images/... paths (reuse EN images) #137)
• Risk analysis and mitigations
• 5-phase implementation plan with time estimates (~6-8 hours total)
• Rollback strategy
• Success metrics

Implementation Plan Summary

Phase	Description	Time
Phase 1	Core Integration - Add image processing to translation pipeline	2-3h
Phase 2	Prompt Enhancement - Update OpenAI prompt to preserve /images/ paths	30m
Phase 3	Testing - Create comprehensive test suite	2-3h
Phase 4	Validation - Lint, format, regression tests	1h
Phase 5	PR Creation	30m

Acceptance Criteria (from issue #137)

After implementation, translated markdown will contain:

• ✅ Zero URLs matching secure.notion-static.com, notion-static.com, amazonaws.com, X-Amz-*, or www.notion.so/image/
• ✅ Stable /images/<filename> references that resolve at build time
• ✅ Shared images (no duplication per language)
• ✅ Support for both ![alt](...) and <img src="..."> syntax
• ✅ Idempotent behavior (re-running doesn't cause churn)

Testing

This PR only adds documentation (specification). Testing will be part of the implementation PR.

---

Closes #137

@luandro can click here to continue refining the PR

Greptile Summary

This PR adds four specification/planning documents for issue #137 — stabilizing expiring Notion/S3 image URLs in translated documentation. No code changes are included; this is purely documentation.

• TRANSLATION_IMAGE_STABILIZATION_SPEC.md: Core technical specification proposing integration of the existing processAndReplaceImages() pipeline into the translation flow (pre-translation image download + post-translation S3 URL validation). Code references verified as accurate against the current codebase.
• TRANSLATION_IMAGE_STABILIZATION_PLAN.md: Detailed implementation plan with task-level breakdown, dependency graph, concrete code diffs, and test scaffolding.
• TRANSLATION_IMAGE_STABILIZATION_SPEC_REVIEW.md: Self-review of the spec identifying issues (all resolved in the updated spec). Adds repo root clutter — consider removing or relocating.
• TRANSLATION_IMAGE_STABILIZATION_SPEC_SIMPLIFIED.md: Non-technical summary that largely duplicates the main spec. Consider consolidating.
• Important: The PR description says "Closes Notion translation pipeline: replace expiring Notion/S3 image URLs with canonical /images/... paths (reuse EN images) #137" but this is a docs-only PR — merging will auto-close the issue before the actual implementation is delivered. The Closes keyword should be removed.
• The testing section includes per-language image override tests despite that feature being explicitly deferred to a future enhancement.

Confidence Score: 4/5

• Documentation-only PR with no runtime impact — safe to merge with minor adjustments.
• This PR adds only markdown specification documents with no code changes, so there is zero risk of runtime breakage. The technical content is well-researched and verified against the actual codebase. Deducting one point for: (1) the "Closes Notion translation pipeline: replace expiring Notion/S3 image URLs with canonical /images/... paths (reuse EN images) #137" keyword which would prematurely close the issue, and (2) four new root-level files where two would suffice, adding organizational clutter.
• No files pose runtime risk. The PR description itself needs attention — remove "Closes Notion translation pipeline: replace expiring Notion/S3 image URLs with canonical /images/... paths (reuse EN images) #137" to avoid prematurely closing the issue before implementation.

Important Files Changed

Filename	Overview
TRANSLATION_IMAGE_STABILIZATION_SPEC.md	Well-structured technical specification with accurate code references, clear pipeline diagrams, and thorough risk analysis. Code locations verified against source.
TRANSLATION_IMAGE_STABILIZATION_PLAN.md	Detailed implementation plan with task-level breakdown, dependency graph, and concrete code examples. Test strategy is comprehensive.
TRANSLATION_IMAGE_STABILIZATION_SPEC_REVIEW.md	Self-review document that identified real issues (fallback behavior, validation mismatch). Useful as audit trail but adds to repo root clutter.
TRANSLATION_IMAGE_STABILIZATION_SPEC_SIMPLIFIED.md	Simplified version for non-technical readers. Content is accurate but overlaps significantly with the main spec.

Sequence Diagram

sequenceDiagram
    participant N as Notion API
    participant T as Translation Pipeline
    participant IR as imageReplacer
    participant FS as static/images/
    participant AI as OpenAI API
    participant D as Disk (i18n/)

    Note over T: Current Flow (broken)
    N->>T: Markdown with S3 URLs
    T->>AI: Translate (S3 URLs intact)
    AI->>T: Translated markdown (S3 URLs)
    T->>D: Save (URLs expire in ~1hr)

    Note over T: Proposed Flow (stable)
    N->>T: Markdown with S3 URLs
    T->>IR: processAndReplaceImages()
    IR->>FS: Download images (cached)
    IR->>T: Markdown with /images/... paths
    alt Image download failed
        T->>T: Throw error (fail page)
    end
    T->>AI: Translate (stable paths)
    AI->>T: Translated markdown
    T->>IR: getImageDiagnostics()
    alt S3 URLs found
        T->>T: Throw error (fail page)
    end
    T->>D: Save with stable /images/... paths

Loading

_{Last reviewed commit: 9f73b74}

Context used:

• Context from dashboard - CLAUDE.md (source)

[kiloconnect]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

This PR adds documentation files only (no code changes):

File	Lines	Description
TRANSLATION_IMAGE_STABILIZATION_SPEC.md	715	Main specification document
TRANSLATION_IMAGE_STABILIZATION_PLAN.md	729	Implementation plan with tasks
TRANSLATION_IMAGE_STABILIZATION_SPEC_REVIEW.md	380	Review of the specification
TRANSLATION_IMAGE_STABILIZATION_SPEC_SIMPLIFIED.md	250	Simplified explanation

Total: 4 new files, 2074 lines of documentation

The documentation appears well-structured and comprehensive, covering:

• Problem description and solution approach
• Implementation tasks with dependencies
• Testing requirements
• Acceptance criteria
• Risks and mitigations
• Review feedback with resolutions

Since this PR contains only markdown documentation files with no executable code, there are no security vulnerabilities, runtime errors, or logic bugs to review.

Files Reviewed (4 files)

• TRANSLATION_IMAGE_STABILIZATION_PLAN.md
• TRANSLATION_IMAGE_STABILIZATION_SPEC.md
• TRANSLATION_IMAGE_STABILIZATION_SPEC_REVIEW.md
• TRANSLATION_IMAGE_STABILIZATION_SPEC_SIMPLIFIED.md

[greptile-apps]

_{4 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

PR should not close #137

The PR description says "Closes #137" but this PR only adds specification documents — no code changes. When this PR merges, GitHub will auto-close issue #137 even though the actual implementation hasn't been done yet. The Closes #137 keyword should be removed from the PR description and reserved for the implementation PR that actually delivers the code changes described in this spec.

Context Used: Context from dashboard - CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: TRANSLATION_IMAGE_STABILIZATION_SPEC.md
Line: 441:452

Comment:
**PR should not close #137**

The PR description says "Closes #137" but this PR only adds specification documents — no code changes. When this PR merges, GitHub will auto-close issue #137 even though the actual implementation hasn't been done yet. The `Closes #137` keyword should be removed from the PR description and reserved for the implementation PR that actually delivers the code changes described in this spec.

**Context Used:** Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=56ef855b-65f1-4964-8b62-134035692d00))

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Review document adds root-level clutter

This self-review document is useful as an internal working artifact, but committing it to the repository root alongside the spec adds clutter. The review findings have already been incorporated into the updated spec (as noted in the "Resolution Status" section at the bottom). Consider either:

• Moving this to a context/ subdirectory (e.g., context/development/) consistent with the project structure
• Removing it from the PR and linking to it as a PR comment instead
• Keeping only the spec and plan files, since the review's findings are already reflected in them

Context Used: Context from dashboard - CLAUDE.md (source)

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: TRANSLATION_IMAGE_STABILIZATION_SPEC_REVIEW.md
Line: 1:10

Comment:
**Review document adds root-level clutter**

This self-review document is useful as an internal working artifact, but committing it to the repository root alongside the spec adds clutter. The review findings have already been incorporated into the updated spec (as noted in the "Resolution Status" section at the bottom). Consider either:
- Moving this to a `context/` subdirectory (e.g., `context/development/`) consistent with the project structure
- Removing it from the PR and linking to it as a PR comment instead
- Keeping only the spec and plan files, since the review's findings are already reflected in them

**Context Used:** Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=56ef855b-65f1-4964-8b62-134035692d00))

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Consider consolidating with the main spec

This simplified version largely duplicates information from TRANSLATION_IMAGE_STABILIZATION_SPEC.md. Adding 4 new root-level markdown files for one feature spec is notable — the repo already has IMAGE_URL_EXPIRATION_SPEC.md and NOTION_FETCH_ARCHITECTURE.md as precedent, but neither has companion review/simplified/plan documents alongside them. Consider consolidating the key "simplified" context as a section within the main spec, or moving this to context/development/ to keep the root directory clean.

Context Used: Context from dashboard - CLAUDE.md (source)

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: TRANSLATION_IMAGE_STABILIZATION_SPEC_SIMPLIFIED.md
Line: 1:10

Comment:
**Consider consolidating with the main spec**

This simplified version largely duplicates information from `TRANSLATION_IMAGE_STABILIZATION_SPEC.md`. Adding 4 new root-level markdown files for one feature spec is notable — the repo already has `IMAGE_URL_EXPIRATION_SPEC.md` and `NOTION_FETCH_ARCHITECTURE.md` as precedent, but neither has companion review/simplified/plan documents alongside them. Consider consolidating the key "simplified" context as a section within the main spec, or moving this to `context/development/` to keep the root directory clean.

**Context Used:** Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=56ef855b-65f1-4964-8b62-134035692d00))

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Per-language override tests contradict scope

The spec explicitly defers per-language image overrides to a "future enhancement" (lines 113-116, 451, 689), yet the testing requirements include tests for per-language image override behavior (tests #5 here). These tests would have no implementation to test against in the initial scope. Either remove these test cases from the initial testing requirements, or add a note that they should be written as skipped/todo tests to document the expected future behavior.

Prompt To Fix With AI

This is a comment left during a code review.
Path: TRANSLATION_IMAGE_STABILIZATION_SPEC.md
Line: 388:397

Comment:
**Per-language override tests contradict scope**

The spec explicitly defers per-language image overrides to a "future enhancement" (lines 113-116, 451, 689), yet the testing requirements include tests for per-language image override behavior (tests #5 here). These tests would have no implementation to test against in the initial scope. Either remove these test cases from the initial testing requirements, or add a note that they should be written as skipped/todo tests to document the expected future behavior.

How can I resolve this? If you propose a fix, please make it concise.