Refactor translation system to be reusable in non-Astro code by delucis · Pull Request #1003 · withastro/starlight

delucis · 2023-10-28T16:58:33Z

What kind of changes does this PR include?

Changes to Starlight code

Description

Refactors the existing Starlight translations system so it can be instantiated from either getCollection() calls (for modules loaded by Astro) or file system calls (for modules running before Astro starts).
The file-system version makes it possible for work like Add Expressive Code to Starlight #742 to re-use our existing logic.
It will also help us unblock Support translating default aside titles #517.
This PR instantiates the file-system version in the main Starlight integration. In follow-up PRs we’d be able to pass useTranslations to code that needs them (i.e. the Expressive Code integration and the asides plugin)

To-do

Write some tests for the new code

Background

This is needed because our current i18n system depends on two bits of code that are only available after Astro starts: getCollection() imported from the astro:content virtual module is used to load the i18n data collection and get any user-configured JSON dictionaries of strings and Starlight user config imported from virtual:starlight/user-config.

These dependencies prevented pre-Astro code like remark/rehype plugins or other integration code from accessing our translation system. So far, when trying to support i18n in those cases, we either got stuck or ended up making a copy of our i18n logic that didn’t cover all cases. This refactor helps make sure we share as much logic as possible between the code that runs before and after Astro starts.

changeset-bot · 2023-10-28T16:58:37Z

🦋 Changeset detected

Latest commit: bd048d1

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

netlify · 2023-10-28T16:58:39Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`bd048d1`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/6542cc39d23e3f0008e3f5ff
😎 Deploy Preview	https://deploy-preview-1003--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 · 2023-10-28T16:59:47Z

size-limit report 📦

Path	Size
/index.html	5.13 KB (0%)
/_astro/*.js	19.27 KB (0%)
/_astro/*.css	9.7 KB (0%)

delucis · 2023-10-28T17:04:02Z

packages/starlight/index.ts

 		name: '@astrojs/starlight',
 		hooks: {
 			'astro:config:setup': ({ config, injectRoute, updateConfig }) => {
+				const useTranslations = createTranslationSystemFromFs(userConfig, config);


This variable is not in use yet, but would be passed into anything that needs it, such as the Starlight integration added in #742.

delucis · 2023-10-28T17:06:08Z

packages/starlight/utils/createTranslationSystem.ts

+/**
+ * Get the BCP-47 language tag for the given locale.
+ * @param locale Locale string or `undefined` for the root locale.
+ */
+function localeToLang(
+	locale: string | undefined,
+	locales: StarlightConfig['locales'],
+	defaultLocale: StarlightConfig['defaultLocale']
+): string {
+	const lang = locale ? locales?.[locale]?.lang : locales?.root?.lang;
+	const defaultLang = defaultLocale?.lang || defaultLocale?.locale;
+	return lang || defaultLang || 'en';
+}


I’ve duplicated this function for now from slugs.ts:

starlight/packages/starlight/utils/slugs.ts

Lines 31 to 39 in ba70635

/**

* Get the BCP-47 language tag for the given locale.

* @param locale Locale string or `undefined` for the root locale.

*/

export function localeToLang(locale: string | undefined): string {

const lang = locale ? config.locales?.[locale]?.lang : config.locales?.root?.lang;

const defaultLang = config.defaultLocale?.lang || config.defaultLocale?.locale;

return lang || defaultLang || 'en';

}

We could refactor in a similar spirit to make this version the base and then have a module that exports the easier to use methods that depend on virtual:starlight/user-config.

delucis · 2023-10-28T17:07:13Z

packages/starlight/utils/translations.ts

Our base useTranslations() method is unchanged but is refactored to use the new createTranslationSystem() factory, passing in files loaded with getCollection().

packages/starlight/utils/translations-fs.ts

* main: (22 commits) fix(docs-i18n-tracker): update `translations` import (withastro#1025) [ci] format i18n(zh-cn): Update css-and-tailwind.mdx (withastro#1018) [ci] format i18n(zh-cn): Update authoring-content.md (withastro#1016) i18n(ko-KR): update `configuration.mdx` (withastro#1015) i18n(ko-KR): update `sidebar.mdx` (withastro#1014) i18n(ko-KR): update `i18n.mdx` (withastro#1013) [ci] format i18n(ko-KR): update `frontmatter.md` (withastro#1017) [ci] format i18n(pt-BR): Update `css-and-tailwind.mdx`, `authoring-content.md` and `overrides.md` (withastro#1009) [ci] format [ci] release (withastro#996) Fix Prettier-compatibility of i18n test fixture Refactor translation system to be reusable in non-Astro code (withastro#1003) Add social icons to mobile menu footer (withastro#988) [ci] format Add Galician language support (withastro#1004) feat: add support for light / dark hero images (withastro#280) ...

…ro#1003)

delucis added 3 commits October 28, 2023 18:53

Refactor translation system to be reusable

e3fecaf

Create fs based translation loader for integration use

6974c89

Load user translations in Starlight integration

432e912

github-actions bot added the 🌟 core Changes to Starlight’s main package label Oct 28, 2023

delucis commented Oct 28, 2023

View reviewed changes

delucis added 6 commits November 1, 2023 22:12

Add tests for file-system translation system

4a5a248

Extra coverage

c2d07f4

Add some error handling to FS translation system

eaf8c14

Add tests for error handling

d9389b7

Fix comment

943900c

Add changeset

0249efe

delucis added the 🌟 patch Change that triggers a patch release label Nov 1, 2023

Merge branch 'main' into chris/i18n-refactor-2

bd048d1

delucis merged commit f1fdb50 into main Nov 1, 2023

delucis deleted the chris/i18n-refactor-2 branch November 1, 2023 22:31

astrobot-houston mentioned this pull request Nov 1, 2023

[ci] release #996

Merged

delucis mentioned this pull request Nov 1, 2023

Add Expressive Code to Starlight #742

Merged

HiDeoo mentioned this pull request Nov 2, 2023

fix(docs-i18n-tracker): update translations import #1025

Merged

delucis mentioned this pull request Nov 2, 2023

Support translating default aside titles #517

Merged

Yoxnear pushed a commit to Yoxnear/starlight-custom that referenced this pull request Jul 23, 2025

Refactor translation system to be reusable in non-Astro code (withast…

684a4e0

…ro#1003)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor translation system to be reusable in non-Astro code#1003

Refactor translation system to be reusable in non-Astro code#1003
delucis merged 10 commits intomainfrom
chris/i18n-refactor-2

delucis commented Oct 28, 2023 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 28, 2023 •

edited

Loading

Uh oh!

netlify bot commented Oct 28, 2023 •

edited

Loading

Uh oh!

astrobot-houston commented Oct 28, 2023 •

edited

Loading

Uh oh!

delucis Oct 28, 2023

Uh oh!

delucis Oct 28, 2023

Uh oh!

delucis Oct 28, 2023

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	/**
	* Get the BCP-47 language tag for the given locale.
	* @param locale Locale string or `undefined` for the root locale.
	*/
	export function localeToLang(locale: string \| undefined): string {
	const lang = locale ? config.locales?.[locale]?.lang : config.locales?.root?.lang;
	const defaultLang = config.defaultLocale?.lang \|\| config.defaultLocale?.locale;
	return lang \|\| defaultLang \|\| 'en';
	}

Uh oh!

Conversation

delucis commented Oct 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of changes does this PR include?

Description

To-do

Background

Uh oh!

changeset-bot bot commented Oct 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Oct 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

astrobot-houston commented Oct 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

delucis Oct 28, 2023

Choose a reason for hiding this comment

Uh oh!

delucis Oct 28, 2023

Choose a reason for hiding this comment

Uh oh!

delucis Oct 28, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

delucis commented Oct 28, 2023 •

edited

Loading

changeset-bot bot commented Oct 28, 2023 •

edited

Loading

netlify bot commented Oct 28, 2023 •

edited

Loading

astrobot-houston commented Oct 28, 2023 •

edited

Loading