React-i18next: Better Document Trans Component

[s-ol]

Right now it is very unclear which index is needed to reference children and why sometimes nested interpolation-indexes are needed (<0><1>...</1></0>).

It is also not documented how interpolation using {{value}} works and how value names are resolved.

[jamuhl]

Just add your content like used...using saveMissing of backend or own saveMissingHandler in i18next options you will get the string. Don't try to generate those strings manually. https://www.i18next.com/configuration-options.html#missing-keys

[jamuhl]

but overall agree we need to update docs...so i will keep this open until getting time to improve docs on that component

[jeremyboles]

It would great too to see some documentation on using the component with React Native too. Right now it is unclear of the component is even supported there.

[jamuhl]

hm...this will only work with react-dom as we render a div - will need to check if there is some option to find out if we are in react-native so we could render a view instead...

[jamuhl]

@jeremyboles https://github.com/i18next/react-i18next/pull/278 will at least enable to pass own parent for wrapping (so one can pass a View component instead of div). Better option will be on react 16 where we do not have to wrap it at all.

Can you anyway give me a case where Trans component makes sense in react-native - as i remember text content will need to be wrapped into Text component anyway...so not sure if this component makes a lot of sense in the react-native case...

[yoagauthier]

As a farly new user of react-i18next, I'm puzzeled about a few things that maybe the documentation should detail :

• the un-natural look of my JSX code regarding to what's outputed :
  <Trans i18nKey="terms">I accept <Button> Terms & Conditions </Button></Trans>
  JSON : "terms": "I accept <1> Terms & Conditions </1>"
  and
  <Trans i18nKey="terms">I love <Button> Pizza </Button></Trans>
  JSON : "terms": "I accept <1> Terms & Conditions </1>"
  output the same things. You detailed the reasons in #271 but I think it's not clear to a new user.
  What about suggesting a syntax in the docs like :
  <Trans i18nKey="termAcceptance">#<Button>#</Button></Trans>
  For me the syntax of the Interpolate component is clearer, but JSX does not allow to pass opening tags or closing tags alone as props.

• what's the best workflow to produce my JSON with the interpolation indexes ? Set the Trans tag, then testing my app, then copy / pasting the generated output ? This, does not seems optimal, is there any way of guessing the generated output if I want to save time ?

[jamuhl]

What it basically does is replace your text segments with what is specified in the translation -> so if signature of your jsx is the same and the translation is the same - what do you expect? Output for sure will be the same. As both are like you describe: ##

The upside of having the jsx not obfuscated by replacing text with # goes into your question 2 -> set debug: true on init of i18next -> the console will output the new keys not found and for those in trans component in the required form "I accept <1> Terms & Conditions </1>

Same for cases where you use the backends saveMissing (https://www.i18next.com/configuration-options.html#missing-keys) capability -> new keys will be automatically stored on backend. See for example the next.js sample in this repo. Or using http://locize.com to have that automatically.

Or use the handler: https://www.i18next.com/api.html#onmissingkey to do some custom logic

[jamuhl]

Will need to add this to docs - currently on holiday. But will do asap. Or accept PR on docs ;)

[jamuhl]

hope that makes it more clear: https://react.i18next.com/components/trans-component.html#how-to-get-the-correct-translation-strings

Else some help on improving the docs would be really a big help

[oliviertassinari]

Just add your content like used...using saveMissing

This solution might work when translating one language, but it will soon be a problem when handling languages that needs to inverse the structure. Without a clear documentation of the logic behind it, I'm gonna have to reverse-engineer it.

By the way, the For a working sample have a look here. link is broken.

[jamuhl]

As long as you keep blocks together <0>, <1> can be freely moved.

basically <0> is the index of child element in component.

Link was fixed....thank you for reporting.

[oliviertassinari]

@jamuhl Thanks, it starts to make sense.