From 766549317b12be2be88be802f7f1e20d94ab1e7f Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 27 Jun 2025 15:56:52 +0200 Subject: [PATCH] Add unit test for docs translation key conflict behavior --- .../__snapshots__/translations.test.ts.snap | 210 ------------------ .../src/__tests__/translations.test.ts | 181 ++++++++++----- 2 files changed, 122 insertions(+), 269 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap index 85001a3509..7498d1ba22 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap @@ -28,30 +28,6 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5", "message": "Fifth doc translatable", }, - "sidebar.sidebarWithDuplicates.category.key-cat1": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.category.key-cat2": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, "version.label": { "description": "The label for version current", "message": "current label", @@ -85,30 +61,6 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5", "message": "Fifth doc translatable", }, - "sidebar.sidebarWithDuplicates.category.key-cat1": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.category.key-cat2": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, "version.label": { "description": "The label for version 2.0.0", "message": "2.0.0 label", @@ -142,30 +94,6 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for the doc item Fifth doc translatable in sidebar otherSidebar, linking to the doc doc5", "message": "Fifth doc translatable", }, - "sidebar.sidebarWithDuplicates.category.key-cat1": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.category.key-cat2": { - "description": "The label for category COMMON LABEL in sidebar sidebarWithDuplicates", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-doc5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref4": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc4", - "message": "COMMON LABEL", - }, - "sidebar.sidebarWithDuplicates.doc.key-ref5": { - "description": "The label for the doc item COMMON LABEL in sidebar sidebarWithDuplicates, linking to the doc doc5", - "message": "COMMON LABEL", - }, "version.label": { "description": "The label for version 1.0.0", "message": "1.0.0 label", @@ -346,52 +274,6 @@ exports[`translateLoadedContent returns translated loaded content 1`] = ` "type": "ref", }, ], - "sidebarWithDuplicates": [ - { - "id": "doc4", - "key": "key-doc4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc5", - "key": "key-doc5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc4", - "key": "key-ref4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "id": "doc5", - "key": "key-ref5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat1", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat2", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - ], }, "tagsPath": "/tags/", "versionName": "current", @@ -563,52 +445,6 @@ exports[`translateLoadedContent returns translated loaded content 1`] = ` "type": "ref", }, ], - "sidebarWithDuplicates": [ - { - "id": "doc4", - "key": "key-doc4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc5", - "key": "key-doc5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc4", - "key": "key-ref4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "id": "doc5", - "key": "key-ref5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat1", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat2", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - ], }, "tagsPath": "/tags/", "versionName": "2.0.0", @@ -780,52 +616,6 @@ exports[`translateLoadedContent returns translated loaded content 1`] = ` "type": "ref", }, ], - "sidebarWithDuplicates": [ - { - "id": "doc4", - "key": "key-doc4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc5", - "key": "key-doc5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "doc", - }, - { - "id": "doc4", - "key": "key-ref4", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "id": "doc5", - "key": "key-ref5", - "label": "COMMON LABEL (translated)", - "translatable": true, - "type": "ref", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat1", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - { - "collapsed": false, - "collapsible": true, - "items": [], - "key": "key-cat2", - "label": "COMMON LABEL (translated)", - "type": "category", - }, - ], }, "tagsPath": "/tags/", "versionName": "1.0.0", diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts index 56cc958fee..5a79346a76 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts @@ -16,7 +16,7 @@ import type { LoadedContent, LoadedVersion, } from '@docusaurus/plugin-content-docs'; -import type {SidebarItem} from '../sidebars/types'; +import type {Sidebar} from '../sidebars/types'; function createSampleDoc(doc: Pick): DocMetadata { return { @@ -41,61 +41,8 @@ function createSampleDoc(doc: Pick): DocMetadata { }; } -function createSampleSidebarWithDuplicates({ - withUniqueKeys, -}: { - withUniqueKeys: boolean; -}): SidebarItem[] { - return [ - { - type: 'doc', - id: 'doc4', - label: 'COMMON LABEL', - translatable: true, - ...(withUniqueKeys && {key: 'key-doc4'}), - }, - { - type: 'doc', - id: 'doc5', - label: 'COMMON LABEL', - translatable: true, - ...(withUniqueKeys && {key: 'key-doc5'}), - }, - { - type: 'ref', - id: 'doc4', - label: 'COMMON LABEL', - translatable: true, - ...(withUniqueKeys && {key: 'key-ref4'}), - }, - { - type: 'ref', - id: 'doc5', - label: 'COMMON LABEL', - translatable: true, - ...(withUniqueKeys && {key: 'key-ref5'}), - }, - { - type: 'category', - label: 'COMMON LABEL', - items: [], - collapsed: false, - collapsible: true, - ...(withUniqueKeys && {key: 'key-cat1'}), - }, - { - type: 'category', - label: 'COMMON LABEL', - items: [], - collapsed: false, - collapsible: true, - ...(withUniqueKeys && {key: 'key-cat2'}), - }, - ]; -} - function createSampleVersion( - version: Pick, + version: Pick & Partial, ): LoadedVersion { return { label: `${version.versionName} label`, @@ -170,10 +117,6 @@ function createSampleVersion( translatable: true, }, ], - - sidebarWithDuplicates: createSampleSidebarWithDuplicates({ - withUniqueKeys: true, - }), }, ...version, }; @@ -210,6 +153,126 @@ describe('getLoadedContentTranslationFiles', () => { it('returns translation files', () => { expect(getSampleTranslationFiles()).toMatchSnapshot(); }); + + describe('translation key conflicts', () => { + function runTest({withUniqueKeys}: {withUniqueKeys: boolean}) { + const sidebarWithConflicts: Sidebar = [ + { + type: 'doc', + id: 'doc4', + label: 'COMMON LABEL', + translatable: true, + ...(withUniqueKeys && {key: 'key-doc4'}), + }, + { + type: 'doc', + id: 'doc5', + label: 'COMMON LABEL', + translatable: true, + ...(withUniqueKeys && {key: 'key-doc5'}), + }, + { + type: 'ref', + id: 'doc4', + label: 'COMMON LABEL', + translatable: true, + ...(withUniqueKeys && {key: 'key-ref4'}), + }, + { + type: 'ref', + id: 'doc5', + label: 'COMMON LABEL', + translatable: true, + ...(withUniqueKeys && {key: 'key-ref5'}), + }, + { + type: 'category', + label: 'COMMON LABEL', + items: [], + collapsed: false, + collapsible: true, + ...(withUniqueKeys && {key: 'key-cat1'}), + }, + { + type: 'category', + label: 'COMMON LABEL', + items: [], + collapsed: false, + collapsible: true, + ...(withUniqueKeys && {key: 'key-cat2'}), + }, + ]; + + const version = createSampleVersion({ + versionName: CURRENT_VERSION_NAME, + sidebars: { + sidebarWithConflicts, + }, + }); + return getLoadedContentTranslationFiles({ + loadedVersions: [version], + }); + } + + it('works on sidebar with translation key conflicts resolved by unique sidebar item keys', () => { + expect(runTest({withUniqueKeys: true})).toMatchInlineSnapshot(` + [ + { + "content": { + "sidebar.sidebarWithConflicts.category.key-cat1": { + "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", + "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", + "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", + "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", + "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", + "message": "COMMON LABEL", + }, + "version.label": { + "description": "The label for version current", + "message": "current label", + }, + }, + "path": "current", + }, + ] + `); + }); + + it('throws on sidebar translation key conflicts', () => { + expect(() => runTest({withUniqueKeys: false})) + .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)} + + - 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)} + + To avoid translation key conflicts, use the \`key\` attribute on the sidebar items above to uniquely identify them. + " + `); + }); + }); }); describe('translateLoadedContent', () => {