Docs - Clarify limitations and gotchas for jsxPlaceholderDefaults

Page

https://lingui.dev/ref/conf#macrojsxplaceholderdefaults

Type of Issue

Missing information

Description

Context: https://github.com/lingui/js-lingui/issues/2631#issuecomment-5131146335

The jsxPlaceholderDefaults configuration can define a placeholder for a tag so that <a> becomes <link> instead of <0> for example. This is can be interpreted as multiple <a> generating <link1>...<linkN> etc. However, this is not the case and instead we get an error stating there is a placeholder collision because 2 tags tried to take the name <link>.

Suggested Improvement

Although I would wish the tags incrementally use a counter for <link1>...<linkN>. The library owners preferred not to. Meaning that if I want to have incremental placeholders or whatever, then I should manually tag them.

Fair. I think that's valid, but I think it should be explicitly documented as such rather than being only found out during extraction 😅

I can open a PR, likely later this week for this.

Contribution

• I'd be willing to open a pull request for this.

Start with the referenced https://lingui.dev/ref/conf#macrojsxplaceholderdefaults page and compare its current description with the behavior described in the issue. Document that repeated tags using the same configured placeholder cause a collision rather than automatic incremental names, and note that incremental or distinct placeholders must be added manually.