## Fixed - **Heading-map injection for new files**: `processFull()` now builds and injects a `translation:` frontmatter block (heading-map + title) into newly translated files. Previously, only section-based updates via `processSectionBased` got heading-maps; new files were missing them. - **`MISSING_HEADINGMAP` false positive for title-only files**: `translate status` no longer flags files with no `##` sections as missing a heading-map. These files have only a title — an empty heading-map is expected. ## Refactored - Moved `buildHeadingMap` from CLI module (`headingmap.ts`) to shared module (`heading-map.ts`) to avoid coupling the Action bundle to CLI-only dependencies. - Added try/catch around heading-map injection in `processFull` so malformed translations fall back gracefully. ## Documentation - Documented language-targeted `\translate-resync` syntax across README, quickstart, action-reference, and FAQ (e.g., `\translate-resync fa` to retrigger only Farsi). ## Tests 976 pass (39 suites) — 4 new tests added.

## What's Changed Fixes #45 — translation PRs are now scoped to the source PR's actual changes, preventing superset accumulation when earlier translation PRs are still open. ### Fixed - **Scope translation PRs to source PR's actual changes**: Unchanged sections missing from target (pending an earlier unmerged translation PR) are now skipped instead of re-translated. Git's 3-way merge combines the PRs when merged independently. Recovery via `/translate-resync` if an earlier PR is abandoned. - **Heading-map corruption when sections are skipped**: `includedSourceSections` array keeps index-alignment with `resultSections` so `updateHeadingMap()` pairs sections correctly. - **Markdown injection in PR body**: Skipped section headings wrapped in backticks to neutralize Markdown syntax. ### Added - **Skipped sections notice**: Translation PRs include a `⚠️ Sections Pending Earlier Translation PR` notice listing which sections were skipped per file. - **`onSkippedSection` callback** and **`skippedSections`** in sync pipeline for tracking skipped sections. - 4 new tests (934 total). **Full Changelog**: https://github.com/QuantEcon/action-translation/compare/v0.12.2...v0.12.3

# translate CLI + Full Resync Pipeline Major release introducing the `translate` CLI — a complete command-line interface for managing lecture translations, including forward resync, backward analysis, review workflows, and repository scaffolding. 18 PRs merged since v0.8.0. Test suite grew from 316 to 879 tests across 39 suites. ## Highlights - **Full CLI** (`npx translate <command>`): status, forward, backward, review, headingmap, doctor, init, setup - **Forward resync**: LLM-powered triage + translation of changed source sections into target languages - **Backward analysis**: Detect untranslated sections in target files by comparing heading maps - **Review pipeline**: Dry-run and interactive review of pending translations - **Repository scaffolding**: `setup` creates target repos with workflows; `init` translates initial lectures - **Source-language support**: Translate from any source language (not just English) via CLI flag or config - **`.translate/` metadata**: Config, heading maps, and per-file state tracking in the target repo - **E2E validated**: Tested against real lecture repos (lecture-python-programming.myst ↔ .fa) ## Added ### CLI Commands - `translate status` — Show sync status of all lectures (with `--write-state` to persist) - `translate forward` — LLM-powered forward resync of changed source sections - `translate backward` — Detect untranslated target sections via heading-map diff - `translate review` — Review pending translations (supports `--dry-run`) - `translate headingmap` — Extract/inject heading maps into target frontmatter - `translate doctor` — Validate `.translate/` metadata, config, and heading maps - `translate init` — Bulk-translate lectures for initial repo setup - `translate setup` — Scaffold a new target translation repo on GitHub with workflows ### Core Features - `resolveSourceLanguage()` — CLI flag > `.translate/config.yml` > default (`en`) - `languageLabel()` helper + `en` added to `LANGUAGE_CONFIGS` - Streaming API support for large document translation (fixes 'Streaming is required' error) - `.translate/` metadata folder: `config.yml`, `heading-map/`, `state/` - Forward triage with explicit examples and safety rules - `getToolVersion()` walk-up strategy for npx environments - Heading-map state sync (section-count update during headingmap runs) ### Tests - **879 tests** across 39 suites (up from 316 in v0.8.0) - 5 snapshots for forward-triage prompt validation - Integration tests for all CLI commands - Headingmap state sync test coverage ## Changed - Heading-map malformed YAML fallback no longer uses hard-coded key allowlist — preserves all unknown frontmatter keys - `--source-language` option defaults to `undefined` (not `en`) to enable proper precedence resolution - CLI renamed from `resync` to `translate` ## PRs Included - #14 chore: condense copilot instructions and add .tmp/ workflow folder - #15 feat: add resync CLI with backward analysis command (Phase 1) - #16 Phase 2: Bulk backward analysis and status command - #17 Phase 3a: JSON schema + ESM migration + ink v4 - #19 Phase 3a: review command — full pipeline + UX polish - #20 Phase 3b: Forward resync command - #21 docs: restructure into user/developer guides with mystmd - #22 docs: document legacy tools, remove tool-alignment and tool-onboarding - #23 feat(cli): rename CLI to translate, add init command with localization rules - #24 Phase 4 refinement + Phase 5b cleanup - #25 feat: Phase 6 — .translate/ metadata folder + GitHub Action integration - #27 Switch to streaming API to fix 'Streaming is required' error - #28 docs: lifecycle tutorials, Phase 7 roadmap with e2e test plan - #30 feat: Phase 7 — Real-World Readiness - #31 fix: E2E testing bugfixes and source-language support

# Sync Orchestrator, PR Creator, Retry Logic ## What's Changed ### Added - **Sync Orchestrator** (`src/sync-orchestrator.ts`): Extracted from `index.ts` — `SyncOrchestrator` class with `Logger` interface for future CLI reuse, `classifyChangedFiles()`, `loadGlossary()`, `FileToSync` and `SyncProcessingResult` interfaces - **PR Creator** (`src/pr-creator.ts`): Extracted PR creation logic — `createTranslationPR()`, `buildPrBody()`, `buildPrTitle()`, `buildLabelSet()`, `PrCreatorConfig` and `SourcePrInfo` interfaces - **Retry Logic**: Exponential backoff retry in `translator.ts` — retries `RateLimitError`, `APIConnectionError`, and 5xx errors; max 3 attempts (1s/2s/4s delays); no retry for `AuthenticationError` or `BadRequestError`; `RETRY_CONFIG` export for testing - **133 new tests** (183 → 316 total, 15 suites): - `inputs.test.ts` (55 tests) — mode, repo format, language, model, PR event validation - `translator.test.ts` (28 tests) — token estimation, glossary formatting, error handling - `sync-orchestrator.test.ts` (26 tests) - `pr-creator.test.ts` (12 tests) - `translator-retry.test.ts` (12 tests) ### Changed - **`index.ts`** rewritten from ~766 to ~447 lines — delegates to `SyncOrchestrator` and `createTranslationPR()` ### Removed - 3 deprecated dead methods from `file-processor.ts`: `findSourceSectionIndex()`, `findTargetSectionIndex()`, `findMatchingSectionIndex()` ### Internal / Docs - CHANGELOG repaired (misplaced `[Unreleased]` section, missing entries backfilled into correct versions)

## What's New ### Fixed - **Test Data Syntax Errors**: Fixed 2 markdown syntax bugs in test fixtures - `19-multi-file-lecture.md`: Fixed malformed heading `####Applications` → `#### Applications` - `23-special-chars-lecture.md`: Fixed mixed fence markers `$$...\`\`\` ` → `$$...$$` - These were the exact errors v0.6.2's validation was designed to prevent! ### Changed - **PR Labels Default**: Simplified from `translation-sync,automated` to `action-translation-sync,automated` - Removed redundant `translation-sync` label in favor of more specific `action-translation-sync` - Cleaned up hardcoded label duplication in index.ts - Labels now sourced solely from `pr-labels` input + source PR labels **Full Changelog**: https://github.com/QuantEcon/action-translation-sync/blob/main/CHANGELOG.md

## What's New in v0.6.1 This release addresses all feedback from human reviewer evaluation of 24 translation PRs. ### Evaluator Improvements - **Focus on Changed Content**: Suggestions now target only modified sections, not unchanged content - **Configurable Max Suggestions**: `--max-suggestions` flag (default: 5, was ~2) - **Markdown Syntax Validation**: "Syntax" as 5th criterion with `syntaxErrors` array and 🔴 markers ### Translator Fixes - **File Rename Handling**: Renamed files now properly handled - Transfers existing translation to new filename - Deletes old file from target repo - Preserves heading-map - **Syntax Rules in Prompts**: Explicit rules for heading space, code/math delimiters ### Other Changes - **Glossary**: Added 2 game theory terms (357 total) - "folk theorem" → "无名氏定理" - "grim trigger strategy" → "冷酷策略" - **Bug Fix**: Changed sections list no longer includes non-existent sections ### Documentation - myst-lint project proposal: QuantEcon/meta#268 **Full Changelog**: https://github.com/QuantEcon/action-translation-sync/blob/main/CHANGELOG.md **Human Review Report**: See issue #4 for complete findings

## 🔧 Critical Bug Fix Fixed heading-map preservation of deeply nested subsections (#### and beyond). ### The Problem Heading-map entries for #### subsections were being deleted during translation. The root cause was duplicate parsing logic: - `parseDocumentComponents()` used a simple 2-level parser (## and ### only) - `parseSections()` had full recursive support (##-######) This meant #### subsections were treated as content instead of structure, preventing them from being added to heading-maps. ### The Solution Refactored `parseDocumentComponents()` to call `parseSections()` internally: - ✅ Eliminated duplicate parsing logic (DRY principle) - ✅ Full recursive support for all nesting levels - ✅ Single source of truth for parsing ### Impact - **All 140 tests passing** ✅ - **No breaking changes** - pure bug fix - **Bundle size**: 1941kB (unchanged) - **Test coverage**: Added 6 tests for #### and ##### changes ### Files Modified - `src/parser.ts` - Unified parser implementation - `src/file-processor.ts` - Removed 44 lines of debug logging - `src/heading-map.ts` - Removed 7 lines of verbose logging - `package.json` - Version bump to 0.4.10 ### Verification Verified in GitHub test PR #316 (Real-world lecture update): - Heading-map correctly includes `Vector Spaces::Basic Properties::Applications in Economics: 在经济学中的应用` - Document structure preserved at all nesting depths ### Documentation - 📄 [Full Release Notes](https://github.com/QuantEcon/action-translation-sync/blob/main/docs/releases/v0.4.10.md) - 📄 [Status Report](https://github.com/QuantEcon/action-translation-sync/blob/main/docs/STATUS-REPORT.md) --- **Full Changelog**: https://github.com/QuantEcon/action-translation-sync/compare/v0.4.7...v0.4.10

# Release v0.4.3 - Subsection Support Complete **Release Date**: October 18, 2025 **Status**: Production-Ready ✅ **Focus**: Complete subsection handling with comprehensive testing --- ## Overview v0.4.3 completes the subsection support feature initiated in v0.4.0. This release fixes the final critical bug (subsection duplication) and includes comprehensive regression testing to ensure all subsection-related functionality works correctly. **Key Achievement**: Subsections (`### Subsection`) are now fully supported - parsed from translated content, integrated into heading-maps, and reconstructed without duplication. --- ## What's New ### 🐛 Bug Fixes #### Subsection Duplication Bug (Critical) **Problem**: Subsections were being duplicated when processing documents multiple times. **Root Cause**: In `extractSectionsWithSubsections()`, the subsections array was being referenced rather than cloned, causing mutations to affect the original data. **Solution**: ```typescript // Before (buggy) section.subsections = subsections; // After (fixed) section.subsections = subsections.map(sub => ({ ...sub })); ``` **Impact**: Documents now reconstruct correctly with no duplication, even when processed multiple times. ### ✅ Testing **New Regression Tests**: 10 tests added (87 total, all passing) **Test Suite 2: Document Reconstruction** (5 tests) - Should parse subsections from translated content - Should handle sections with no subsections - Should handle empty translated content - Should extract correct subsection headings and content - **Should not duplicate subsections when processing multiple times** ⭐ (regression test) **Test Suite 3: Heading-Map Integration** (5 tests) - Should include subsections in heading-map - Should handle sections without subsections in heading-map - Should handle mixed sections (some with/without subsections) - Should preserve subsection order in heading-map - Should update heading-map with subsections from translated content **Coverage**: All subsection functionality thoroughly tested with realistic scenarios. --- ## Complete v0.4.x Series The v0.4.x series was a focused effort to add full subsection support: ### v0.4.0 (November 2024) - **Discovery**: Heading-map incomplete - missing subsections - **Analysis**: Subsections not being extracted from translated content - **Feature**: Heading-map system with automatic population ### v0.4.1 (December 2024) - **Implementation**: `parseTranslatedSubsections()` function - **Feature**: Extract subsections from translated section content - **Issue**: Subsections not appearing in heading-map ### v0.4.2 (December 2024) - **Fix**: Recursive processing in `updateHeadingMap()` - **Feature**: Subsections now added to heading-map - **Issue**: Subsections duplicated in output ### v0.4.3 (October 2025) ✅ - **Fix**: Deep clone subsections to prevent duplication - **Testing**: 10 comprehensive regression tests - **Result**: Subsection support complete and production-ready --- ## Technical Details ### Architecture Changes **No breaking changes** - all improvements are internal bug fixes. **Modified Functions**: 1. `extractSectionsWithSubsections()` - Deep clone subsections array 2. Test suite - Added 10 regression tests **Heading-Map Behavior**: - Now correctly contains 15 entries (10 sections + 5 subsections) - Previously only had 10 entries (sections only) - Maintains flat structure for all headings ### Performance Impact **No performance changes** - the deep clone operation is negligible (typically 5 subsections per section). --- ## Validation Results ### Test Repository Validation **Test Document**: `lectures/example.md` - **Sections**: 10 (`## Section`) - **Subsections**: 5 (`### Subsection`) - **Heading-Map Entries**: 15 ✅ - **Duplication**: None ✅ - **Processing**: Multiple runs produce identical output ✅ ### Real-World Testing **Status**: Ready for production use with QuantEcon lecture repositories - All core features working - No known bugs - Comprehensive test coverage --- ## Migration Guide ### Upgrading from v0.3.0 or earlier **No changes required** - v0.4.3 is fully backward compatible. Your existing workflow will automatically benefit from: - Subsections now tracked in heading-maps - More accurate cross-language section matching - No duplication issues ### Upgrading from v0.4.0-v0.4.2 **No changes required** - bug fixes only. If you experienced subsection duplication in v0.4.0-v0.4.2: - This is now fixed in v0.4.3 - Simply upgrade and the issue will be resolved --- ## Testing the Release ### Quick Test ```yaml - uses: quantecon/action-translation-sync@v0.4.3 with: target-repo: 'your-org/your-repo.zh-cn' target-language: 'zh-cn' anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} ``` ### Verify Subsection Handling Check the translated document's frontmatter heading-map: ```yaml --- kernelspec: ... heading-map: 'Introduction': '简介' 'Background': '背景' 'Theory': '理论' 'Mathematical Framework': '数学框架' # subsection 'Assumptions': '假设' # subsection ... --- ``` You should see both sections (`##`) and subsections (`###`) in the heading-map. --- ## Documentation Updates ### Updated Documentation - ✅ **IMPLEMENTATION.md** - Comprehensive rewrite with subsection handling details - ✅ **TESTING.md** - Consolidated guide (1197→413 lines) - ✅ **ARCHITECTURE.md** - Added subsection support explanation - ✅ **STATUS-REPORT.md** - Current status (362→143 lines) - ✅ **TODO.md** - v0.4.3 complete, v1.0 roadmap - ✅ **INDEX.md** - Clean structure, 12 core docs ### Cleaned Up - Removed temporary validation/regression test documents - Removed historical archive - All docs reflect current v0.4.3 state **Total**: 12 focused documentation files --- ## Known Issues **None** - All known bugs from v0.4.0-v0.4.2 are fixed. --- ## What's Next ### v1.0 - API Stabilization **Focus**: Freeze public interfaces, guarantee backward compatibility **Timeline**: Q1 2026 (pending production validation) **Requirements**: - 95%+ test coverage (currently ~85%) - Real-world validation with QuantEcon lectures - Performance benchmarks - API documentation freeze - Semantic versioning commitment ### v1.1+ - Feature Enhancements **Planned Features**: - Additional languages (Japanese, Spanish) - Custom glossaries per repository - Translation memory/caching - Performance optimizations - Quality metrics --- ## Contributors - Development: QuantEcon Team - Testing: Comprehensive automated test suite - Documentation: Complete review and cleanup --- ## Resources - **Documentation**: [docs/INDEX.md](../INDEX.md) - **Implementation Guide**: [docs/IMPLEMENTATION.md](../IMPLEMENTATION.md) - **Testing Guide**: [docs/TESTING.md](../TESTING.md) - **Status Report**: [docs/STATUS-REPORT.md](../STATUS-REPORT.md) - **Repository**: https://github.com/quantecon/action-translation-sync - **Issues**: https://github.com/quantecon/action-translation-sync/issues --- ## Changelog ### Added - 10 new regression tests for subsection handling (87 total tests) - Comprehensive test coverage for document reconstruction - Comprehensive test coverage for heading-map integration ### Fixed - **Critical**: Subsection duplication bug in `extractSectionsWithSubsections()` - Subsections now correctly cloned instead of referenced ### Changed - Documentation cleanup (removed archive, consolidated files) - STATUS-REPORT.md reduced by 60% (362→143 lines) - All docs updated to reflect v0.4.3 ### Removed - Historical archive folder - Temporary validation and test tracking documents --- **Full Changelog**: [v0.3.0...v0.4.3](https://github.com/quantecon/action-translation-sync/compare/v0.3.0...v0.4.3) --- **Released**: October 18, 2025 **Status**: ✅ Production-Ready