Add support for translating sidebar badges #2285

HiDeoo · 2024-09-05T10:09:10Z

Description

Closes Translatable badges in sidebar #1721

This PR adds the ability to translate sidebar badges using the same approach as the site title. A badge text can be a string, or for multilingual sites, an object with values for each different locale.

starlight({
  sidebar: [
    {
      slug: "test",
      badge: {
        en: "New",
        "pt-BR": "Novo",
      },
    },
  ],
});

This syntax is compatible with the string/object syntax to define badges. To support this feature, a new type of badge was added (I18nBadge) and can only be used in the sidebar configuration.

changeset-bot · 2024-09-05T10:09:14Z

🦋 Changeset detected

Latest commit: dc863a8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2024-09-05T10:09:26Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`dc863a8`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/66ea88c6b658ff0007c69e57
😎 Deploy Preview	https://deploy-preview-2285--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

astrobot-houston · 2024-09-05T10:09:53Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/sidebar.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

delucis · 2024-09-06T16:17:58Z

docs/src/content/docs/guides/sidebar.mdx

+			items: [
+				{
+					slug: 'constellations/andromeda',
+					badge: {
+						en: 'New',
+						'pt-BR': 'Novo',
+					},
+				},
+				{
+					slug: 'constellations/scorpius',
+					badge: {
+						text: {
+							en: 'Outdated',
+							'pt-BR': 'Descontinuado',
+						},
+						variant: 'caution',
+					},
+				},
+			],
+		},
+	],


Awesome stuff! Happy to add this.

I wonder if it would be simpler to only support localized strings using the text property though? I find it a bit weird to have two config options that are objects but that mean very different things depending on what the keys are, i.e. one object is “record of locales to labels” the other is “precisely typed config object with known keys”. (Without testing, I’d guess this also interferes with IDE autocomplete?)

Also, imagine this badge:

badge: { en: 'New', fr: 'Nouveau', }

If you decide you want to make it a success variant, this doesn’t work:

badge: { en: 'New', fr: 'Nouveau', + variant: 'success', }

So overall, I think I’m in favour of a single syntax rather than two. What do you think?

My initial implementation was what you described, then I somehow managed to convince myself that if you were using the shorthand notation, you would prefer to use that too with translated labels. I ended up not liking it personally but couldn't decide if I should remove it or not.

If you're having the same feeling too, I'll be more than happy to remove it (and it'll make the implementation simpler). I'll update the PR accordingly. Thanks again for the great input 🙌

Haha, yeah, going from badge: 'New' to badge: { text: { en: 'New' } } feels superficially like a lot, but I think in practice it’s OK and even it is slightly verbose, it definitely is clearer to explain/understand. Plus once you have a couple of locales the difference is kind of not so bad, e.g.

badge: { text: { en: 'New', fr: 'Nouveau', de: 'Neu', it: 'Nuovo' } } // vs badge: { en: 'New', fr: 'Nouveau', de: 'Neu', it: 'Nuovo' }

I second having only one config option with locales inside text. It's a key longer but a very small price to pay to have localized badges 💜.

Thanks you both, super appreciated. I have updated the PR accordingly, definitely an improvement 👍

delucis

LGTM! Thanks @HiDeoo — ready for the next minor 🫡

delucis · 2024-09-11T10:42:35Z

packages/starlight/utils/navigation.ts

+	if (!defaultText) {
+		throw new AstroError(
+			`The badge text for "${itemLabel}" must have a key for the default language "${defaultLang}".`,
+			'Update the Starlight config to include a badge text for the default language.\n' +
+				'Learn more about sidebar badges internationalization at https://starlight.astro.build/guides/sidebar/#internationalization-with-badges'
+		);
+	}


Noting that one way to avoid needing this would be to use the same API we use for sidebar items themselves:

{ label: 'Andromeda', translations: { fr: 'Andromède' }, }

I don’t have a strong opinion — we use the string | Record<string, string> form for the site title, but the label/translations form here in the sidebar currently. I’m pretty sure I opted for the separate translations property when designing the sidebar API to enforce the presence of a default label at the schema level, but having translations keys proliferating everywhere also isn’t amazing.

Happy to keep this as is, but wanted to note this while approving!

HiDeoo · 2024-09-11T16:08:29Z

Updated the test coverage thresholds in fd48b6b (no other changes since the approval)

feat: translatable sidebar badges

960139c

github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Sep 5, 2024

Merge branch 'main' into hd-feat-translatable-sidebar-badges

1afea3e

delucis reviewed Sep 6, 2024

View reviewed changes

HiDeoo added 2 commits September 9, 2024 11:08

feat: remove translatable sidebar badge shorthand syntax

e5a5d33

Merge branch 'main' into hd-feat-translatable-sidebar-badges

18a4aaa

delucis approved these changes Sep 11, 2024

View reviewed changes

delucis added the 🌟 minor Change that triggers a minor release label Sep 11, 2024

HiDeoo added 2 commits September 11, 2024 17:51

Merge branch 'main' into hd-feat-translatable-sidebar-badges

a9ae0e0

test: update coverage thresholds

fd48b6b

delucis added 3 commits September 18, 2024 09:49

Merge branch 'main' into hd-feat-translatable-sidebar-badges

72e238a

Merge branch 'main' into hd-feat-translatable-sidebar-badges

2689050

Update Vitest thresholds

dc863a8

delucis merged commit 7286220 into withastro:main Sep 18, 2024
16 checks passed

astrobot-houston mentioned this pull request Sep 18, 2024

[ci] release #2332

Merged

jsparkdev mentioned this pull request Sep 18, 2024

i18n(ko-KR): update sidebar.mdx #2337

Merged

HiDeoo mentioned this pull request Sep 18, 2024

i18n(fr): update guides/sidebar #2342

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for translating sidebar badges #2285

Add support for translating sidebar badges #2285

HiDeoo commented Sep 5, 2024

changeset-bot bot commented Sep 5, 2024 •

edited

Loading

netlify bot commented Sep 5, 2024 •

edited

Loading

astrobot-houston commented Sep 5, 2024 •

edited

Loading

delucis Sep 6, 2024

HiDeoo Sep 6, 2024 •

edited

Loading

delucis Sep 6, 2024

kevinzunigacuellar Sep 8, 2024

HiDeoo Sep 9, 2024

delucis left a comment

delucis Sep 11, 2024

HiDeoo commented Sep 11, 2024

Add support for translating sidebar badges #2285

Add support for translating sidebar badges #2285

Conversation

HiDeoo commented Sep 5, 2024

Description

changeset-bot bot commented Sep 5, 2024 • edited Loading

🦋 Changeset detected

netlify bot commented Sep 5, 2024 • edited Loading

✅ Deploy Preview for astro-starlight ready!

astrobot-houston commented Sep 5, 2024 • edited Loading

Lunaria Status Overview

Tracked Files

delucis Sep 6, 2024

Choose a reason for hiding this comment

HiDeoo Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

delucis Sep 6, 2024

Choose a reason for hiding this comment

kevinzunigacuellar Sep 8, 2024

Choose a reason for hiding this comment

HiDeoo Sep 9, 2024

Choose a reason for hiding this comment

delucis left a comment

Choose a reason for hiding this comment

delucis Sep 11, 2024

Choose a reason for hiding this comment

HiDeoo commented Sep 11, 2024

changeset-bot bot commented Sep 5, 2024 •

edited

Loading

netlify bot commented Sep 5, 2024 •

edited

Loading

astrobot-houston commented Sep 5, 2024 •

edited

Loading

HiDeoo Sep 6, 2024 •

edited

Loading