Improve quickstart documentation

Here’re my notes from Building X with JavaScript series

• add quickstart guide - tutorial is too verbose and README doesn’t say much. In fact, do we have any positive feedback for the React tutorial? I’m thinkng about rewriting it from scratch, but I would like to figure out how to merge/simplify tutorials for various environments, if it’s possible.

• 29:36 - this part breaks my heart 💔. The reason why he copies id and values might be either because he’s speedcoding or simply because he expects such API from working with react-intl. I think we should a) add docs how to use Lingui without macros/plugins b) make it more clear in docs what’s macro and how it looks under the hood or remove it from tutorial completely

• prefer local installation of @lingui/cli, related #273

• ~mention peer dependencies in tutorial (cross-link to @lingui/cli reference)~ It’s actually there, as the 3rd and last step of installation

• write all imports in code examples

• other plural form shouldn’t be considered as a default one. In fact, it shouldn’t be the only required form, because some languages (Polish, Russian) use other plural form for decimal numbers, while one, few, many for integers

• 1:15:02 add note how to figure out plural rules for target language.

Other nice-to-haves:

• add warnings about missing plural forms in development
• upgrade to Babel 7, which should be the default version and provide steps how to use the lib with babel 6.

[tricoder42]

Well, that’s just sad 😄

For me, writing:

<Trans 
  id="See all <0>unread messages</0> or <1>mark them</1> as read." 
  components={[<Link to="/unread" />, <a onClick={markAsRead} />]}
/>

is just more advanced than:

<Trans>
      See all <Link to="/unread">unread messages</Link>{" or "}
      <a onClick={markAsRead}>mark them</a> as read.
</Trans>

…because I need to learn the API and I need to learn the message format.

On the other hand, if I use macros, I don’t have to learn anything (except plurals maybe), because I already know JSX.

Imagine if the macros plugin and CLI worked out of the box and you didn’t spend an hour to set it up? I would rather focus on making the installation and user onboarding right, than recommending more complex variation.

As I said, creat-react-app will soon have macros bundled, next.js have official example using macros, so once other frameworks will catch up, it’ll be much easier to beginners. Also the annoying babel 6/7 situation is making things a bit harder 😕

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.