code · pull · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025
diff --git a/...ages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap b/...ages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap
@@ -5,27 +5,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "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",
+        "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",
+        "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",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {
@@ -38,27 +38,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "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",
+        "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",
+        "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",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {
@@ -71,27 +71,27 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = `
   {
     "content": {
       "sidebar.docs.category.Getting started": {
-        "description": "The label for category Getting started in sidebar docs",
+        "description": "The label for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started",
       },
       "sidebar.docs.category.Getting started.link.generated-index.description": {
-        "description": "The generated-index page description for category Getting started in sidebar docs",
+        "description": "The generated-index page description for category 'Getting started' in sidebar 'docs'",
         "message": "Getting started index description",
       },
       "sidebar.docs.category.Getting started.link.generated-index.title": {
-        "description": "The generated-index page title for category Getting started in sidebar docs",
+        "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",
+        "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",
+        "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",
+        "description": "The label for the doc item 'Fifth doc translatable' in sidebar 'otherSidebar', linking to the doc doc5",
         "message": "Fifth doc translatable",
       },
       "version.label": {

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/frontMatter.test.ts
@@ -186,10 +186,24 @@ describe('validateDocFrontMatter slug', () => {
   });
 });
 
+describe('validateDocFrontMatter sidebar_key', () => {
+  testField({
+    prefix: 'sidebar_key',
+    validFrontMatters: [
+      {sidebar_key: undefined},
+      {sidebar_key: 'Awesome docs'},
+    ],
+    invalidFrontMatters: [[{sidebar_key: ''}, 'is not allowed to be empty']],
+  });
+});
+
 describe('validateDocFrontMatter sidebar_label', () => {
   testField({
     prefix: 'sidebar_label',
-    validFrontMatters: [{sidebar_label: 'Awesome docs'}],
+    validFrontMatters: [
+      {sidebar_label: undefined},
+      {sidebar_label: 'Awesome docs'},
+    ],
     invalidFrontMatters: [[{sidebar_label: ''}, 'is not allowed to be empty']],
   });
 });

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts
@@ -232,35 +232,35 @@ describe('getLoadedContentTranslationFiles', () => {
           {
             "content": {
               "sidebar.sidebarWithConflicts.category.key-cat1": {
-                "description": "The label for category COMMON LABEL in sidebar sidebarWithConflicts",
+                "description": "The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.category.key-cat2": {
-                "description": "The label for category COMMON LABEL in sidebar sidebarWithConflicts",
+                "description": "The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-doc4": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-doc5": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-ref4": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.doc.key-ref5": {
-                "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5",
+                "description": "The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.link.key-link1": {
-                "description": "The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com",
+                "description": "The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com'",
                 "message": "COMMON LABEL",
               },
               "sidebar.sidebarWithConflicts.link.key-link2": {
-                "description": "The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com",
+                "description": "The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com'",
                 "message": "COMMON LABEL",
               },
               "version.label": {
@@ -279,21 +279,24 @@ describe('getLoadedContentTranslationFiles', () => {
         .toThrowErrorMatchingInlineSnapshot(`
         "Multiple docs sidebar items produce the same translation key.
         - \`sidebar.sidebarWithConflicts.category.COMMON LABEL\`: 2 duplicates found:
-          - COMMON LABEL (The label for category COMMON LABEL in sidebar sidebarWithConflicts)
-          - COMMON LABEL (The label for category COMMON LABEL in sidebar sidebarWithConflicts)
+          - COMMON LABEL (The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts')
+          - COMMON LABEL (The label for category 'COMMON LABEL' in sidebar 'sidebarWithConflicts')
 
         - \`sidebar.sidebarWithConflicts.link.COMMON LABEL\`: 2 duplicates found:
-          - COMMON LABEL (The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com)
-          - COMMON LABEL (The label for link COMMON LABEL in sidebar sidebarWithConflicts, linking to https://example.com)
+          - COMMON LABEL (The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com')
+          - COMMON LABEL (The label for link 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to 'https://example.com')
 
         - \`sidebar.sidebarWithConflicts.doc.COMMON LABEL\`: 4 duplicates found:
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc4)
-          - COMMON LABEL (The label for the doc item COMMON LABEL in sidebar sidebarWithConflicts, linking to the doc doc5)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc4)
+          - COMMON LABEL (The label for the doc item 'COMMON LABEL' in sidebar 'sidebarWithConflicts', linking to the doc doc5)
 
         To avoid translation key conflicts, use the \`key\` attribute on the sidebar items above to uniquely identify them.
-            "
+
+        When using autogenerated sidebars, you can provide a unique translation key by adding:
+        - the \`key\` attribute to category item metadata (\`_category_.json\` / \`_category_.yml\`)
+        - the \`sidebar_key\` attribute to doc item metadata (front matter in \`Category/index.mdx\`)"
       `);
     });
   });

diff --git a/packages/docusaurus-plugin-content-docs/src/frontMatter.ts b/packages/docusaurus-plugin-content-docs/src/frontMatter.ts
@@ -30,6 +30,7 @@ export const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   description: Joi.string().allow(''),
   slug: Joi.string(),
+  sidebar_key: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),

diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts
@@ -339,7 +339,15 @@ declare module '@docusaurus/plugin-content-docs' {
      * @see {@link DocMetadata.slug}
      */
     slug?: string;
-    /** Customizes the sidebar label for this doc. Will default to its title. */
+    /**
+     * Customizes the sidebar key for this doc,
+     * to uniquely identify it in translations.
+     */
+    sidebar_key?: string;
+    /**
+     * Customizes the sidebar label for this doc.
+     * Will default to its title.
+     */
     sidebar_label?: string;
     /**
      * Controls the position of a doc inside the generated sidebar slice when

diff --git a/...ocusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap b/...ocusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap
@@ -91,6 +91,7 @@ exports[`DefaultSidebarItemsGenerator generates simple flat sidebar 1`] = `
       "custom": "prop",
     },
     "id": "doc1",
+    "key": "doc1-sidebar-key",
     "label": "doc1 sidebar label",
     "type": "doc",
   },
@@ -120,6 +121,7 @@ exports[`DefaultSidebarItemsGenerator generates subfolder sidebar 1`] = `
         "type": "doc",
       },
     ],
+    "key": "doc1-sidebar-key",
     "label": "Subsubsubfolder category label",
     "link": {
       "id": "doc1",
@@ -142,6 +144,7 @@ exports[`DefaultSidebarItemsGenerator generates subfolder sidebar 1`] = `
   },
   {
     "id": "doc1",
+    "key": "doc1-sidebar-key",
     "type": "doc",
   },
   {

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts
@@ -63,6 +63,7 @@ describe('DefaultSidebarItemsGenerator', () => {
           sourceDirName: '.',
           sidebarPosition: 2,
           frontMatter: {
+            sidebar_key: 'doc1-sidebar-key',
             sidebar_label: 'doc1 sidebar label',
             sidebar_custom_props: {custom: 'prop'},
           },
@@ -254,7 +255,9 @@ describe('DefaultSidebarItemsGenerator', () => {
           sourceDirName: 'subfolder/subsubfolder',
           title: 'Subsubsubfolder category label',
           sidebarPosition: undefined,
-          frontMatter: {},
+          frontMatter: {
+            sidebar_key: 'doc1-sidebar-key',
+          },
         },
         {
           id: 'doc2',

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts
@@ -139,6 +139,7 @@ Available doc IDs:
       const {
         sidebarPosition: position,
         frontMatter: {
+          sidebar_key: key,
           sidebar_label: label,
           sidebar_class_name: className,
           sidebar_custom_props: customProps,
@@ -151,6 +152,7 @@ Available doc IDs:
         source: fileName,
         // We don't want these fields to magically appear in the generated
         // sidebar
+        ...(key !== undefined && {key}),
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
         ...(customProps !== undefined && {customProps}),
@@ -191,6 +193,7 @@ Available doc IDs:
       function getCategoryLinkedDocMetadata():
         | {
             id: string;
+            key?: string;
             position?: number;
             label?: string;
             customProps?: {[key: string]: unknown};
@@ -212,6 +215,7 @@ Available doc IDs:
         return {
           id,
           position: doc.sidebarPosition,
+          key: doc.frontMatter.sidebar_key,
           label: doc.frontMatter.sidebar_label ?? doc.title,
           customProps: doc.frontMatter.sidebar_custom_props,
           className: doc.frontMatter.sidebar_class_name,
@@ -236,6 +240,8 @@ Available doc IDs:
         categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
 
+      const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
+
       return {
         type: 'category',
         label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
@@ -252,7 +258,7 @@ Available doc IDs:
         ...(categoryMetadata?.description && {
           description: categoryMetadata?.description,
         }),
-        ...(categoryMetadata?.key && {key: categoryMetadata?.key}),
+        ...(key && {key}),
         ...(link && {link}),
       };
     }

diff --git a/packages/docusaurus-plugin-content-docs/src/translations.ts b/packages/docusaurus-plugin-content-docs/src/translations.ts
@@ -71,7 +71,16 @@ function ensureNoSidebarDuplicateEntries(
 To avoid translation key conflicts, use the ${logger.code(
       'key',
     )} attribute on the sidebar items above to uniquely identify them.
-    `);
+
+When using autogenerated sidebars, you can provide a unique translation key by adding:
+- the ${logger.code('key')} attribute to category item metadata (${logger.code(
+      '_category_.json',
+    )} / ${logger.code('_category_.yml')})
+- the ${logger.code(
+      'sidebar_key',
+    )} attribute to doc item metadata (front matter in ${logger.code(
+      'Category/index.mdx',
+    )})`);
   }
 }
 
@@ -90,7 +99,7 @@ function getSidebarTranslationFileContent(
         `sidebar.${sidebarName}.category.${categoryKey}`,
         {
           message: category.label,
-          description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+          description: `The label for category '${category.label}' in sidebar '${sidebarName}'`,
         },
       ]);
 
@@ -100,7 +109,7 @@ function getSidebarTranslationFileContent(
             `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.title`,
             {
               message: category.link.title,
-              description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
+              description: `The generated-index page title for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -109,7 +118,7 @@ function getSidebarTranslationFileContent(
             `sidebar.${sidebarName}.category.${categoryKey}.link.generated-index.description`,
             {
               message: category.link.description,
-              description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
+              description: `The generated-index page description for category '${category.label}' in sidebar '${sidebarName}'`,
             },
           ]);
         }
@@ -126,7 +135,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.link.${linkKey}`,
       {
         message: link.label,
-        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+        description: `The label for link '${link.label}' in sidebar '${sidebarName}', linking to '${link.href}'`,
       },
     ];
   });
@@ -140,7 +149,7 @@ function getSidebarTranslationFileContent(
       `sidebar.${sidebarName}.doc.${docKey}`,
       {
         message: doc.label!,
-        description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${
+        description: `The label for the doc item '${doc.label!}' in sidebar '${sidebarName}', linking to the doc ${
           doc.id
         }`,
       },