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>
facebook · Apr 29, 2022 · 3b1170e · 3b1170e
1 parent ae788c5
commit 3b1170e
Show file tree

Hide file tree

Showing 34 changed files with 885 additions and 52 deletions.
diff --git a/.eslintrc.js b/.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,
@@ -305,6 +313,24 @@ 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: [
+          '·',
+          '-',
+          '—',
+          '×',
+          '', // zwj: &#8203;
+          '@',
+          'WebContainers',
+          'Twitter',
+          'GitHub',
+          'Dev.to',
+          '1.x',
+        ],
+      },
+    ],
   },
   overrides: [
     {
@@ -327,6 +353,7 @@ module.exports = {
         'header/header': OFF,
         'global-require': OFF,
         '@typescript-eslint/no-var-requires': OFF,
+        '@docusaurus/no-untranslated-text': OFF,
       },
     },
     {
@@ -350,6 +377,16 @@ module.exports = {
         '@typescript-eslint/explicit-module-boundary-types': OFF,
       },
     },
+    {
+      files: [
+        '**/__tests__/**',
+        'packages/docusaurus-plugin-debug/**',
+        'website/_dogfooding/**',
+      ],
+      rules: {
+        '@docusaurus/no-untranslated-text': OFF,
+      },
+    },
     {
       // Internal files where extraneous deps don't matter much at long as
       // they run

diff --git a/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx b/packages/docusaurus-theme-classic/src/theme/LastUpdated/index.tsx
@@ -82,6 +82,7 @@ export default function LastUpdated({
       </Translate>
       {process.env.NODE_ENV === 'development' && (
         <div>
+          {/* eslint-disable-next-line @docusaurus/no-untranslated-text */}
           <small> (Simulated during dev for better perf)</small>
         </div>
       )}

diff --git a/packages/docusaurus-theme-live-codeblock/src/theme/Playground/index.tsx b/packages/docusaurus-theme-live-codeblock/src/theme/Playground/index.tsx
@@ -23,6 +23,7 @@ function Header({children}: {children: React.ReactNode}) {
 
 function LivePreviewLoader() {
   // Is it worth improving/translating?
+  // eslint-disable-next-line @docusaurus/no-untranslated-text
   return <div>Loading...</div>;
 }
 

diff --git a/packages/docusaurus/src/client/exports/__tests__/Translate.test.tsx b/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>

diff --git a/packages/docusaurus/src/client/theme-fallback/Error/index.tsx b/packages/docusaurus/src/client/theme-fallback/Error/index.tsx
@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
+
 import React from 'react';
 import Layout from '@theme/Layout';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';

diff --git a/packages/docusaurus/src/client/theme-fallback/Loading/index.tsx b/packages/docusaurus/src/client/theme-fallback/Loading/index.tsx
@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
+
 import React from 'react';
 import type {LoadingComponentProps} from 'react-loadable';
 

diff --git a/packages/docusaurus/src/client/theme-fallback/NotFound/index.tsx b/packages/docusaurus/src/client/theme-fallback/NotFound/index.tsx
@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// Should we translate theme-fallback?
+/* eslint-disable @docusaurus/no-untranslated-text */
+
 import React from 'react';
 import Layout from '@theme/Layout';
 import Head from '@docusaurus/Head';

diff --git a/packages/eslint-plugin/.eslintrc.js b/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'],
+};
diff --git a/packages/eslint-plugin/.npmignore b/packages/eslint-plugin/.npmignore
@@ -0,0 +1,6 @@
+copyUntypedFiles.mjs
+.tsbuildinfo
+tsconfig*
+__tests__
+
+.eslintrc.js
diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md
@@ -0,0 +1,7 @@
+# `@docusaurus/eslint-plugin`
+
+ESLint plugin to enforce best Docusaurus practices.
+
+## Usage
+
+See [eslint-plugin documentation](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin).
diff --git a/packages/eslint-plugin/lib/index.js b/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',
+      },
+    },
+  },
+};
diff --git a/packages/eslint-plugin/lib/rules/__tests__/no-untranslated-text.test.js b/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']}],
+    },
+  ],
+});
diff --git a/packages/eslint-plugin/lib/rules/__tests__/string-literal-i18n-messages.test.js b/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,
+    },
+  ],
+});