Documentation & getting started - Community feedback

[Vadorequest]

This thread is meant for the community to share their feedback regarding how to get started with the boilerplate, and how the documentation should be improved in order to make it easier.

Lots of documentation has been written, both in markdown files (README, etc.) and as in-code comments. About 2h of video tutorial has been recorded as well, so that you don't get stuck when trying out this project for yourself, but I know there is a lot of things to understand, lots of third parties, lots of configuration as well, and all this is likely overwhelming.

If you could share what you've struggled to understand, where you got stuck, it would help us improve the documentation and ease the process for everyone. Contributions are also welcome!

[sjsakib]

I wanted to understand how the i18next integration works. How is the i18nextInstance passed to react? It seems to be passed to the Layout component, but the Layout component never uses it. So how does this work?

[Vadorequest]

Hi @sjsakib, interesting question!

The i18nextInstance isn't necessary to perform translations actually, it's forwarded as a utility.

See https://github.com/UnlyEd/next-right-now/blob/master/src/components/Layout.tsx#L416, that's where the Layout component passes down to the react tree the i18nextInstance defined in https://github.com/UnlyEd/next-right-now/blob/master/src/pages/_app.tsx#L172

Manipulating the i18nextInstance is not often necessary, using import { Trans, useTranslation } from 'react-i18next'; is what you'll need most of the time when translating content.

---

Another way of providing the i18nextInstance would be to use https://react.i18next.com/latest/i18nextprovider i18nextprovider, but I've done it differently. I'm not sure what difference those two approaches may imply.

[jamuhl]

all the react-i18next components need to access an i18next instance to get a t function, load translations,...

In most cases using i18next.use(initReactI18next) is sufficient -> basically using that plugin does nothing but passing the i18next instance to react-i18next.

When do you need the I18nextProvider?

• When you got serverside scenarios -> eg. in express there will be a cloned i18next instance per request asserting all async operations during the request use that clone which is bound to one language (using the singleton would result in concurrency issues with mixed languages)
• When you like to use multiple instances on clientside (there are a few large projects I know of doing this)

[Vadorequest]

Thanks @jamuhl for your feedback, I was also wondering how the t function was linked to i18next because I don't use the i18nextProvider.

But it's clear now that it's because of i18nInstance.init() at

next-right-now/src/utils/i18nextLocize.ts

Line 369 in 3458fa3

map(plugins, (plugin) => i18nInstance.use(plugin));

, that's where we configure i18next, and that's how later use of t or Trans can use the translations that had been loaded previously.

[sjsakib]

Thanks a lot guys.

So, is the i18next instance getting initialized anew with every page transition in the client?

[Vadorequest]

I would say it does. A new page refresh (SSR) would definitely initialise the i18nextInstance, but a CSR would also initialise it. But, that doesn't mean it will fetch translations again, because of caching mechanisms that are built-in with the i18nextLocize implementation.

A lot of efforts have been made to avoid over-fetching, and if that's your concern you can see that no additional network request is performed toward Locize provider when navigating on the client side. Feel free to test and confirm that it works properly on your side! :)

[joshualinog]

issues i can create a pull request for .... later

I'm currently working on a branch that just deals with typos in the documentation, but I thought maybe this was a space to enumerate "non-typo" issues that could be fixed later.

• broken vendor link on home page
  
  probably needs to point to this /reference/vendors

[Vadorequest]

Good catch! Fixed through b2acea1