documentation for integration with gatsby

[jaredh159]

Hi there, I really appreciate all the work on ttag, great library.

I spent a chunk of time yesterday and today trying to figure out how to use ttag with gatsby, and found the documentation a bit hard to follow. I wanted to do pre-compilation, but struggled to adapt the directions for CRA, and manual invoking ttag-cli from the command line (as indicated in the "Getting Started" section) didn't seem to work with the workflow and opinionated build and develop steps of gatsby.

Anyway, after a fair bit of trial and error, I think I figured out how to put the pieces together, and made a simple gatsby starter with basic ttag support. I was wondering about a couple things:

• did I do it right in the above-linked repo? is that the correct way to handle build-time precompilation using the babel plugin?
• would it be worth making a section in your docs somewhere about gatsby integration?
• or maybe showing a simple babel.config.js somewhere in the docs like the one I eventually figured out (if it's correct) might be helpful to someone else trying to grok all the moving pieces.

I also submitted the gatsby starter to get it listed on their website, for anyone else coming along hoping to jump start with a a hello-world gatsby + ttag starter, fwiw.

[AlexMost]

Hi @jaredh159!

Wow, glad that you liked ttag! Firstly I want to thank you for your research!

100% agree, that we should improve ttag doc and add some examples of how to use it with babel-plugin-ttag. Actually, at the very start, the "Quick start" section was without ttag-cli and we added it later just to simplify the first steps.

did I do it right in the above-linked repo? is that the correct way to handle build-time precompilation using the babel plugin

I haven't used gatsby, but at the very first glance - seems like everything is ok.

would it be worth making a section in your docs somewhere about gatsby integration?

That would be just great!

or maybe showing a simple babel.config.js

I think we should add something like that, to show how to resolve translations with babel-plugin-ttag.

Thanks for your feedback! Feel free to report any issues and feature requests.

[jaredh159]

@AlexMost thanks for the response. I'd be willing to take a crack at adding to the documentation, just wondering if you'd give me a little bit of direction how you'd envision any addition so I don't waste my time. For instance, do you think I should add a "Gatsby" sub-page under the "Getting Started" section, as a sibling to the "Create React App" page? Or is that overkill -- should I just add a note or callout on another page somewhere?

And then, with respect to the babel.config.js -- where would you envision placing an example config file like I proposed? The places that seem logical to me would either be under the "Precompiled translations" section at the bottom of the "Getting Started" page, or on the babel-plugin-ttag api page.

[AlexMost]

@jaredh159 it would be great if you will find time to help us with this!

So, as far as I can see, we can place Gatsby in the Getting Started section right after the CRA.

As for the Precompiled translations I think we can put it to the Features section. As it's one of ttag features. We can describe both approaches there (with cli and just with babel-plugin). Also, it would be great to add a couple of reasons why we should choose the precompiled approach (smaller js bundles, no runtime overhead with translations loading e.t.c)

What do you think?

@MrOrz @erickwilder @vharitonsky @alxpy

[oleksandr-kuzmenko]

As for the Precompiled translations I think we can put it to the Features section. :ok_hand: