feat: Docusaurus ESLint plugin to enforce best Docusaurus practices

.eslintrc.js

@@ -32,6 +32,7 @@ module.exports = {
     'plugin:@typescript-eslint/recommended',
     'plugin:regexp/recommended',
     'prettier',
+    'plugin:@docusaurus/all',
   ],
   settings: {
     'import/resolver': {
@@ -41,7 +42,14 @@ module.exports = {
     },
   },
   reportUnusedDisableDirectives: true,
-  plugins: ['react-hooks', 'header', 'jest', '@typescript-eslint', 'regexp'],
+  plugins: [
+    'react-hooks',
+    'header',
+    'jest',
+    '@typescript-eslint',
+    'regexp',
+    '@docusaurus',
+  ],
   rules: {
     'array-callback-return': WARNING,
     camelcase: WARNING,
@@ -326,6 +334,7 @@ module.exports = {
         'header/header': OFF,
         'global-require': OFF,
         '@typescript-eslint/no-var-requires': OFF,
+        '@docusaurus/no-untranslated-text': OFF,
       },
     },
     {

packages/docusaurus/src/client/exports/__tests__/Translate.test.tsx

@@ -67,6 +67,7 @@ describe('<Translate>', () => {
   it('rejects when children is not a string', () => {
     expect(() =>
       renderer.create(
+        // eslint-disable-next-line @docusaurus/no-dynamic-i18n-messages
         <Translate id="foo">
           {/* @ts-expect-error: for test */}
           <span>aaa</span>

packages/eslint-plugin/.eslintrc.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  extends: ['../../.eslintrc.js', 'plugin:eslint-plugin/recommended'],
+};

packages/eslint-plugin/README.md

@@ -0,0 +1,56 @@
+# `@docusaurus/eslint-plugin`
+
+Docusaurus specific linting rules for eslint
+
+## Installation
+
+You'll first need to install [ESLint](https://eslint.org/):
+
+```sh
+npm i -D eslint
+```
+
+Next, install `@docusaurus/eslint-plugin`:
+
+```sh
+npm i -D @docusaurus/eslint-plugin
+```
+
+## Usage
+
+Add `@docusaurus` to the plugins section of your `.eslintrc` configuration file:
+
+```json
+{
+  "plugins": ["@docusaurus"]
+}
+```
+
+Then, you can extend one of the configs (e.g. the `recommended` config):
+
+```json
+{
+  "extends": ["plugin:@docusaurus/recommended"]
+}
+```
+
+For more fine-grained control, you can also configure the rules you want to use:
+
+```json
+{
+  "rules": {
+    "@docusaurus/no-dynamic-i18n-messages": "error",
+    "@docusaurus/no-untranslated-text": "warn"
+  }
+}
+```
+
+## Supported Configs
+
+- recommended
+- all
+
+## Supported Rules
+
+- no-dynamic-i18n-messages
+- no-untranslated-text

packages/eslint-plugin/docs/rules/no-dynamic-i18n-messages.md

@@ -0,0 +1,42 @@
+# enforce translate calls to be plain text labels (no-dynamic-i18n-messages)
+
+Ensures that `<Translate>` children and the message attribute of `translate` function calls are hardcoded strings.
+
+This is to ensure that static extraction of the text will work so it can be translatable. In-string dynamic placeholders are also possible using the values object.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+const text = 'Some text to be translated'
+
+// Invalid <Translate> child
+<Translate>{text}</Translate>
+
+// Invalid message attribute
+translate({message: text})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// Valid <Translate> child
+<Translate>Some text to be translated</Translate>
+
+// Valid message attribute
+translate({message: 'Some text to be translated'})
+
+// Valid <Translate> child using values object as prop
+<Translate values={{firstName: 'Sébastien'}}>
+  {'Welcome, {firstName}! How are you?'}
+</Translate>
+
+// Valid message attribute using values object as second argument
+translate({message: 'The logo of site {siteName}'}, {siteName: 'Docusaurus'})
+```
+
+## Further Reading
+
+- https://docusaurus.io/docs/docusaurus-core#translate
+- https://docusaurus.io/docs/docusaurus-core#translate-1

packages/eslint-plugin/docs/rules/no-untranslated-text.md

@@ -0,0 +1,32 @@
+# enforce text labels in JSX to be wrapped by translate calls (no-untranslated-text)
+
+Ensures that all text labels in JSX are wrapped by `<Translate>` components.
+
+When the [i18n feature](https://docusaurus.io/docs/i18n/introduction) is used, this rule is to ensure that all strings appearing on the website are being translated, so no string accidentally slips through untranslated.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+// Hello World is not translated
+<Component>Hello World</Component>
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// Hello World is translated
+<Component>
+  <Translate>Hello World</Translate>
+</Component>
+```
+
+## When Not To Use It
+
+If you're not using the [i18n feature](https://docusaurus.io/docs/i18n/introduction) then you can disable this rule.
+
+## Further Reading
+
+- https://docusaurus.io/docs/docusaurus-core#translate
+- https://docusaurus.io/docs/docusaurus-core#translate-1

packages/eslint-plugin/lib/index.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const requireIndex = require('requireindex');
+
+module.exports = {
+  rules: requireIndex(`${__dirname}/rules`),
+  configs: {
+    recommended: {
+      rules: {
+        '@docusaurus/no-dynamic-i18n-messages': 'error',
+      },
+    },
+    all: {
+      rules: {
+        '@docusaurus/no-dynamic-i18n-messages': 'error',
+        '@docusaurus/no-untranslated-text': 'warn',
+      },
+    },
+  },
+};

packages/eslint-plugin/lib/rules/__tests__/no-dynamic-i18n-messages.test.js

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const rule = require('../no-dynamic-i18n-messages');
+const {RuleTester} = require('eslint');
+const {getCommonValidTests} = require('../../util');
+
+const errorsJSX = [{messageId: 'translateChildren', type: 'JSXElement'}];
+const errorsFunc = [{messageId: 'translateArg', type: 'Identifier'}];
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 2022,
+    ecmaFeatures: {jsx: true},
+  },
+});
+ruleTester.run('no-dynamic-i18n-messages', rule, {
+  valid: [
+    ...getCommonValidTests(),
+    {
+      code: `<Translate
+                id="homepage.title"
+                description="The homepage welcome message">
+                  Welcome to my website
+              </Translate>`,
+    },
+    {
+      code: `<Translate
+                values={{firstName: 'Sébastien'}}>
+                  {'Welcome, {firstName}! How are you?'}
+              </Translate>`,
+    },
+    {
+      code: `<Translate>{'This'} is {\`valid\`}</Translate>`,
+    },
+    {
+      code: "translate({message: 'My page meta title'})",
+    },
+    {
+      code: "translate({message: 'The logo of site {siteName}'}, {siteName: 'Docusaurus'})",
+    },
+    {
+      code: 'translate({otherProp: metaTitle})',
+    },
+    {
+      code: 'translate({otherProp: `My page meta title`})',
+    },
+  ],
+
+  invalid: [
+    {
+      code: '<Translate>{text}</Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Translate>Hi {text} my friend</Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Translate> {text} </Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Translate>`{text}`</Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Translate>{`${text}`}</Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: 'translate({message: metaTitle})',
+      errors: errorsFunc,
+    },
+    {
+      code: 'translate({message: `My page meta title`})',
+      errors: errorsFunc,
+    },
+  ],
+});

packages/eslint-plugin/lib/rules/__tests__/no-untranslated-text.test.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const rule = require('../no-untranslated-text');
+const {RuleTester} = require('eslint');
+const {getCommonValidTests} = require('../../util');
+
+const errorsJSX = [{messageId: 'translateChildren', type: 'JSXElement'}];
+const errorsJSXFragment = [
+  {messageId: 'translateChildren', type: 'JSXFragment'},
+];
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 2022,
+    ecmaFeatures: {jsx: true},
+  },
+});
+ruleTester.run('no-untranslated-text', rule, {
+  valid: [...getCommonValidTests()],
+
+  invalid: [
+    {
+      code: '<Component>text</Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Component> text </Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Component>"text"</Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: "<Component>'text'</Component>",
+      errors: errorsJSX,
+    },
+    {
+      code: '<Component>`text`</Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<Component>{"text"}</Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: "<Component>{'text'}</Component>",
+      errors: errorsJSX,
+    },
+    {
+      code: '<Component>{`text`}</Component>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<>text</>',
+      errors: errorsJSXFragment,
+    },
+  ],
+});