Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 2 commits into from Jun 16, 2022
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b46434b
fix(content-docs): allow translating doc labels in sidebars.js
Josh-Cena Jun 16, 2022
3e5d21b
refactor docLink -> doc
Josh-Cena Jun 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
42 changes: 39 additions & 3 deletions ...ages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/translations.test.ts.snap
View file
Open in desktop
Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -214,6 +238,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc2",
"label": "Second doc translatable (translated)",
"translatable": true,
"type": "doc",
},
{
Expand Down Expand Up @@ -248,7 +274,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc5",
"type": "doc",
"label": "Fifth doc translatable (translated)",
"translatable": true,
"type": "ref",
},
],
},
Expand Down Expand Up @@ -386,6 +414,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc2",
"label": "Second doc translatable (translated)",
"translatable": true,
"type": "doc",
},
{
Expand Down Expand Up @@ -420,7 +450,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc5",
"type": "doc",
"label": "Fifth doc translatable (translated)",
"translatable": true,
"type": "ref",
},
],
},
Expand Down Expand Up @@ -558,6 +590,8 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc2",
"label": "Second doc translatable (translated)",
"translatable": true,
"type": "doc",
},
{
Expand Down Expand Up @@ -592,7 +626,9 @@ exports[`translateLoadedContent returns translated loaded content 1`] = `
},
{
"id": "doc5",
"type": "doc",
"label": "Fifth doc translatable (translated)",
"translatable": true,
"type": "ref",
},
],
},
Expand Down
6 changes: 5 additions & 1 deletion packages/docusaurus-plugin-content-docs/src/__tests__/translations.test.ts
View file
Open in desktop
Expand Up @@ -86,6 +86,8 @@ function createSampleVersion(
{
type: 'doc',
id: 'doc2',
label: 'Second doc translatable',
translatable: true,
},
{
type: 'link',
Expand All @@ -109,8 +111,10 @@ function createSampleVersion(
id: 'doc4',
},
{
type: 'doc',
type: 'ref',
id: 'doc5',
label: 'Fifth doc translatable',
translatable: true,
},
],
},
Expand Down
47 changes: 47 additions & 0 deletions ...aurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/normalization.test.ts.snap
View file
Open in desktop
@@ -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": [
Expand Down
26 changes: 26 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/normalization.test.ts
View file
Open in desktop
Expand Up @@ -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();
});
});
6 changes: 6 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/sidebars/normalization.ts
View file
Open in desktop
Expand Up @@ -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,
Expand Down
7 changes: 6 additions & 1 deletion packages/docusaurus-plugin-content-docs/src/sidebars/types.ts
View file
Open in desktop
Expand Up @@ -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 & {
Expand Down Expand Up @@ -94,7 +99,7 @@ export type SidebarCategoriesShorthand = {
};

export type SidebarItemConfig =
| SidebarItemDoc
| Omit<SidebarItemDoc, 'translatable'>
| SidebarItemHtml
| SidebarItemLink
| SidebarItemAutogenerated
Expand Down
3 changes: 3 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts
View file
Open in desktop
Expand Up @@ -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[] {
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts
View file
Open in desktop
Expand Up @@ -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>({
Expand Down
27 changes: 26 additions & 1 deletion packages/docusaurus-plugin-content-docs/src/translations.ts
View file
Open in desktop
Expand Up @@ -12,6 +12,8 @@ import {
collectSidebarCategories,
transformSidebarItems,
collectSidebarLinks,
collectSidebarDocItems,
collectSidebarRefs,
} from './sidebars/utils';
import type {
LoadedVersion,
Expand Down Expand Up @@ -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!}`,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why is the key "docLink" instead of just "doc"? I mean, we use "category" and not "categoryLink". It looks better to use the exact same term as the sidebar item type?

Was wondering if we don't want to use different keys for "doc" and "ref"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was wondering if we don't want to use different keys for "doc" and "ref"?

Not necessarily. A "ref" item is always accompanied by a "doc" item and we probably want to reuse the label for the two items, if they are the same.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmmm, why not 馃憤

Someday there will likely someone who will want different translations for different items that share the same label 馃槄 currently there's potential for conflicts, but this looks like a niche use-case so let's see if anyone complains

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case we would need to differentiate each label independently. ref/doc is a pretty arbitrary cutoff, but each label being translated independently is... not too weird, just inconvenient.

{
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({
Expand Down Expand Up @@ -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;
});
}
Expand Down