Skip to content

i18n fixes and improvements#2444

Merged
delucis merged 10 commits intowithastro:mainfrom
HiDeoo:hd-fix-i18n-region-subtag-locals
Oct 28, 2024
Merged

i18n fixes and improvements#2444
delucis merged 10 commits intowithastro:mainfrom
HiDeoo:hd-fix-i18n-region-subtag-locals

Conversation

@HiDeoo
Copy link
Copy Markdown
Member

@HiDeoo HiDeoo commented Oct 7, 2024

Description

This PR includes the following changes:

Fix translations for languages with a region subtag

Languages with a region subtag (e.g. zh-CN) are not properly translated in the current implementation. This is visible in the https://starlight.astro.build/zh-cn/components/cards/ page:

  • The built-in UI strings are not applied, e.g. "Search" in the search bar.
  • The custom UI strings are not applied, e.g. "Preview" in the component preview.
image

This issue is due to the fact that Astro.currentLocale returns a BCP 47 language tag (usually called a lang in Starlight) and that the translation system creation is expecting a language path from the URL (usually called a locale in Starlight) that is later converted to a BCP 47 language tag. Passing down a lang instead of a locale fails that conversion making the translation of languages with a region subtag not work.

This PR changes the translation system creation to always use a BCP 47 language tag.

image

Use Astro.locals.t() when possible

In various places, we were still creating more translation systems than necessary instead of using the already configured Astro.locals.t(). This PR replaces those instances with Astro.locals.t().

Docs

The documentation "Accessing the current locale" example has been updated to use getRelativeLocaleUrl() so that the generated link is always correct.

HiDeoo added 4 commits October 7, 2024 23:05
Translation systems are now created from a BCP 47 language tag instead
of a locale which in Starlight represents a language path in the URL.
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Oct 7, 2024

🦋 Changeset detected

Latest commit: 16cfb89

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

@github-actions github-actions bot added the 🌟 core Changes to Starlight’s main package label Oct 7, 2024
@netlify
Copy link
Copy Markdown

netlify bot commented Oct 7, 2024

Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit 16cfb89
🔍 Latest deploy log https://app.netlify.com/sites/astro-starlight/deploys/671feff09b927200085ba895
😎 Deploy Preview https://deploy-preview-2444--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
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 site configuration.

@github-actions github-actions bot added the 📚 docs Documentation website changes label Oct 10, 2024
@astrobot-houston
Copy link
Copy Markdown
Contributor

astrobot-houston commented Oct 10, 2024

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/i18n.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.

@HiDeoo HiDeoo marked this pull request as ready for review October 10, 2024 08:22
@daniel-locatelli
Copy link
Copy Markdown

I noticed that the file locals.ts is getting the wrong locale, this seems to solved the issue:

	const locale = context.url.pathname.split('/')[1] || context.preferredLocale || 'en';
	context.locals.t = useTranslations(locale);

I hope it helps!

@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented Oct 18, 2024

Thanks for the feedback 🙌

I noticed that the file locals.ts is getting the wrong locale

This PR refactors useTranslations() to now accepts a lang instead of a locale. In Starlight, a locale usually represents the path used in i18n, e.g. zh-cn while lang is a BCP 47 language tag, e.g. zh-CN so this may be what you're seeing, which is a change from the previous behavior?

@daniel-locatelli
Copy link
Copy Markdown

What I meant is that the UI translation problem is still happening when I use this current pull request.

I forked this repo and used as a local package to test on my own Astro project.
The problem seems to be that the locals.ts is incorrectly getting the locale "en" in place of "pt-br" for example.

However, that did not happen when I tried directly on the "docs" in the monorepo. When you log locals.ts in the monorepo it outputs the correct locale. In my case the output was "pt-BR", which is still not in the right format, but can be fixed just lowering the case.

I made a video so you can better understand. At the bottom left is this current pull request. At the right is my own project, you can see it is not logging the wright locale:

Recording.2024-10-18.171635.mp4

@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented Oct 18, 2024

I see, I think there are 2 points here:

The problem seems to be that the locals.ts is incorrectly getting the locale "en" in place of "pt-br" for example.

Always getting en is definitely an issue. Altho, it should be at a different level, likely when we transform the Starligh i18n config to an Astro i18n config. This part of the code should not be impacted by the changes in this PR.

I tried reproducing the issue locally but I couldn't using the following config I assumed from your video:

defaultLocale: "en",
locales: {
  en: { label: "English", lang: "en" },
  "pt-br": { label: "Português do Brasil", lang: "pt-BR" },
},

Would you be able to share your Starlight config so I can investigate further?

In my case the output was "pt-BR", which is still not in the right format, but can be fixed just lowering the case.

This is expected with the current changes as Astro.currentLocale returns what is called a lang in Starlight (or a code in Astro i18n) and not a locale as I described in this comment.

@daniel-locatelli
Copy link
Copy Markdown

I already tried different configs too. Using Astro's native i18n or with starlight. No luck so far.
I am about to start a new project and see if I manage to reproduce the error.

My current config:

// https://astro.build/config
export default defineConfig({
  site: getSite(),
  base: BASE_PATH,
  output: "server",
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
  }),
  experimental: {
    serverIslands: true,
  },
  integrations: [
    sitemap(),
    react(),
    icon(),
    tailwind(),
    starlight({
      title: "ArchCompute",
      defaultLocale: "en",
      locales: {
        en: { label: "English", lang: "en" },
        "pt-br": {
          label: "Português Brasileiro",
          lang: "pt-BR",
        },
      },
      disable404Route: true,
    }),
    mdx(),
  ],
});

@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented Oct 18, 2024

Oh, that just hit me, which version of Astro are you using?

I had a similar issue a few days ago that was an issue in Astro which was fixed in Astro 4.16.4. Would you be able to test using the latest Astro version?

@daniel-locatelli
Copy link
Copy Markdown

Oh man... that was it! Thanks a lot.
Shame on me for not think about updating Astro 😅 It was at 4.15.11

Also thanks for this PR!

@HiDeoo
Copy link
Copy Markdown
Member Author

HiDeoo commented Oct 18, 2024

Amazing to hear, thanks for the follow-up and checking it out 🙌 And no problem, I had the same problem and it took me a while to figure it out, it's a bit tricky to spot an upstream i18n issue while working on another i18n issue 😅

Copy link
Copy Markdown
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

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

Looks great! I noticed one tiny detail in a comment, but no other notes — will fix that and conflicts now so we can get a patch out with these important fixes.

@delucis delucis merged commit d585b3e into withastro:main Oct 28, 2024
@astrobot-houston astrobot-houston mentioned this pull request Oct 28, 2024
thomasbnt added a commit to thomasbnt/starlight that referenced this pull request Oct 29, 2024
HiDeoo added a commit that referenced this pull request Oct 30, 2024
Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Co-authored-by: dreyfus92 <85648028+dreyfus92@users.noreply.github.com>
Yoxnear pushed a commit to Yoxnear/starlight-custom that referenced this pull request Jul 23, 2025
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants