Try Crowdin + Docusaurus 2 beta?

Docs & Content Translations
#1

Here with another yet another change of wind!

I’ve been following Docusaurus team’s PR about adding i18n support for Crowdin (l10n service) to docusaurus 2. It looks like the support has been recently merged but not yet included in the docs as it is in testing for release soon. The PR owner is offering onboarding to those interested

Good timing! I think we should test out a solution for multli-lingual tutorial with this Crowdin + Docusaurus 2 combo. Would you guys mind if I reached out to make this happen?

i18n (internationalization) = The structural components of a website that allow for multi-lingual content
l10n (localization) = The management of multi-lingual content itself.

Why Docusaurus 2 (i18n):

  • It’s a static site framework designed explicitly for docs
  • Tried and trusted: one of those Facebook products
  • Now has i18n support with Crowdin integration

I tested Docusaurus out in past research for this project and rejected it because i18n was only available in the older Docusaurus 1 and felt it was not optimal for our use case. The new i18n support in Docusaurus 2 looks promising.

Why Crowdin (l10n):
I tested it out with our docs (see Crowdin repo here)

  • Has a truly beautiful translation interface with machine aided translation
  • Integration now supported with Docusarus 2
  • Makes auto PR requests
  • Translators can use their Github account with crowdin
  • Translators can see very quickly which docs need translation attention
  • Is not as buggy as Gitlocalize
  • FREE for open source projects

As background, so far we’ve been experimenting with this Gatsby-based repo with Gitlocalize l10n. It’s an OK alterenative, but is just (poorly) reinventing the docusaurus wheel.

So what do you say - can I reach out on behalf of Redwood? Docusaurus 2 needs a case for private onboarding, and Crowdin requires I apply for an open source license with them.

6 Likes
Tutorials as readme's, so people can fork and get started
#2

FWIW we went with Crowdin at work for our translation needs. Of the ones we tested it was the one we liked the most. Our needs are a little different though - we’re just translating short strings that we display using react-intl (formatjs) - not full page documents as is the case for RW.

1 Like
#3

we’re just translating short strings that we display using react-intl (formatjs) - not full page documents as is the case for RW.

As it turns out Crowdin is fantastic with markdown too

Happy to hear a confirmation that your team finds it a useful platform

#4

Heck yeah, you’re an official Agent of Redwood now, you can reach out on behalf of the group if you want to try something! This sounds very interesting…can’t wait to check it out, Special Agent Froelich. :woman_office_worker:

image

#5

By the power vested in me by Rob, I’ve started the ball rolling on this

Will keep everyone posted on the progress. Once the basics are in place it will be easier to colab!

5 Likes
#6

Quick update: I’ll get started on a repo with this “stack” this weekend since there is now guidance on how to get started

Very excited about this combo as it would allow us to be nimble with evolving documentation and default untranslated content to English. Since presentation of docs is covered by docusaurus framework, more energy can be spent on helping people who want to translate get involved.

Also, thanks to @Thieffen’s hard work on FR translation we could hit to ground running with solid example content :slight_smile:

Jest is currently moving their documentation to this “stack” - you can see a sample of what Redwood tutorial (and more?) docs could become :earth_africa:


(^ not all content is translated, but you can see what happens when you use language switcher)
2 Likes
#7

Nice! Any updates so far?

#8

Thanks to Rob’s help we have an official learn.redwoodjs.com repo up

It’s just budding now as I hook it up to Crowdin. @rob, it looks like I need admin access to this repo in order to set up Crowdin integration… is this possible?

2 Likes
#9

done! try again and let me know

#10

Much appreciated @thedavid! almost there, it looks like I just need the redwood mods to approve a request to integrate crowdin to this repo now

image
image1021×89 9.73 KB

In other news, we have a live deployment preview

1 Like
#11

Integration approved just now!

1 Like
#12

And nice work! Great to see the deploy preview up and running. :rocket::rocket:

1 Like
#13

Updated the deploy preview link to https://learn-redwood.netlify.app/

I added all the English content of the Tutorial. This invovled splitting the mega file into articles, adding frontmatter, updating relative links for new file structure, and closing img tags.

Note : there are styling issues to address

  • Code blocks with highlighted line numbers are missing highlted syntax
  • iframes are tiny

To test out translation flow I added one of @Thieffen’s French translations for “Welcome to Redwood”. Crowdin works, but it’s giving me all the credit for French translation :stuck_out_tongue:

@Thieffen if you want your name to show up on Github for the translations, I’m afraid you’ll have to upload them using a Crowdin account tied to your Github. I have already split your translations into files and added the necessary frontmatter/relative link edits. It would just require you uploading the files and correcting any missing translation strings. Here are instructions and the files: https://github.com/redwoodjs/learn.redwoodjs.com/tree/master/to-upload

Of course if you don’t feel like doing that I can upload it for you

^The English and French content may be a tad stale as there have been some edits to tutorial in .com. No worries, will sync it later in line with commit history.

For those curious to peek at the Crowdin: https://crowdin.com/project/learn-redwoodjs/fr#

2 Likes
#14

Looking good!

Were you thinking of adding Tailwind or sticking with custom? Tailwind will fix those iframes lickety split, but we can do the equivalent CSS easily enough.

The highlighted lines, that might be a different story…does Docusaurus do its own syntax highlighting? I was using a plugin for markdown-it that added a highlighted-line class to a <div> around each line, but I don’t see any of that in the new source.

#15

Were you thinking of adding Tailwind or sticking with custom? Tailwind will fix those iframes lickety split, but we can do the equivalent CSS easily enough.

I’ve tried adding tailwind, but it’s tricky to config because of docusaurus has baked-in postcss. Following this thread to hopefully get tailwind working sometime soon.

Regular old css would be probably do the trick for iframes… setting width: 100% makes it wide enough but can’t figure out the height. Stuck in wide-screen mode lol.

image

The highlighted lines, that might be a different story…does Docusaurus do its own syntax highlighting?

Docusaurus uses remark (vs. markdown-it on rw.com). After much search I discovered just adding a space before the {highlighted lines} does the trick…

```html {4-9}

image
image867×321 24.3 KB

1 Like
#16

Yeah those iframes are the worst, but someone lost to history discovered the bottom padding trick: https://avexdesigns.com/blog/responsive-youtube-embed

#17

Thank youuu and done with vanilla CSS (for now)

1 Like