Documentation improvements

[amannn]

• [x] Make sure all used functions are imported in the code samples (focus on copy-pasting)
• [x] Add a table of contents for quick scanning
• [x] A standalone website
• [x] Potentially a separate example that shows just the basic hello world setup and another one showing more advanced features
• [x] Live examples
• [x] Clarify which polyfills are needed and under which conditions
• [ ] Inline examples with sandpack?
• [ ] Consider more examples or linking more to examples from the docs.
• [ ] Avoid external links if not really necessary

[andrevenancio]

So maybe a good thing would be to have a couple of examples pointing to codesandbox or similar so users can pick up specific tasks.

1. Could be the basic example for setup the basic
2. Could be some examples about time formatting (2 hours ago) potentially linking for the "in browser feature" you mention on #70 so people can read further.
3. another example could be on how to pass the now from the server to _app.ts At least with me when I look at a "new library" its always nice to have a working advanced example instead of just code snippets. Just a suggestion :)

[amannn]

Thank you for the feedback and I'm incredibly grateful for your sponsorship! ❤️❤️❤️

I really like your idea with CodeSandbox, as it could lower the barrier to try out the APIs. I've started working on a proper docs website, maybe I can embed sandboxes there or alternatively link to them to try out different features.

Thank you again for supporting the project! 🙂

[andrevenancio]

My pleasure. this is a great library, and you've been very kind with your enourmous patience guiding me through this issues and some others in the past!

Just expanding on the examples. One thing I'm very happy with on my particular project is the ability to toggle between english and in my case german. I think if the examples have some sort of shared footer or something users can change the language then they can see how powerful this library really is. For example your "2 hours ago" in german becomes "vor 2 Stunden" without me doing anything. So if the examples have a way of toggling a language I think it will be more aparent to users the full potential of this library.

[amannn]

The example in this repo already has such a switch:

https://github.com/amannn/next-intl/blob/1571b78688fa2735011b2170e7811e83fd574204/packages/example/src/components/Navigation.tsx#L21-L23

Is it maybe too subtle or is it rather the problem that the example has to be built locally?

[andrevenancio]

I think the latter! If you have it on an embbeded example people could quickly glance it will be easier to spot. Maybe instead of one big example, you could have smaller more targeted examples.

[Haschikeks]

Hey there first of all great library, ty 😀

While checking the example (especially the advanced) I noticed, that the implementation is not consistent. For example in the about.tsx you use getServerSideProps and in the index.tsx you use getStaticProps. Is this by design to show both cases?

Similar the lodash.pickimport is different. I would just look nicer if it was consistent. 😉

[amannn]

Thanks for the hint @Haschikeks! I've just set up a PR to unify the lodash imports (https://github.com/amannn/next-intl/pull/82).

The usage of getServerSideProps is intentional:

https://github.com/amannn/next-intl/blob/ac5b83eb64e6d52bd7706480119e0d6541d5552e/packages/example-advanced/src/pages/about.tsx#L33-L36

[Haschikeks]

The usage of getServerSideProps is intentional:

Ah yeah okay I see, my bad.

Thanks for the hint @Haschikeks! I've just set up a PR to unify the lodash imports (#82).

Thank you 🥰

[amannn]

Small docs update: There's now a page that provides instructions for runtime requirements and polyfills.

[santyas]

@amannn how do you use it in app directory?

[amannn]

@santyas The polyfills? Just as shown here: https://next-intl-docs.vercel.app/docs/production-checklist#runtime-requirements. But definitely verify if you need any polyfills at all, depending on the browsers you support.

[santyas]

@amannn right, polyfills. So I tested it on Safari 13 in Catalina OS, in case of using app directory as I mentioned, it's necessary to import it on a layout file instead of "custom _app" as the docs mentions.

Another important thing is to import that component inside the NextIntlClient Provider of the layout file, and add 'use client' (on the component) in case you want to use the hook useLocale() to get the {locale}.

My example: https://github.com/santyas/next-intl

[amannn]

We have many more links to examples now in the docs, and with that, the list from the top of this issue is quite complete. I'll close this issue therefore.

We now also have a new template for docs improvements—feel free to use that in case you find that something can be improved!