Design: Consider _translation.yml for heading-map storage

[mmcky]

Summary

Currently, we store heading-map data in each translated file's YAML frontmatter:

---
title: 介绍
heading-map:
  introduction: "介绍"
  background: "背景"
---

This works well but has some considerations for future development.

Current Approach: Frontmatter heading-map

Pros:

• Self-contained - mapping travels with the file
• Works with file renames/moves automatically
• No additional files to manage
• Already implemented and tested

Cons:

• Adds metadata to every translated file
• Potential (unlikely) conflict if Jupyter Book introduces a heading-map key
• Could rename to x-heading-map to namespace it

Alternative: _translation.yml (Centralized)

Similar to how Jupyter Book uses _config.yml and _toc.yml, we could have:

# _translation.yml
source-repo: QuantEcon/lecture-python
source-lang: en
target-lang: zh-cn

files:
  intro.md:
    heading-map:
      introduction: "介绍"
      background: "背景"
  
  markov.md:
    heading-map:
      markov-chains: "马尔可夫链"

Pros:

• Clean document files (no translation metadata in frontmatter)
• Single place to see all mappings
• Follows Jupyter Book conventions
• Could store additional metadata (last-synced commit, source repo, etc.)
• Easier to inspect/debug all mappings at once

Cons:

• Extra file to maintain
• Must update when files are renamed/moved
• Slightly more complex lookup (file path → mapping)
• Need to handle nested directories

Multi-Language & Bi-Directional Considerations

The current design supports:

1. Multi-language: One English source → multiple targets (zh-cn, es, ja), each target has its own heading-map
2. Bi-directional sync: Can reverse-lookup the heading-map in target files to sync changes back to source

Both approaches (frontmatter vs _translation.yml) support these use cases.

Recommendation

• v0.x: Keep current heading-map in frontmatter (working, tested)
• v1.0: Consider migrating to _translation.yml for a cleaner architecture
• Migration path: Could support both during transition, with _translation.yml taking precedence

Related

• Current implementation: src/heading-map.ts
• Documentation: docs/HEADING-MAPS.md