fix(content-docs): allow translating doc labels in sidebars.js (#7634)

packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap

@@ -16,10 +16,18 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
         "description": "The generated-index page title for category Getting started in sidebar docs",
         "message": "Getting started index title",
       },
+      "sidebar.docs.doc.Second doc translatable": {
+        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "message": "Second doc translatable",
+      },
       "sidebar.docs.link.Link label": {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
       },
+      "sidebar.otherSidebar.doc.Fifth doc translatable": {
+        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "message": "Fifth doc translatable",
+      },
       "version.label": {
         "description": "The label for version current",
         "message": "current label",
@@ -41,10 +49,18 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
         "description": "The generated-index page title for category Getting started in sidebar docs",
         "message": "Getting started index title",
       },
+      "sidebar.docs.doc.Second doc translatable": {
+        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "message": "Second doc translatable",
+      },
       "sidebar.docs.link.Link label": {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
       },
+      "sidebar.otherSidebar.doc.Fifth doc translatable": {
+        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "message": "Fifth doc translatable",
+      },
       "version.label": {
         "description": "The label for version 2.0.0",
         "message": "2.0.0 label",
@@ -66,10 +82,18 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
         "description": "The generated-index page title for category Getting started in sidebar docs",
         "message": "Getting started index title",
       },
+      "sidebar.docs.doc.Second doc translatable": {
+        "description": "The label for the doc item Second doc translatable in sidebar docs, linking to the doc doc2",
+        "message": "Second doc translatable",
+      },
       "sidebar.docs.link.Link label": {
         "description": "The label for link Link label in sidebar docs, linking to https://facebook.com",
         "message": "Link label",
       },
+      "sidebar.otherSidebar.doc.Fifth doc translatable": {
+        "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5",
+        "message": "Fifth doc translatable",
+      },
       "version.label": {
         "description": "The label for version 1.0.0",
         "message": "1.0.0 label",
@@ -214,6 +238,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
               },
               {
                 "id": "doc2",
+                "label": "Second doc translatable (translated)",
+                "translatable": true,
                 "type": "doc",
               },
               {
@@ -248,7 +274,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
           {
             "id": "doc5",
-            "type": "doc",
+            "label": "Fifth doc translatable (translated)",
+            "translatable": true,
+            "type": "ref",
           },
         ],
       },
@@ -386,6 +414,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
               },
               {
                 "id": "doc2",
+                "label": "Second doc translatable (translated)",
+                "translatable": true,
                 "type": "doc",
               },
               {
@@ -420,7 +450,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
           {
             "id": "doc5",
-            "type": "doc",
+            "label": "Fifth doc translatable (translated)",
+            "translatable": true,
+            "type": "ref",
           },
         ],
       },
@@ -558,6 +590,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
               },
               {
                 "id": "doc2",
+                "label": "Second doc translatable (translated)",
+                "translatable": true,
                 "type": "doc",
               },
               {
@@ -592,7 +626,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
           },
           {
             "id": "doc5",
-            "type": "doc",
+            "label": "Fifth doc translatable (translated)",
+            "translatable": true,
+            "type": "ref",
           },
         ],
       },

packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts

@@ -86,6 +86,8 @@ function createSampleVersion(
             {
               type: 'doc',
               id: 'doc2',
+              label: 'Second doc translatable',
+              translatable: true,
             },
             {
               type: 'link',
@@ -109,8 +111,10 @@ function createSampleVersion(
           id: 'doc4',
         },
         {
-          type: 'doc',
+          type: 'ref',
           id: 'doc5',
+          label: 'Fifth doc translatable',
+          translatable: true,
         },
       ],
     },

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap

@@ -1,5 +1,52 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`normalization adds a translatable marker for labels defined in sidebars.js 1`] = `
+{
+  "sidebar": [
+    {
+      "id": "google",
+      "label": "Google",
+      "translatable": true,
+      "type": "doc",
+    },
+    {
+      "items": [
+        {
+          "id": "doc1",
+          "type": "doc",
+        },
+        {
+          "id": "doc2",
+          "type": "doc",
+        },
+      ],
+      "label": "Category 1",
+      "type": "category",
+    },
+    {
+      "items": [
+        {
+          "id": "doc3",
+          "type": "doc",
+        },
+        {
+          "id": "doc4",
+          "type": "doc",
+        },
+        {
+          "id": "msft",
+          "label": "Microsoft",
+          "translatable": true,
+          "type": "ref",
+        },
+      ],
+      "label": "Category 2",
+      "type": "category",
+    },
+  ],
+}
+`;
+
 exports[`normalization normalizes shorthands 1`] = `
 {
   "sidebar": [

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts

@@ -91,4 +91,30 @@ describe('normalization', () => {
       `"Invalid sidebar items collection \`"item"\` in sidebar sidebar: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a \`type\` property). See https://docusaurus.io/docs/sidebar/items for all valid syntaxes."`,
     );
   });
+
+  it('adds a translatable marker for labels defined in sidebars.js', () => {
+    expect(
+      normalizeSidebars({
+        sidebar: [
+          {
+            type: 'doc',
+            id: 'google',
+            label: 'Google',
+          },
+          {
+            'Category 1': ['doc1', 'doc2'],
+            'Category 2': [
+              'doc3',
+              'doc4',
+              {
+                type: 'ref',
+                id: 'msft',
+                label: 'Microsoft',
+              },
+            ],
+          },
+        ],
+      }),
+    ).toMatchSnapshot();
+  });
 });

packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts

@@ -44,6 +44,12 @@ export function normalizeItem(
     // This will never throw anyways
     return normalizeSidebar(item, 'sidebar items slice');
   }
+  if (
+    (item.type === 'doc' || item.type === 'ref') &&
+    typeof item.label === 'string'
+  ) {
+    return [{...item, translatable: true}];
+  }
   if (item.type === 'category') {
     const normalizedCategory: NormalizedSidebarItemCategory = {
       ...item,

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -27,6 +27,11 @@ export type SidebarItemDoc = SidebarItemBase & {
   type: 'doc' | 'ref';
   label?: string;
   id: string;
+  /**
+   * This is an internal marker. Items with labels defined in the config needs
+   * to be translated with JSON
+   */
+  translatable?: true;
 };
 
 export type SidebarItemHtml = SidebarItemBase & {
@@ -94,7 +99,7 @@ export type SidebarCategoriesShorthand = {
 };
 
 export type SidebarItemConfig =
-  | SidebarItemDoc
+  | Omit<SidebarItemDoc, 'translatable'>
   | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemAutogenerated

packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts

@@ -81,6 +81,9 @@ export function collectSidebarCategories(
 export function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[] {
   return collectSidebarItemsOfType('link', sidebar);
 }
+export function collectSidebarRefs(sidebar: Sidebar): SidebarItemDoc[] {
+  return collectSidebarItemsOfType('ref', sidebar);
+}
 
 // /!\ docId order matters for navigation!
 export function collectSidebarDocIds(sidebar: Sidebar): string[] {

packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts

@@ -47,6 +47,7 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
   type: Joi.string().valid('doc', 'ref').required(),
   id: Joi.string().required(),
   label: Joi.string(),
+  translatable: Joi.boolean(),
 });
 
 const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({

packages/docusaurus-plugin-content-docs/src/translations.ts

@@ -12,6 +12,8 @@ import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
+  collectSidebarDocItems,
+  collectSidebarRefs,
 } from './sidebars/utils';
 import type {
   LoadedVersion,
@@ -111,7 +113,22 @@ function getSidebarTranslationFileContent(
     ]),
   );
 
-  return mergeTranslations([categoryContent, linksContent]);
+  const docs = collectSidebarDocItems(sidebar)
+    .concat(collectSidebarRefs(sidebar))
+    .filter((item) => item.translatable);
+  const docLinksContent: TranslationFileContent = Object.fromEntries(
+    docs.map((doc) => [
+      `sidebar.${sidebarName}.doc.${doc.label!}`,
+      {
+        message: doc.label!,
+        description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${
+          doc.id
+        }`,
+      },
+    ]),
+  );
+
+  return mergeTranslations([categoryContent, linksContent, docLinksContent]);
 }
 
 function translateSidebar({
@@ -166,6 +183,14 @@ function translateSidebar({
             ?.message ?? item.label,
       };
     }
+    if ((item.type === 'doc' || item.type === 'ref') && item.translatable) {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.doc.${item.label!}`]
+            ?.message ?? item.label,
+      };
+    }
     return item;
   });
 }