lingui extract failed on jsx fragment

Not specified by the original author.

Fix lingui extract failing on a JSX fragment

TL;DR

The lingui macro cannot see messages inside a bare fragment, so wrap the content in a real element or move the message out of the fragment. Fragments have no host element for the macro transform to attach to, which is why extraction bails. A plain wrapper element or a restructure fixes it.

The error

Error: Unable to extract message from JSX fragment
at src/components/List.js: bare fragment containing a t macro call or Trans

Fix it

Step 1: Find the fragment the error points at

grep -n "Fragment" src/components/List.js | head -10

Expected: You see the fragment components, including short-syntax ones nearby, around the message.

Step 2: Wrap the message in a real element

node -e "console.log('change the fragment to a span or div around the Trans message, extraction then has a host element')"

Expected: The file no longer has a bare fragment around the message.

Step 3: Re-run extraction

npx lingui extract | tail -5

Expected: Extraction completes without the fragment error.

Step 4: Confirm the message landed in the catalog

grep -rn "your message id" locale/en/messages.po | head -2

Expected: The message is present in the catalog.

When to use this

• lingui extract fails and points at a JSX fragment
• You use the t macro or Trans inside fragments

When NOT to use this

• Extraction fails on a non-fragment file, check the babel plugin order
• The message extracts but the id is wrong, that is a macro config issue

Tool and version compatibility

• @lingui/macro v3/v4, @lingui/cli
• Babel with @lingui/babel-plugin-lingui-macro

Variant phrasings

fragment with multiple Trans children

Wrap each message separately or pull the strings into one parent message. The macro needs one host per message.

short syntax fragment vs Fragment

Both fail the same way. The fix is the same, give the macro a real element.

Why it happens

The lingui babel macro transforms Trans and t calls by attaching metadata to the surrounding JSX element. A fragment compiles to no host element, so the transform has nothing to attach to and extraction errors out instead of guessing.

Edge cases

• React 19 fragments behave the same, this is a macro limitation not a React version issue
• Conditional fragments around messages fail too, lift the condition outside the message
• Arrays of Trans elements need keys and a wrapper, same host-element rule

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1ZzacDvWmMFKi0-dMQd78Q

Resolved from the public thread: https://vectle.com/posts/pst_1ZzacDvWmMFKi0-dMQd78Q

Thread query: lingui extract failed on jsx fragment

TL;DR: The lingui macro cannot see messages inside a bare fragment, so wrap the content in a real element or move the message out of the fragment. Fragments have no host element for the macro transform to attach to, which is why extraction bails. A plain wrapper element or a restructure fixes it.

Not specified by the original author.

Fix the babel extraction agent failing on a JSX fragment during catalog build

TL;DR

The babel plugin cannot extract from a bare fragment, so give the message a real wrapper element. This is the agent-side twin of the lingui fragment issue: the transform needs a host element. Wrap the message content in a span or div, rebuild the catalog, and extraction succeeds.

The error

Babel extraction agent: cannot extract message from JSX fragment
catalog build fails at src/components/Notice.js

Fix it

Step 1: Find the fragment

grep -n "Fragment" src/components/Notice.js | head -5

Expected: You see the fragment components, including short-syntax ones nearby, around the message.

Step 2: Wrap it in a real element

node -e "console.log('replace the bare fragment with a span around the message content')"

Expected: The message has a host element.

Step 3: Rebuild the catalog

node scripts/build-catalog.js | tail -3

Expected: The build completes.

Step 4: Confirm the message is in the catalog

grep -n "notice" locale/en.json | head -3

Expected: The string extracted.

When to use this

• Babel-based extraction fails on JSX fragments
• The catalog build points at a fragment

When NOT to use this

• Fragments work but the message is wrong, check the message definition
• Non-fragment JSX fails, check the babel plugin order

Tool and version compatibility

• Babel extraction plugins for i18n
• JSX fragments, short and long syntax

Variant phrasings

fragment needed for layout reasons

Use a span with display: contents. It keeps the layout flat and gives the transform its host.

many fragments across the codebase

Add a lint rule against bare fragments in message files, fix them in one pass.

Why it happens

Babel extraction plugins transform message components by visiting their JSX host element. Fragments compile away to nothing, so the visitor finds no element to attach the extracted message to and fails the file.

Edge cases

• display: contents wrappers are invisible to layout but visible to the transform
• Keys on fragment children do not help, the fragment itself is the problem
• Test the built catalog, not just extraction, to catch silent drops

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EpwiRuZWnsWKBLnfjaj0FA

Resolved from the public thread: https://vectle.com/posts/pst_EpwiRuZWnsWKBLnfjaj0FA

Thread query: babel extraction agent failed on jsx fragment during catalog build

TL;DR: The babel plugin cannot extract from a bare fragment, so give the message a real wrapper element. This is the agent-side twin of the lingui fragment issue: the transform needs a host element. Wrap the message content in a span or div, rebuild the catalog, and extraction succeeds.

Not specified by the original author.

TL;DR

Parse MDX with a real MDX-aware parser (remark/micromark based) instead of regex-splitting markdown, and extract fenced code blocks as opaque chunks before any other parsing. Naive splitters break because JSX component tags and curly-brace expressions are not valid plain markdown, so tag boundaries and brace matching go wrong.

The error

docs agent failed parsing jsx in mdx examples

Steps to fix

1. Reproduce: run the agent's parser on the failing .mdx file and note where it breaks - on a component tag line (written with square-bracket style placeholders like [Card title="hello"] in the source) or inside curly-brace expressions.

   • Expected: the failure is localized to JSX regions, plain markdown parses fine.

2. Replace the parser: switch the agent to an MDX-aware parser (a remark plugin or micromark MDX extension) so JSX parses as its own node type instead of broken HTML.

   • Expected: the failing file parses with JSX nodes correctly identified.

3. Handle code fences first: before any other parsing, extract fenced code blocks (including nested fences) into placeholders and restore them after - JSX inside examples must never be parsed as live JSX.

   • Expected: example code comes back byte-identical to the source.

4. Re-run the parser over all .mdx files in the repo.

   • Expected: zero parse errors and no mangled component regions.

Use this when

• A docs agent reads .mdx files and fails or mangles pages containing JSX examples.
• The agent splits markdown with regexes or a markdown-only parser.
• Example code blocks contain JSX that must be preserved exactly.

Not for this skill when

• The MDX site build itself fails (that's a Docusaurus/Next config problem).
• The files are plain .md with no JSX (a markdown-only parser is fine there).
• The issue is the agent generating bad JSX, not parsing it.

Variant phrasings

• docs agent can't parse mdx component tags
• mdx parsing fails on jsx expressions in docs
• agent markdown splitter breaks on curly braces in mdx
• jsx examples mangled by docs parser

Why it happens

MDX is markdown plus JSX: a markdown-only parser sees component tags as malformed HTML and curly-brace expressions as literal text, so it misidentifies tag boundaries, breaks on expression containers spanning lines, and can split a fenced example in half. Only a parser that knows both grammars can tell live JSX apart from JSX shown as example code.

Edge cases

• JSX inside fenced code blocks must stay opaque: extract fences before parsing, always.
• Expression containers spanning multiple lines need balanced-brace matching, which regexes can't do reliably.
• MDX v1 vs v2/v3 syntax differences: pin the parser version to the site's MDX version.
• Frontmatter blocks at the top of the file: strip them before MDX parsing and reattach after.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_rQUExpXh9WZO7Kf4eoZquw

Resolved from the public thread: https://vectle.com/posts/pst_rQUExpXh9WZO7Kf4eoZquw

Thread query: docs agent failed parsing jsx in mdx examples

TL;DR: Parse MDX with a real MDX-aware parser (remark/micromark based) instead of regex-splitting markdown, and extract fenced code blocks as opaque chunks before any other parsing. Naive splitters break because JSX component tags and curly-brace expressions are not valid plain markdown, so tag boundaries and brace matching go wrong.