Add automated translation stub generation for missing content

[aashishpanthi]

Addresses #1404

Changes

This PR implements stub-file generation for the GSoC 2026 Translation Tracker (#1404). When a new English content files (except references) 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 files inside 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/**/en/** changes (except src/content/references/en/** for now)
  • 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.
• Except reference content only for now; examples, tutorials, etc. have been added via STUB_CONTENT_TYPES.

Test plan

• Verified on fork (aap009/p5.js-website): workflow creates stub PRs when English content files are added
• Checked the workflow dispatch with options from GitHub website
• 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]

left minor comments, overall looks clean

[aashishpanthi]

Thank you for your review. I've fixed the issues and pushed the code.

Thank you!

[aashishpanthi]

Hi @Divyansh013, as discussed in our last call, I checked if the website is breaking when the stub files are merged, it turns out it does break.

I found two issues:

1. MDX compilation error with HTML comments

The stub generator uses HTML-style comments <!-- -->, but MDX files are compiled as JSX by @astrojs/mdx. HTML comments are invalid JSX syntax. The parser throws this error:

Unexpected character ! (U+0021) before name, expected a character that can start a name, such as a letter, $, or _

Fix: Changed stub comments to JSX-style ({/* */}) in workflows.js. Already fixed it.

2. Stub files bypass English fallback, rendering empty content (proposed fix)

The locale fallback logic in src/pages/_utils.ts (getCollectionInLocaleWithFallbacks) only checks whether a localized file exists. It doesn't check whether it contains content that we want. Since stub files are valid MDX (they pass Zod schema validation with title and oneLineDescription present), the fallback system treats them as complete translations and does not fall back to English. This results in pages with empty body content. It looks weird.

Additionally, needsTranslation is not in the Zod schema (src/content/examples/config.ts), so we don't check it.

Proposed fix: Add needsTranslation as an optional boolean to the content schema, then update the fallback logic to treat entries with needsTranslation: true as if they don't exist. It is just like falling back to the English source when the file is missing entirely.

About the second issue, I want to work on the fix and push it here, if that sounds good. Waiting for your approval.