docs: add translation image stabilization specification for issue #137#140
Draft
docs: add translation image stabilization specification for issue #137#140
Conversation
This specification document addresses the problem of expiring Notion/S3 image URLs in translated documentation. It provides: - Technical analysis of the current translation pipeline - Proposed solution integrating existing image processing infrastructure - Detailed 5-phase implementation plan with time estimates - Testing requirements and acceptance criteria - Risk analysis and rollback strategy The solution reuses the existing processAndReplaceImages() and validateAndFixRemainingImages() functions from the notion-fetch pipeline to stabilize image URLs before and after translation. Closes #137 Co-authored-by: openhands <openhands@all-hands.dev>
Updates to TRANSLATION_IMAGE_STABILIZATION_SPEC.md: Per-language image overrides: - Add section explaining default vs override behavior - Document how translators can use localized screenshots - Define precedence rules (language page wins, EN fallback) - Add how-to snippet with before/after example Pipeline improvements: - Add language-aware source selection step in pipeline flow - Update acceptance criteria for localized images Technical clarifications: - Add function contracts section with exact input/output types - Fix line number typo (858-518 → 858-890) - Add invariants section with grep verification commands - Make failure policy explicit (fail page, no placeholders) - Clarify validation catches mutated canonical paths Testing: - Add per-language override test case - Require mocked network/filesystem in tests Cleanup: - Remove time estimates from phases - Reuse existing slug logic (no new implementation) - Expand out-of-scope section (no migration, no new storage) Co-authored-by: openhands <openhands@all-hands.dev>
- Add detailed review of original spec with 17 issues identified - Add simplified spec that's easier to understand (ELI5 style) - Key changes: removed redundant items, fixed fallback behavior, clarified edge cases, added implementation details 🤖 Generated with [Qoder][https://qoder.com]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 tostatic/images/and rewriting URLs.Solution Overview
The specification proposes integrating the existing image processing pipeline into the translation flow:
processAndReplaceImages()to stabilize image URLs before sending to OpenAIvalidateAndFixRemainingImages()as a safety net to catch any remaining S3 URLsThis approach reuses existing, tested code rather than creating new image handling logic.
What's Included
📄
TRANSLATION_IMAGE_STABILIZATION_SPEC.mdcontaining:/images/...paths (reuse EN images) #137)Implementation Plan Summary
/images/pathsAcceptance Criteria (from issue #137)
After implementation, translated markdown will contain:
secure.notion-static.com,notion-static.com,amazonaws.com,X-Amz-*, orwww.notion.so/image//images/<filename>references that resolve at build timeand<img src="...">syntaxTesting
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