feat: Docusaurus ESLint plugin to enforce best Docusaurus practices (#7206)

* feat: add eslint plugin

* refactor

* add tests

* fixups!

* fix(no-dynamic-i18n-messages): make translate() recognize template literals

* refactor: rename rule no-dynamic-i18n-messages --> string-literal-i18n-messages

* feat: add ignoreStrings option and refactor

* docs: migrate docs to /docs/api/plugins

* docs: fix anchor links in README.md

* fix: add some ignored strings

* docs: update eslint-plugin docs

* fix: update README link

* docs: various updates

- Reorder sidebar entries
- Fix title size
- Use Markdown file paths
- Simplify relative links

* address reviews

* wording polish

* add npmignore

* fix all internal warnings

* doc improvements

* fix test

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

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: ['​']}],
+    },
+    {
+      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');
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,62 @@
+/**
+ * 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,
+  isStringWithoutExpressions,
+} = require('../util');
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'enforce translate APIs to be called on plain text labels',
+      category: 'Possible Problems',
+      url: 'https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/string-literal-i18n-messages',
+    },
+    schema: [],
+    messages: {
+      translateChildren:
+        '<Translate> children must be hardcoded strings. You can have in-string dynamic placeholders using the values prop.',
+      translateArg:
+        'translation message must be a hardcoded string. You can have in-string dynamic placeholders using the values argument.',
+    },
+  },
+
+  create(context) {
+    const isNodeValid = (node) =>
+      node.children.every((child) => isTextLabelChild({child}));
+
+    return {
+      "JSXElement[openingElement.name.name='Translate']": (node) => {
+        if (!isNodeValid(node)) {
+          report(context, node, 'translateChildren');
+        }
+      },
+      "CallExpression > Identifier[name='translate']": (node) => {
+        const messageProperty = node.parent.arguments[0].properties.find(
+          (property) => property.key.name === 'message',
+        );
+        if (!messageProperty) {
+          return;
+        }
+
+        if (
+          !isStringWithoutExpressions({
+            text: messageProperty.value,
+          })
+        ) {
+          report(context, node, 'translateArg');
+        }
+      },
+    };
+  },
+};