Translating the Tutorial (and, maybe, Docs)

Get Involved Docs & Content Translations
61

How’s this feeling? Think it’ll work with what we’re doing now with redwoodjs.com → fr.redwoodjs.com?

It is new territory for me too - I’m not sure how to programatically make the PR once the webhook has detected a push change in main English repo.

Still have more to learn, haven’t given up yet!

Are you getting cold feet on the entire-site-repo idea??

No! :slight_smile: I was revisiting the “mycelium” middleman repo idea for docs because I got stuck on the webhooks.

Since the build.js script fetches some docs from github, I thought why not keep all the docs in on separate repo where gitlocalize can manage the sync against the source content. The language repos would essentially become site building machines tuned to fetch their respective languages.

I made a little sandbox here of a docs middleman repo that redwoodjs.com, fr.redwoodjs.com, ja.redwoodjs.com etc. could pull from during the build process.

The content translations are managed in git localize here

Gitlocalize marks translations as incomplete if content in sorresponsing source file changes or new ones are added.
image

Then I modified the build.js file for a hypothetical ja.redwoodjs.com repo that contains the cameronjs-y magic for building a redwood site. Only difference is it sources it’s content from the mycelium repo. BASE_PATH is the path for translated content, FALLBACK_PATH is the path for English content.

https://github.com/clairefro/redwoodjs.com/compare/main...clairefro:ja-test#diff-1ae50dc56d6f821fbc0183fc424426e7cf420c9f5e0a0a5fd0e1801a573b8fd0

Lots of hairiness still as I notice the docs are sourced from multiple places and can be difficult to decouple for build. Also takes manual updates to include new translations.

ANYWAY, was just trying it out to compare methods. I will continue to explore the webooks method (if anyone is good at github webhooks do get in touch!)

2 Likes
62

I’ve had a breakthrough. Have you heard of Pipedream? It’s a free serverless API integration tool that’s making the auto pull request thing look possible.

Testing it out by trying to sync pushes made to a repo called dummy-main as PRs to a language repo called dummy-es. Still haven’t gotten the cross-repo thing working but close…

1 Like
63

As Christopher pointed out on call today, Gatsby has a robust community translation mechanism in place for docs.

I popped a message in their localization channel on discord to see if we can’t get some sage advice on what’s working for them
https://discordapp.com/channels/484383807575687178/624540311435214859/771801116966780948

1 Like
64

Good move, thanks!

1 Like
65

it looks like gatsby is doing a “mycelium” :smiley:

66

:smiley: :mushroom: :mushroom: :mushroom:

Looks like it’s made for i18n in the framework itself.
Can be something to keep in mind for the future.

67

Following our last meeting on Zoom, we spoke briefly on “what to translate” and “how many target languages should we start”.

This is what did Storybook:

image
image1261×60 5.5 KB

They created a separate part for tutorials (as redwood) but pointing to a dedicated website (learnstorybook.com).
Documentation remains on the main website
Tutorial is translated, while documentation is not.

image
image1290×90 4.86 KB

https://www.learnstorybook.com/intro-to-storybook/react/en/get-started/
https://www.learnstorybook.com/intro-to-storybook/react/es/get-started/
https://www.learnstorybook.com/intro-to-storybook/react/fr/get-started/
etc…

Our tutorial (soon 2.0 :slight_smile: ) is already quite long and is widely acknowledged to be well done.
Also it will probably become one of the most stable part of the website at some point.

Maybe we could follow this idea, create a kind of “learn redwood” website, and focus on having a first class introduction to the framework. Adding translations would occur only on this specific perimeter, less prone to be constantly updated over the time.

A bonus would also be to not alter SEO performance of the main redwoodjs.com website, while preventing to mix untranslated part in english with other languages in the translations (at this moment we need to translate the whole website, documention and recipes)

68

I love this idea - it allows us to limit the scope of content needing translation while also keeping SEO clean.

What do you think about trying this, and initially limiting the scope to just the long tutorial doc?

learnredwood.com/en/tutorial/welcome-to-redwood
learnredwood.com/en/tutorial/prerequisites

learnredwood.com/fr/tutorial/welcome-to-redwood
learnredwood.com/fr/tutorial/prerequisites
etc…

With a repo structure that has language namespaces for docs, something like

docs/
    en/
      TUTORIAL.md
    fr/
      TUTORIAL.md
    ja/
      TUTORIAL.md
...

^ Structuring docs like this would allow us to use Gitlocalize automating staleness checks against the docs in en/

So the only syncing we would need to code is listening for changes in redwood/redwoodjs.com repo’s TUTORIAL.md to update the learnredwood English TUTORIAL.md

I’m tempted to try building a learnredwood site like you mentioned with cameronjs , but I’m more familiar with builds and localization with Gatsby. Would you have a preference in which site generator to use?

69

Testing out a “learn redwood” style site with Gatsby

70

:+1: Prevent staleness on the long run is key

Not particulary, but I guess @Founders probably have one

In the meantime, I continue to translate TUTORIAL.md to FR (30% done at this moment)

71

Interestinggggggg This would simplify things all around if we started from “scratch” with a new URL and only worried about translating that, a subset of all the docs in existence. And we can build it out from scratch with i18n in mind and not try to hack something together like we’re doing now.

Could we even have the english tutorial live at learnredwood.com and just have the main site link over to it?

And it sounds like gitlocalize could be the one worrying about notifying translators when the English version changes?

72

Could we even have the english tutorial live at learnredwood.com and just have the main site link over to it?

That would sure make things easy… !

Let’s get a prototype ‘learnredwood’ up and running before thinking about moving the live tutorial over. Thieffen’s amazing French translation should mostly hold until then, maybe a few minor changes we can monitor from main english repo’s TUTORIAL.md

@rob is Gatsby ok for this? I’m open to cameronjs too, just more familiar with Gatsby

1 Like
73

Ugh, I tried using Gatsby once but when it took like 10 minutes to build on Netlify (when anything else I’d used took ~30 seconds) I felt queezy…and just to end up with plain, flat HTML anyway! I know there’s a whole huge ecosystem behind them, but how much of that would we need? It felt like overkill to me for just turning Markdown into HTML but maybe it’s doing a bunch of other stuff that would make the tradeoff worth it?

@thedavid has been a huge https://docusaurus.io/ advocate, have you ever used that? That might be more useful for like API documentation where there’s a bunch of navigating and cross-referencing, etc.

1 Like
75

I perused docusaurus during research and found it intersting. I’ll try with that!

76

Blitz has been using Docusaurus for their homepage if you’re looking for an example.

1 Like
77

Been playing with Docusuarus - it’s interesting but the build phase is completely obscured making it difficult to add custom build logic.

It also relies on frontmatter for building pages which would mean changing the source docs. Would also probably involve splitting the tutorial doc into smaller docs as I can’t figure out how to add custom build logic to split it up like in the redwoodjs site.

Maybe I’m not tapping into the potential yet? @thedavid do you know how one can customize build logic in a Docusaurus project?

1 Like
78

I don’t mind doing this, I’ve thought about doing it on the existing site several times. That one Markdown file is MASSIVE.

1 Like
79

Btw, both learnredwood.com and learnredwoodjs.com have already been taken months ago.

Would learn.redwoodjs.com be a good option ?

80

Would learn.redwoodjs.com be a good option ?

That would look pretty official if doable!

I don’t mind doing this, I’ve thought about doing it on the existing site several times. That one Markdown file is MASSIVE.

Gitlocalize would be thankful too XD

1 Like
81

Sorry guys, not having much success with docusaurus.

It’s a great framework for all-English docs, but has some limitations for our multilingual use case that I’m not sure how to overcome

  • it requires a flat folder structure for docs (see Blitzjs.com example). This disables us from using Gitlocalize for syncing as it relies on subdirectories with files of same name

  • Can’t figure out how to handle the sidebar in multiple languages

I know Gatsby wasn’t the popular choice, but I have confirmed it is easy to control the build process to build nested language routes. I did a multlilingual Gatsby site once that passed language meta data to each dynamically built page such that all UI components know which language context to use for that url (this would be useful for name-spacing algolia search)

I’m open to help with docusaurus if we’d like to try it still, I’m just stuck. If there isn’t bandwith for help, I will go the gatsby route

1 Like