Would appreciate more detailed documentation for <Localized>

[mstange]

I would appreciate some documentation for <Localized> that goes more into specifics. I'm reading https://github.com/projectfluent/fluent.js/wiki/Localized but it's not really answering most of my questions:

• How deep does the replacement magic go? Obviously <Localized>Some string</Localized> works, and so does <Localized><div>Some string</div></Localized>, but how deep does it go?
• Which part of the react children gets replaced by the localized contents? Does it only replace raw strings, and are all "element" descendants preserved, or can it happen that an element descendant gets "localized away"?
• What happens if I have multiple raw strings inside the <Localized> contents, in different descendant elements?
• Can <Localized> components be nested? What happens if I nest them?

[mstange]

• Do the contents of the fallback string have any meaning for the substitution, or are those contents completely irrelevant, except for the case where fallback actually happens? Is it only important to have "some" string that can be replaced?

[zbraniecki]

@stasm @gregtatum @eemeli - can you help here?

[mstange]

It would also be great to see some more complex examples involving vars. For example, can vars only take strings, or could I also do vars={{pref: <code>myprefname</code>}}, i.e. give it a react element? And if so, what would the type annotation in the comment in the ftl file look like?

[stasm]

All great questions, @mstange. I don't have the capacity to edit the docs, but if someone is up for doing it based on the implementation, I'll be happy to support that effort by review a PR.

[eemeli]

• How deep does the replacement magic go? Obviously <Localized>Some string</Localized> works, and so does <Localized><div>Some string</div></Localized>, but how deep does it go?

The replacements only apply to the immediate child, i.e. no deeper than the examples you give.

• Which part of the react children gets replaced by the localized contents? Does it only replace raw strings, and are all "element" descendants preserved, or can it happen that an element descendant gets "localized away"?

This depends on the value and attributes of the message that's referred to by the id prop. If it has a value, then the children of the immediate child of the <Localized> component are entirely replaced by that message value. If the message has attributes, then the attrs prop controls which of those are applied as props of the immediate child component.

• What happens if I have multiple raw strings inside the <Localized> contents, in different descendant elements?

If the message has a value, then they'll all be replaced. If it only has attributes and you use the attrs prop, they'll be applied to the immediate child on the <Localized> component.

• Can <Localized> components be nested? What happens if I nest them?

Sure, there's nothing preventing this. With the proviso that if any of the outer components refer to a message that has a non-empty value, all of its inner components will not be rendered.

• Do the contents of the fallback string have any meaning for the substitution, or are those contents completely irrelevant, except for the case where fallback actually happens? Is it only important to have "some" string that can be replaced?

They do not have any particular meaning in a programmatic sense, so that you're free to use a fallback message that makes sense for your context.

[mstange]

Thank you! That's very helpful.