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.
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.
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.
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
Jest is currently moving their documentation to this “stack” - you can see a sample of what Redwood tutorial (and more?) docs could become
(^ not all content is translated, but you can see what happens when you use language switcher)
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?
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
@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.
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.
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.
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…
