From b46434b6dc166cb2b54f1ded1583397bc4640354 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 16 Jun 2022 19:45:06 +0800 Subject: [PATCH 1/2] fix(content-docs): allow translating doc labels in sidebars.js --- .../__snapshots__/translations.test.ts.snap | 42 +++++++++++++++-- .../src/__tests__/translations.test.ts | 6 ++- .../__snapshots__/normalization.test.ts.snap | 47 +++++++++++++++++++ .../sidebars/__tests__/normalization.test.ts | 26 ++++++++++ .../src/sidebars/normalization.ts | 6 +++ .../src/sidebars/types.ts | 7 ++- .../src/sidebars/utils.ts | 3 ++ .../src/sidebars/validation.ts | 1 + .../src/translations.ts | 27 ++++++++++- 9 files changed, 159 insertions(+), 6 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 4098aeb59399..fec474492100 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 @@ -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.docLink.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.docLink.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.docLink.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.docLink.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.docLink.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.docLink.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", }, ], }, 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 fb099e8eb63d..4c5392e28301 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts +++ b/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, }, ], }, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap index f847163c3050..f2c320506640 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap +++ b/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": [ diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts index f7f9ad2ee2e8..6ab358ad30b6 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts +++ b/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(); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts index 4d51e254443e..dad0f7c86c1c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts +++ b/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, diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index 8d038f417537..1a8746574a5e 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/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 | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts index 0c743f42d537..1ac140cd627b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts +++ b/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[] { diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index b9b1bfae007e..f1cc5a168e3c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -47,6 +47,7 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append({ type: Joi.string().valid('doc', 'ref').required(), id: Joi.string().required(), label: Joi.string(), + translatable: Joi.boolean(), }); const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({ diff --git a/packages/docusaurus-plugin-content-docs/src/translations.ts b/packages/docusaurus-plugin-content-docs/src/translations.ts index abc56ac65b93..8298d7bb04d5 100644 --- a/packages/docusaurus-plugin-content-docs/src/translations.ts +++ b/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}.docLink.${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}.docLink.${item.label!}`] + ?.message ?? item.label, + }; + } return item; }); } From 3e5d21b8210d493008af958f1e4f8cf535dc463d Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Thu, 16 Jun 2022 20:24:34 +0800 Subject: [PATCH 2/2] refactor docLink -> doc --- .../__snapshots__/translations.test.ts.snap | 12 ++++++------ .../src/translations.ts | 4 ++-- 2 files changed, 8 insertions(+), 8 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 fec474492100..bd51f4568621 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 @@ -16,7 +16,7 @@ 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.docLink.Second doc translatable": { + "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", }, @@ -24,7 +24,7 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for link Link label in sidebar docs, linking to https://facebook.com", "message": "Link label", }, - "sidebar.otherSidebar.docLink.Fifth doc translatable": { + "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", }, @@ -49,7 +49,7 @@ 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.docLink.Second doc translatable": { + "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", }, @@ -57,7 +57,7 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for link Link label in sidebar docs, linking to https://facebook.com", "message": "Link label", }, - "sidebar.otherSidebar.docLink.Fifth doc translatable": { + "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", }, @@ -82,7 +82,7 @@ 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.docLink.Second doc translatable": { + "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", }, @@ -90,7 +90,7 @@ exports[`getLoadedContentTranslationFiles returns translation files 1`] = ` "description": "The label for link Link label in sidebar docs, linking to https://facebook.com", "message": "Link label", }, - "sidebar.otherSidebar.docLink.Fifth doc translatable": { + "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", }, diff --git a/packages/docusaurus-plugin-content-docs/src/translations.ts b/packages/docusaurus-plugin-content-docs/src/translations.ts index 8298d7bb04d5..e0d824cd9c75 100644 --- a/packages/docusaurus-plugin-content-docs/src/translations.ts +++ b/packages/docusaurus-plugin-content-docs/src/translations.ts @@ -118,7 +118,7 @@ function getSidebarTranslationFileContent( .filter((item) => item.translatable); const docLinksContent: TranslationFileContent = Object.fromEntries( docs.map((doc) => [ - `sidebar.${sidebarName}.docLink.${doc.label!}`, + `sidebar.${sidebarName}.doc.${doc.label!}`, { message: doc.label!, description: `The label for the doc item ${doc.label!} in sidebar ${sidebarName}, linking to the doc ${ @@ -187,7 +187,7 @@ function translateSidebar({ return { ...item, label: - sidebarsTranslations[`sidebar.${sidebarName}.docLink.${item.label!}`] + sidebarsTranslations[`sidebar.${sidebarName}.doc.${item.label!}`] ?.message ?? item.label, }; }