fix: use region-specific translations for default locale by MilesChou · Pull Request #3759 · withastro/starlight

MilesChou · 2026-03-16T13:35:20Z

Summary

Fix default locale buildResources using stripLangRegion result as a separate layer that overwrites region-specific translations
For example, a monolingual site with lang: 'zh-TW' gets Simplified Chinese (zh) UI strings instead of Traditional Chinese (zh-TW)

Root Cause

In createTranslationSystem.ts, the default locale translation loading passes both builtinTranslations[defaultLocale] and builtinTranslations[stripLangRegion(defaultLocale)] as separate arguments to buildResources. Since buildResources applies later layers over earlier ones, zh (Simplified Chinese) overwrites zh-TW (Traditional Chinese).

The locales loop (line 37) correctly uses || as a fallback, but the default locale path (line 25-26) does not.

Fix

Align the default locale behavior with the locales loop by using || so the stripLangRegion result is only used as a fallback when the specific locale has no built-in translations:

-  builtinTranslations[defaultLocale],
-  builtinTranslations[stripLangRegion(defaultLocale)],
+  builtinTranslations[defaultLocale] || builtinTranslations[stripLangRegion(defaultLocale)],

Test plan

Added test case for zh-TW monolingual site verifying search.label returns 搜尋 (Traditional Chinese) instead of 搜索 (Simplified Chinese)
All existing i18n tests pass

Reproduction

// astro.config.mjs
starlight({
  locales: {
    root: {
      label: '繁體中文',
      lang: 'zh-TW',
    },
  },
})

The UI strings (search, theme selector, etc.) incorrectly show Simplified Chinese instead of Traditional Chinese.

🤖 Generated with Claude Code

…ase language override When a monolingual site uses a region-specific locale as the default (e.g., `zh-TW`), `buildResources` for the default locale was loading both `builtinTranslations['zh-TW']` and `builtinTranslations['zh']` as separate layers. Since `buildResources` applies later layers over earlier ones, the base language (`zh` → Simplified Chinese) was overwriting the region-specific translations (`zh-TW` → Traditional Chinese). This fix aligns the default locale behavior with the locales loop (line 37), using `||` so `stripLangRegion` result is only used as a fallback when the specific locale has no built-in translations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

netlify · 2026-03-16T13:35:29Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`ba86e01`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/69baaf75a7ed46000856cedf
😎 Deploy Preview	https://deploy-preview-3759--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: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

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

changeset-bot · 2026-03-16T13:35:29Z

🦋 Changeset detected

Latest commit: ba86e01

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	Patch

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

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

astrobot-houston · 2026-03-16T13:37:44Z

Hello! Thank you for opening your first PR to Starlight! ✨

Here’s what will happen next:

Our GitHub bots will run to check your changes.
If they spot any issues you will see some error messages on this PR.
Don’t hesitate to ask any questions if you’re not sure what these mean!
In a few minutes, you’ll be able to see a preview of your changes on Netlify 🤩
One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don’t worry if this takes a few days.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

delucis

Thank you @MilesChou! This change makes sense to me.

I initially wondered if it should only flip the order of the two resources (so you’d e.g. apply zh-TW on top of zh instead of the reverse like it is currently). That way e.g. a partial en-US dictionary could be combined with a complete en dictionary.

But I think your change is the right call:

These are our built-in translations and we require complete dictionaries for these, so there is no possibility of a “partial” dictionary.
While the en + en-US example might make sense, there are cases like zh + zh-TW where combining the dictionaries would not make sense.

It’s also what we already do for all other locales, so I think it was just an oversight that we didn’t for the default locale.

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.38.1` → `0.38.2`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.38.1/0.38.2) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.38.2?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.38.1/0.38.2?slim=true) | --- ### Release Notes <details> <summary>withastro/starlight (@astrojs/starlight)</summary> ### [`v0.38.2`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0382) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.38.1...@astrojs/starlight@0.38.2) ##### Patch Changes - [#3759](withastro/starlight#3759) [`f24ce99`](withastro/starlight@f24ce99) Thanks [@MilesChou](https://github.com/MilesChou)! - Fixes an issue where monolingual sites using a region-specific locale (e.g., `zh-TW`) as the default would incorrectly display base language translations (e.g., `zh` Simplified Chinese) instead of the region-specific ones (e.g., `zh-TW` Traditional Chinese). - [#3768](withastro/starlight#3768) [`a4c6c20`](withastro/starlight@a4c6c20) Thanks [@delucis](https://github.com/delucis)! - Improves performance of sidebar generation for sites with very large sidebars </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: Renovate Bot <renovate@zarantonello.dev> Co-committed-by: Renovate Bot <renovate@zarantonello.dev>

chore: add changeset for region-specific locale fix

6a8986e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions bot added the 🌟 core Changes to Starlight’s main package label Mar 16, 2026

MilesChou and others added 2 commits March 17, 2026 16:08

fix: add missing locale property to fix type check

2d6012c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tweak changeset

1ba0e9a

delucis approved these changes Mar 18, 2026

View reviewed changes

delucis added 🌟 patch Change that triggers a patch release ✅ approved Pull requests that have been approved and are ready to merge when next cutting a release labels Mar 18, 2026

Merge branch 'main' into fix/default-locale-region-translation-override

ba86e01

delucis merged commit f24ce99 into withastro:main Mar 18, 2026
16 checks passed

astrobot-houston mentioned this pull request Mar 18, 2026

[ci] release #3766

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: use region-specific translations for default locale#3759

fix: use region-specific translations for default locale#3759
delucis merged 5 commits intowithastro:mainfrom
MilesChou:fix/default-locale-region-translation-override

MilesChou commented Mar 16, 2026

Uh oh!

netlify bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

astrobot-houston commented Mar 16, 2026

Uh oh!

delucis left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

MilesChou commented Mar 16, 2026

Summary

Root Cause

Fix

Test plan

Reproduction

Uh oh!

netlify bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

changeset-bot bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

astrobot-houston commented Mar 16, 2026

Uh oh!

delucis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Mar 16, 2026 •

edited

Loading

changeset-bot bot commented Mar 16, 2026 •

edited

Loading

delucis left a comment •

edited

Loading