Markdown structure and pt-br heading style

[NivaldoFarias]

Summary

Two mechanical quality gaps drive a large share of maintainer churn: broken markdown links after translation, and English-style Title Case on Portuguese headings.

Problem

Markdown links

PR	Issue
reactjs/pt-br.react.dev#1241	Link text left [...] wrapper; like [\errorInfo.componentStack`...](/path)` became broken inline code + bare path

No guard compares link structure between source and translation.

Heading sentence case (pt-br convention)

Maintainers expect sentence case: capitalize the first word and proper nouns only (React, JSX, product names).

PR	Examples
reactjs/pt-br.react.dev#1192	### Frameworks e Bundlers Afetados → sentence case
reactjs/pt-br.react.dev#1183	## Novos Recursos no React Canary
reactjs/pt-br.react.dev#1184	## Compatibilidade com Versões Anteriores
reactjs/pt-br.react.dev#1186	Multiple ## headings (plus separate fence issue)
reactjs/pt-br.react.dev#1188	## Use o React Compiler Hoje
reactjs/pt-br.react.dev#1189	## Novos Recursos do React
reactjs/pt-br.react.dev#1182	#### O Novo Transform JSX... (“novo” should be lowercase)

This batch (reactjs/pt-br.react.dev#1183 – reactjs/pt-br.react.dev#1189) is mostly heading-only fixes; fixing at generation time avoids repeated human edits across blog/release posts.

Proposed direction

1. Markdown link guard

   • For each [text](url) in source, ensure translated output preserves link syntax (balanced brackets, same URL, text may be translated inside brackets).
   • Retry hint with structural fix pattern from #1241.

2. pt-br heading style guard (or analyzer)

   • For lines matching heading patterns (# … ###), flag Title Case Portuguese function words (heuristic: capitalize words after the first except allowlist: React, DOM, JSX, Flight, etc.).
   • Prefer rules in pt-br.locale.ts plus validation; avoid hardcoding every blog title.

3. Prompt

   • Explicit sentence-case rule for pt-br headings in locale rules.specific.

Acceptance criteria

• Guard detects broken link pattern from #1241 (fixture test).
• Guard or analyzer flags at least one Title Case heading from #1188 or #1189 with actionable hint.
• pt-br locale documents sentence-case heading rule.
• False positive rate acceptable on English proper nouns in headings.

Out of scope (for this issue)

• Broad Portuguese grammar checking (Tradução de react-19-upgrade-guide.md para Português (Brasil) reactjs/pt-br.react.dev#1182 “várias desvantagens”, Tradução de react-19-2.md para Português (Brasil) reactjs/pt-br.react.dev#1189 “da renderização”). Rely on human review or future LLM pass; do not block on full grammar NLP here.

References

• src/app/services/translator/validation/guards/
• src/app/locales/pt-br.locale.ts
• pt-br PRs:
  • Tradução de captureOwnerStack.md para Português (Brasil) reactjs/pt-br.react.dev#1241
  • Tradução de critical-security-vulnerability-in-react-server-components.md para Português (Brasil) reactjs/pt-br.react.dev#1192
  • Tradução de react-19-upgrade-guide.md para Português (Brasil) reactjs/pt-br.react.dev#1182
  • Tradução de react-labs-what-we-have-been-working-on-february-2024.md para Português (Brasil) reactjs/pt-br.react.dev#1183
  • Tradução de react-compiler-beta-release.md para Português (Brasil) reactjs/pt-br.react.dev#1184
  • Tradução de sunsetting-create-react-app.md para Português (Brasil) reactjs/pt-br.react.dev#1186
  • Tradução de react-compiler-1.md para Português (Brasil) reactjs/pt-br.react.dev#1188
  • Tradução de react-19-2.md para Português (Brasil) reactjs/pt-br.react.dev#1189