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,
@@ -304,6 +312,10 @@ module.exports = {
     // locals must be justified with a disable comment.
     '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
     '@typescript-eslint/prefer-optional-chain': ERROR,
+    '@docusaurus/no-untranslated-text': [
+      WARNING,
+      {ignoreStrings: ['·', '-', '—', "'", '"', '×', '@', '🏠', '​']},
+    ],
   },
   overrides: [
     {
@@ -326,6 +338,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/string-literal-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,7 @@
+# `@docusaurus/eslint-plugin`
+
+Docusaurus specific linting rules for eslint.
+
+## Usage
+
+See [eslint-plugin documentation](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin).

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/string-literal-i18n-messages': 'error',
+      },
+    },
+    all: {
+      rules: {
+        '@docusaurus/string-literal-i18n-messages': 'error',
+        '@docusaurus/no-untranslated-text': 'warn',
+      },
+    },
+  },
+};

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

@@ -0,0 +1,147 @@
+/**
+ * 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(),
+    {
+      code: '<Component>·</Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>· </Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component> · </Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>· ·</Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>· — ×</Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>{"·"}</Component>',
+      options: [{ignoreStrings: ['"·"']}],
+    },
+    {
+      code: "<Component>{'·'}</Component>",
+      options: [{ignoreStrings: ["'·'"]}],
+    },
+    {
+      code: '<Component>{`·`}</Component>',
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>Docusaurus</Component>',
+      options: [{ignoreStrings: ['Docusaurus']}],
+    },
+    {
+      code: '<Component>&#8203;</Component>',
+      options: [{ignoreStrings: ['&#8203;']}],
+    },
+    {
+      code: `<>
+              {' · '}
+            </>`,
+      options: [{ignoreStrings: ['·', "'"]}],
+    },
+  ],
+
+  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,
+    },
+    {
+      code: '<Component>· — ×</Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—']}],
+    },
+    {
+      code: '<Component>··</Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component> ·· </Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>"·"</Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: "<Component>'·'</Component>",
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>`·`</Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['·', '—', '×']}],
+    },
+    {
+      code: '<Component>Docusaurus</Component>',
+      errors: errorsJSX,
+      options: [{ignoreStrings: ['Docu', 'saurus']}],
+    },
+  ],
+});

packages/eslint-plugin/lib/rules/__tests__/string-literal-i18n-messages.test.js

@@ -0,0 +1,51 @@
+/**
+ * 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('../string-literal-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('string-literal-i18n-messages', rule, {
+  valid: [...getCommonValidTests()],
+
+  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,
+    },
+    {
+      // eslint-disable-next-line no-template-curly-in-string
+      code: '<Translate>{`${text}`}</Translate>',
+      errors: errorsJSX,
+    },
+    {
+      code: 'translate({message: metaTitle})',
+      errors: errorsFunc,
+    },
+  ],
+});

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

@@ -0,0 +1,71 @@
+/**
+ * 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 {isTextLabelChild, report} = require('../util');
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'enforce text labels in JSX to be wrapped by translate calls',
+      category: 'Suggestions',
+      url: 'https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/no-untranslated-text',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          ignoreStrings: {
+            type: 'array',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      translateChildren:
+        'All text labels in JSX should be wrapped by translate calls',
+    },
+  },
+
+  create(context) {
+    const stringsToIgnore = context.options[0]?.ignoreStrings ?? [];
+
+    const isParentTranslate = ({child, isParentFragment}) =>
+      !isParentFragment &&
+      child.parent.openingElement.name.name === 'Translate';
+
+    const isChildValid = ({child, isParentFragment}) => {
+      if (!isTextLabelChild({child, ignoreWhitespace: true, stringsToIgnore})) {
+        return true;
+      }
+      return isParentTranslate({child, isParentFragment});
+    };
+
+    const isNodeValid = ({node, isFragment = false} = {}) =>
+      node.children.every((child) =>
+        isChildValid({child, isParentFragment: isFragment}),
+      );
+
+    return {
+      'JSXElement[openingElement.selfClosing=false]': (node) => {
+        if (!isNodeValid({node})) {
+          report(context, node, 'translateChildren');
+        }
+      },
+      'JSXFragment[openingFragment]': (node) => {
+        if (!isNodeValid({node, isFragment: true})) {
+          report(context, node, 'translateChildren');
+        }
+      },
+    };
+  },
+};