[GSoC 2026] Add automated translation stub generation for missing reference pages

[aashishpanthi]

Addresses #1404

Changes

This PR implements stub-file generation for the GSoC 2026 Translation Tracker (#1404). When a new English reference page exists without translations, the tracker generates placeholder MDX stubs and opens one PR per language for maintainer review.

Features

Stub generation

• Detects missing translations for reference content (findMissingTranslations)
• Generates stub MDX files from English sources:
  • Copies essential frontmatter (title, module, submodule, file, description)
  • Sets needsTranslation: true
  • Adds a placeholder body and HTML comment linking to the English source
• Opens one PR per language via the GitHub API (blob → tree → commit → branch → pull request)
• Default languages: es, hi, ko, zh-Hans
• STUB_MAX_FILES applies per language (default 50), not as a global cap across all languages

GitHub Actions

• New workflow: .github/workflows/translation-stubs.yml
  • Runs in stub mode (GENERATE_STUBS=true), separate from issue tracking in translation-sync.yml
  • Triggered on push when src/content/reference/en/** changes
  • Supports manual workflow_dispatch with full_scan and languages inputs

Local testing

• npm run test:stubs — dry-run stub generation into stub-preview/ (no PRs, no src/content/ changes)

Code organization
After discussing with Divyansh, I refactored the translation tracker from a single large index.js into focused modules:

File	Re-purposed to
index.js	Entry point and orchestration
constants.js	Supported languages, content types, stub frontmatter keys
utils.js	Path helpers, frontmatter parsing, file scanning
github-tracker.js	GitHub API client (issues, diffs, stub PR creation)
workflows.js	Translation status checks and stub generation logic

Design decisions

• Stub mode and issue-tracking mode are mutually exclusive (GENERATE_STUBS=true returns before issue logic), so PR and issue workflows stay independent.
• Stub PRs are never auto-merged; language stewards and maintainers review them.
• Reference content only for now; examples, tutorials, etc. can be added later via STUB_CONTENT_TYPES.

Test plan

• Verified on fork (aashishpanthi/p5.js-website): workflow creates stub PRs when English reference files are added/changed
• Confirmed up to 4 PRs created (one per language: es, hi, ko, zh-Hans)

PR Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works

To:Do

• Change the branch name in the workflow file to main. I added feature branch for testing.

[Divyansh013]

Hi @aashishpanthi , have added some comments

[Divyansh013]

Minor design inconsistency and not a bug that STUB_CONTENT_TYPES is hardcoded, inconsistent with languages/full_scan which are exposed as workflow_dispatch inputs.
languages and full_scan are parameterized via github.event.inputs, but STUB_CONTENT_TYPES is a hardcoded env value with no corresponding input, so a maintainer wanting to scope a manual run to one content type must edit the YAML.

[Divyansh013]

per-language stub PR creation runs sequentially instead of in parallel.
for (const [language, items] of limitedByLanguage) { ... await githubTracker.createStubPullRequest(...) } awaits each language's PR (blob→tree→commit→branch→PR) one at a time. With up to 4 languages × 50 files each, this adds up unnecessarily since the languages are fully independent; Promise.all over languages would cut wall-clock time roughly 4x. Not new to worry about a timeout, just avoidable latency in a fresh code path.

[Divyansh013]

parseEnvList returns an empty array (not the default) for garbage comma-only input, silently disabling stub generation.
parseEnvList only falls back to defaultList when the raw env value is empty/whitespace. If it's non-empty but garbage (e.g. STUB_LANGUAGES="," or " , "), split(',').map(trim).filter(Boolean) yields []. An empty array is truthy, so the || defaultStubContentTypes fallback at workflows.js:251 never triggers, and there's no fallback at all for STUB_LANGUAGES (workflows.js:248). Since languages/STUB_LANGUAGES is a free-text workflow_dispatch input, a maintainer typo (stray comma/trailing whitespace) causes the action to silently report "No missing translation files found" and exit with zero stubs and no error , not a crash, but a silent no-op that looks like success.