Localize executive-brief lead in news HTML + sharpen brief headline tradecraft#2834
Conversation
Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>
Co-authored-by: pethers <1726836+pethers@users.noreply.github.com>
github-actions
Bot
added
documentation
🏷️ Automatic Labeling SummaryThis PR has been automatically labeled based on the files changed and PR metadata. Applied Labels: documentation,testing,refactor,size-l Label Categories
For more information, see |
🔍 Lighthouse Performance Audit
📥 Download full Lighthouse report Budget Compliance: Performance budgets enforced via |
There was a problem hiding this comment.
Pull request overview
Brings the on-page article lead into lock-step with the existing localized SEO cascade: non-English news pages now open with their own-language executive-brief_<lang>.md body (falling back to English when absent), and the 13 inline ## Executive Brief <Lang> carrier sections embedded by the aggregator are stripped for every language — dropping a sample proposition page from ~428 KB to ~307 KB. Localized brief carriers are also excluded from the artifact list so they stop appearing as Reader Guide rows, Article Sources cards, and JSON-LD isBasedOn.
Changes:
- New pure transform
scripts/render-lib/article-brief-lead.ts(carrier strip + lead-body swap reusingcleanArtifactBody+rewriteRelativeLinks, deliberately skippingnormalizeNarrativeTerminology), wired intorenderArticleHtml. - Carrier exclusion in
resolveArtifactListandisReaderGuideEligibleplus 12 unit tests intests/article-brief-lead.test.ts. - Documentation: new "On-page lead localization" section in
Article-Generation.mdand a Headline-tradecraft block inanalysis/methodologies/ai-driven-analysis-guide.md.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/render-lib/article-brief-lead.ts | New pure transform: strip carriers + swap lead body to localized brief |
| scripts/render-lib/article.ts | Wires localizeExecutiveBriefLead into renderArticleHtml |
| scripts/render-lib/aggregator/reader-guide.ts | Excludes executive-brief_<lang>.md from Reader Guide eligibility |
| scripts/render-articles.ts | Excludes localized brief carriers from resolveArtifactList |
| tests/article-brief-lead.test.ts | 12 cases pinning carrier strip, swap, fallback, cleaning, provenance |
| Article-Generation.md | Documents on-page lead localization alongside SEO cascade |
| analysis/methodologies/ai-driven-analysis-guide.md | Adds headline-tradecraft guidance + triple-duty H1 note |
Non-English news pages opened with the English executive brief even when a localized
executive-brief_<lang>.mdexisted, and every page embedded all 13 localized briefs inline as## Executive Brief Sv/De/…carrier sections (a representative proposition page was ~428 KB). The localized brief was only feeding the SEO<title>/<meta description>cascade — never the on-page body lead.This brings the on-page lead into lock-step with that SEO cascade (localized if it exists, English otherwise) and strips the inline carrier bloat.
Changes
scripts/render-lib/article-brief-lead.ts— pure (no-I/O) markdown transform applied byrenderArticleHtmlper language:stripEmbeddedLocalizedBriefSections()removes every## Executive Brief <Lang>carrier for all languages.<h2>lead-section body (## What Happened) is swapped to the cleanedexecutive-brief_<lang>.md— reusing the aggregator'scleanArtifactBody+rewriteRelativeLinkspipeline, deliberately skippingnormalizeNarrativeTerminologyso English first-use glosses never leak into localized prose. Lead heading stays the language-stable English## What Happened(TOC localizes its label separately); provenance comment repoints toexecutive-brief_<lang>.md.scripts/render-lib/article.tsrenderArticleHtml.resolveArtifactList(render-articles.ts) andisReaderGuideEligible(aggregator/reader-guide.ts) now skipexecutive-brief_<lang>.md, so they no longer surface as Reader Intelligence Guide rows (which would dangle once the body carriers are stripped), Article Sources cards, or JSON-LDisBasedOn. They are translations ofexecutive-brief.md, not independent analytical artifacts.analysis/methodologies/ai-driven-analysis-guide.md— added a 🪝 Headline-tradecraft block (named actor + active verb + concrete stake, SERP-safe ≤70 chars, no date-stuffing, localize the angle not the words) and made Step 2B / Step 7 explicit that the brief H1/BLUF is now the on-page lead in every language, not just metadata.Article-Generation.md— documents the on-page lead localization step alongside the existing metadata cascade.tests/article-brief-lead.test.ts— 12 cases: carrier strip across all langs incl. EN, localized swap, EN passthrough, missing/empty fallback, provenance repoint, front-matter/H1 cleaning +##→###demotion, legacy## Executive BriefH2, single-H2 lead.Analysis findings (requested)
article.mdcompleteness: all 22 root analytical artifacts on disk are aggregated (each carries asource:comment) — no valuable content is missing. The sole redundancy was the 13 translation carriers, which are functionally dead weight in HTML (SEO readsexecutive-brief_<lang>.mdfrom disk, not the embedded copies) and are now stripped at render.Notes
sv/ja/ar/en(2026-05-20/propositions): localized lead present, no English leak, zero carriers, ~428 KB → ~307 KB. Sample page renders were reverted — bulk HTML regeneration lands as its own dedicated commit per repo convention, so this PR is code + tests + docs only.