feat(i18n): introduce localisation capabilities and language toggle

[ovflowd]

trafficstars

Check List

• [x] I have read the Contributing Guidelines and made commit messages that follow the guideline.
• [x] I have run npm run lint:js -- --fix and/or npm run lint:md -- --fix for my JavaScript and/or Markdown changes.
  • This is important as most of the cases your code changes might not be correctly linted
• [x] I have run npm run test to check if all tests are passing, and/or npm run test -- -u to update snapshots if I created and/or updated React Components.
• [x] I have checked that the build works locally and that npm run build and npm run build-storybook work fine.
• [x] I've covered new added functionality with unit tests if necessary.

Description

This PR introduces several changes within the nodejs.dev codebase. By introducing full Internationalization and Localization support. The following changes and introductions were done:

• Introduced two plugins gatsby-theme-i18n and gatsby-theme-i18n-react-intl
  • Those respectively introduce the support of Localized pages and MDX/Markdown pages and content, the introduction of language prefixes in the website and finally, the support of FormatJS/ReactIntl.
  • When a page doesn't contain a translation for the current language, it falls back to the default language version of that page
  • The gatsby-theme-i18n was patched since it is kinda unmaintained, and we were required to patch it to work with some of our requirements.
    • The patches allow it to redirect pages without the language prefixes to the same page with a language prefix
    • It also allows the gatsby-plugin-offline to work
• Introduced a Language Dropdown that easily allows switching between Languages
• Introduced a config.json file for i18n with multiple Language metadata.
  • Note.: Most of the languages are disabled and miss correct metadata; this can be populated later by the @nodejs/i18n team.
• Introduced a helper that easily allows to wrap Article pages into Localized GraphQL data and render them without duplicating code. (Most of the pages (src/pages) were copy-paste and simple changes. This helper creates uniformity and allows us to create new pages easily and have a centralized Layout for Article pages (src/components/Layout/article.tsx)
• Created a helper that keeps track of the user's language choices and redirects them to the stored language of preference. This hook also attempts to redirect them initially to the language their system/browser prefers.
  • TL;DR if the browser language is Spanish, and they open the page without the language prefix, it will redirect to the Spanish version of our page if we support the language.
• This PR introduced several micro performances, styles and logic fixes to the Nodejs.dev website, whose most are related to the introduction of the Node.js.dev website
• This PR also moved all the content pages adding a prefix on the file extension to en.md
  • Markdown files now require this suffix to inform the engine which language they belong.

Screenshots

Related Issues

Closes #2568 Closes #254 Closes #1555 Closes #274

[github-actions[bot]]

Please find a preview at: https://staging.nodejs.dev/2500/

[ovflowd]

Note.: I'm still going to add unit tests for the new hooks and Components. Just haven't had time for it 🙇

[codecov-commenter]

Codecov Report

Merging #2500 (8ea6147) into main (b5ce031) will decrease coverage by 3.08%. The diff coverage is 73.21%.

@@            Coverage Diff             @@
##             main    #2500      +/-   ##
==========================================
- Coverage   87.10%   84.01%   -3.09%     
==========================================
  Files          87       97      +10     
  Lines        1000     1076      +76     
  Branches      273      301      +28     
==========================================
+ Hits          871      904      +33     
- Misses        123      166      +43     
  Partials        6        6              

Impacted Files	Coverage Δ
src/components/BlogCard/index.tsx	100.00% <ø> (ø)
src/components/Footer/index.tsx	100.00% <ø> (ø)
src/components/GetStartedSection/index.tsx	100.00% <ø> (ø)
src/components/Hero/index.tsx	100.00% <ø> (ø)
src/components/InstallTabs/LinuxPanel/index.tsx	100.00% <ø> (ø)
src/components/InstallTabs/MacOSPanel/index.tsx	100.00% <ø> (ø)
src/components/InstallTabs/WindowsPanel/index.tsx	100.00% <ø> (ø)
src/components/NavigationItem/index.tsx	100.00% <ø> (ø)
src/components/Pagination/index.tsx	100.00% <ø> (ø)
src/components/RecentPosts/index.tsx	100.00% <ø> (ø)
... and 35 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[mikeesto]

Nice work on this one! A couple of small comments/suggestions (by no means blockers):

1. When I opened the dropdown I initially didn't realise there were more than 4 locale options. It may be worthwhile making the vertical scrollbar always visible.

2. Sometimes when I was clicking through the dropdown I noticed that the locale didn't change in the URL. I think this is because the item within the list does not take up the full height/width and I just happened to be clicking too high/low:

[mikeesto]

Changing the locale and then navigating to a new page also does not persist the selection in the url, which is something else we will need to figure out

[ovflowd]

@mikeesto yes, indeed changing to a different page through the Navigation doesn't persist languages.

I'm still going to figure out that part, (re-read the plugin docs) and also investigate on proper helpers for getting the localized URL and navigating to localized URLs

[ovflowd]

I'm also going to fix those small UX issues. But regarding the scrollbars on the Language selector, I will need to check if I can override macOS behaviour through CSS as definitely by default macOS only shows the scrollbar when you're scrolling 🤔

[ovflowd]

@mikeesto I fixed the issues regarding links and navigation. Luckily the plugin itself already features everything we need.

Regarding the scroll, still investigating this issue, but it is a cosmetic problem which I don't think really blocks this PR.

[mikeesto]

Regarding the scroll, still investigating this issue, but it is a cosmetic problem which I don't think really blocks this PR.

Agreed! Appreciate the changes you did make. LGTM now.

[ovflowd]

@benhalverson I just rebased this branch, so we can see how it looks both with the search bar and language button 🎉

[github-actions[bot]]

Please find a preview at: https://staging.nodejs.dev/2500/

[manishprivet]

LGTM!

However, we might need to think about the /learn section for this, as translating them is a huge task and might not get completed any time soon. So it should always default to en.

Also, maybe we can pull translations for /community section from the original website, also giving us a base to test the i18n functionality.

@ovflowd

[benhalverson]

I like this but I don't know if it should be displayed yet if there are no language files to switch to. What do you think? @obensource @joesepi

[ovflowd]

I like this but I don't know if it should be displayed yet if there are no language files to switch to.

Well as the website is under development it makes sense to only display the languages we have indeed. I could add another field in the JSON that defines if the language is enabled or not. And only render the switch button if at least two languages are enabled.

[ovflowd]

Thanks, @rodion-arr, I'm gonna give an 👀 to why my changes affect this Component. Hold tight 😄

[ovflowd]

@rodion-arr this is what I was referring that still needs to be done.

[ovflowd]

@benhalverson yup, but I'm going today to add some changes on this PR as I wrote on my check-list here.

[github-actions[bot]]

Please find a preview at: https://staging.nodejs.dev/2500/

[github-actions[bot]]

Please find a preview at: https://staging.nodejs.dev/2500/

[ovflowd]

@nodejs/i18n could we get proofreading on /content/homepage/index.es.md? It's just a test document, but as we start to proceed with the internationalisation here, we would also start to make it nice.

[JohnTitor]

About Español, it looks fine to me 👍

Have you checked the layouts in ja-JP or zh-CN (i.e. different character frames), and ar-SA (i.e. right-to-left written language)? I expect it's overall fine, but I want to make sure that the things aren't corrupted (these langs often break the layouts in the context of l10n/i18n).

[ovflowd]

Hey @JohnTitor 👋 in theory the instalaltion should handle the rtl languages, I haven't really tested. As I mentioned before all the languages on src/i18n/config.json are disabled and I only enabled the Spanish one for testing. These changes here will be behind a feature flag 👀

Biut I'm def open for feedback, suggestions 🙏

[ovflowd]

About Español, it looks fine to me 👍

Thanks! The file most-likely is going to be removed, as I'm thinking on a factual plan of getting things translated and including a guideline of how the i18n system works here so people'd know the best way of contributing with i18n here.

[JohnTitor]

Ah, I thought we were also testing the localized layouts but actually not? Then I think this PR looks totally good to me (the translations are displayed and the toggle works perfectly)!

[ovflowd]

Ah, I thought we were also testing the localized layouts but actually not? Then I think this PR looks totally good to me (the translations are displayed and the toggle works perfectly)!

Yup, this PR only introduces the actual system. (A fully working system, which supports browser preferred languages, react-intl (React localized text bags through JSON files), localized markdown/mdx files, a feature toggle switcher, and redirects from non-localized pages (without language prefixes) to a localized one. (It also stores your language selections from the language toggler and redirects to those by default when coming from non-localized pages 😄)

In a following-PR I'm actually going to add the translation keys for the React components on the JSON files, and create guidelines for translation and then we're ready to officially accept translations! :D

[ovflowd]

PR is ready. Merging it once build passes.

[bennycode]

@ovflowd I noticed that this PR touched the docs of the Node.js event loop which are currently down: https://nodejs.dev/learn/the-nodejs-event-loop

Do you know what's the problem here?

https://user-images.githubusercontent.com/469989/185747544-eefaebf3-ae1f-493b-b1da-adb556e3ec6f.mp4

[ovflowd]

Hey, @bennycode, I would recommend looking through the open issues before spending time commenting on a merged PR. The bug you're referring to is here https://github.com/nodejs/nodejs.dev/issues/2647, and there's already an open PR fixing it.

The bug is partially introduced within createMarkdownPages, but the bug is not introduced in this PR. But in a previous one.

Yet, I appreciate you for taking time commenting here.

[bennycode]

Thanks for the feedback. Happy to hear that a fix has been already found. Keep up the good work. 👍

[ovflowd]

Thank you, @bennycode! Much appreciated!