feat(core): add script env variables: NODE_ENV + BABEL_ENV + DOCUSAURUS_CURRENT_LOCALE (temporary i18n workaround)

[slorber]

Note: this feature is considered as experimental and the API may need to be changed

Motivation

All Docusaurus scripts should fallback to "development" env:

process.env.BABEL_ENV ??= 'development';
process.env.NODE_ENV ??= 'development';

It should remain possible to run something like NODE_ENV=production docusaurus swizzle, although I'm not sure why someone would want to do that, it could make sense for some plugin script use cases we didn't think of? 🤷‍♂️

docusaurus build should override those defaults and have:

  process.env.BABEL_ENV = 'production';
  process.env.NODE_ENV = 'production';

---

When starting/building the site for a given locale, we should set a process.env.DOCUSAURUS_CURRENT_LOCALE variable.

It is a temporary flexible workaround to solve the inability to translate site config attributes (#4542).

IMPORTANT: the docusaurus build will first load the Docusaurus config with an empty value for DOCUSAURUS_CURRENT_LOCALE. This is because... the i18n config is in that file so we must first load it before being able to inject a value as an env variable. For this reason this env variable is only a best-effort awkward temporary workaround to unlock users. It is undocumented on purpose, not part of the public API, and will likely be refactored some day.

If you decide to use this variable, you'd rather program defensively and assume the locale value might be absent, and fallback yourself to your defaultLocale.

2 possible defensive examples, assuming "en" is your default locale:

process.env.DOCUSAURUS_CURRENT_LOCALE ??= "en"

function getSiteTagline() {
  switch(process.env.DOCUSAURUS_CURRENT_LOCALE) {
    case "fr": return "Mon site en Français";
    default: return "My English website";
  }
}

Some cases where DOCUSAURUS_CURRENT_LOCALE will be undefined:

• When Docusaurus first loads the config file on docusaurus build to get the i18n config
• When you run docusaurus start with no locale arg
• When you run any other docusaurus CLI script unrelated to i18n, that requires reading the config (swizzle, docs:version...)

The DOCUSAURUS_CURRENT_LOCALE env variable will be provided when:

• You run docusaurus build, only after the first load, once we start iterating over locales
• You run docusaurus build --locale fr
• You run docusaurus start --locale fr

Note: DOCUSAURUS_CURRENT_LOCALE is not designed to be set "from the outside". Please don't set this value as an env variable in your CI or local computer, it will be ignored.

I hope this makes sense and is not too confusing. Hopefully, we will provide a better way to translate the config later, but this should be good enough to unlock many use cases.

Test Plan

dogfood on our own website (site meta SEO tagline translated)

Test links

Deploy preview: https://deploy-preview-8677--docusaurus-2.netlify.app/

Related issues/PRs

Fix #8599

i18n workaround for #4542

[github-actions]

Size Change: 0 B

Total Size: 947 kB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	86 kB
website/build/assets/css/styles.********.css	112 kB
website/build/assets/js/main.********.js	707 kB
website/build/index.html	41 kB

_{compressed-size-action}

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	bd09150
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/63efab415cf3400008a2df5a
😎 Deploy Preview	https://deploy-preview-8677--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 85	🟢 97	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 77	🟢 100	🟢 100	🟢 100	🟢 90	Report

[slorber]

Any opinion @Josh-Cena ?

[slorber]

going to move on and merge this for now. We'll see how to improve this i18n+config support later