lingui extract failed on jsx fragment

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.