Expose FS translation system to plugins #2578

HiDeoo · 2024-11-05T16:59:02Z

Description

This plugin exposes the file system translation system to Starlight plugins throught the setup hook using a new useTranslations() callback function.

This change requires the addition of a new plugin hook (currently named init, I picked the first thing coming to mind to get started) which now exposes the injectTranslations() callback function (which was previously available in the setup hook).

The documentation so far is only a rough draft to get an idea of everything changed.

Remaining tasks

Restore the docs/astro.config.mjs file
Restore the docs/package.json file
Restore the docs/src/content/i18n/zh-CN.json file
Remove the entire packages/demo-plugin/ directory
Run pnpm i to remove mention of the starlight-demo-plugin package in the lockfile
Remove all remaining // TODO(HiDeoo) comments (if any)
Order the changeset in the release PR so that .changeset/polite-fishes-remain.md comes first (Deprecates the Starlight plugin `setup` hook in favor of the new `config:setup` hook which provides the same functionality.)

changeset-bot · 2024-11-05T16:59:07Z

🦋 Changeset detected

Latest commit: a6661b3

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

This PR includes changesets to release 2 packages

Name	Type
@astrojs/starlight	Minor
@astrojs/starlight-docsearch	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-11-05T16:59:18Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`a6661b3`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67b063b53cd3cd00089e6c77
😎 Deploy Preview	https://deploy-preview-2578--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 site configuration.

HiDeoo · 2024-11-05T16:59:45Z

packages/starlight/integrations/expressive-code/index.ts

 				...otherStyleOverrides,
 			},
-			getBlockLocale: ({ file }) => pathToLocale(file.path, { starlightConfig, astroConfig }),
+			getBlockLocale: ({ file }) => pathToLang(file.path, { astroConfig, starlightConfig }),


Expressive Code technically expects a Starlight language here so I changed it but this is not a bug fix (no changeset) as Expressive Code lower-cases the language identifier anyway.

astrobot-houston · 2024-11-05T16:59:47Z

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.
en	reference/plugins.md	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

This looks great @HiDeoo! Left some suggestions/questions/discussions, but they’re honestly all around the “outside” of the core functionality or on the docs. I think overall this seems very solid 🚀

.changeset/large-balloons-compete.md

packages/starlight/__tests__/plugins/vitest.config.ts

packages/starlight/integrations/expressive-code/index.ts

delucis · 2024-11-07T18:37:51Z

packages/starlight/utils/createTranslationSystem.ts

+// strings. We let TypeScript merge them into a single union type so that plugins with a TypeScript
+// configuration preventing `UserI18nKeys` to be properly inferred can still get auto-completion
+// for built-in UI strings.
+export type I18nKeys = keyof BuiltInStrings | UserI18nKeys | keyof StarlightApp.I18n;


Ahhhhhh, nice fix! 🧠

docs/src/content/docs/reference/plugins.md

HiDeoo · 2024-11-08T09:14:55Z

Thanks for the review 🙌

Holding off on the suggested changes so I can tackle them all at once when we have a clearer idea of what we want to do regarding the name.

* main: (27 commits) i18n(ko-KR): update `site-search.mdx` [ci] release (withastro#2590) Support passing more options to the DocSearch component (withastro#2589) [ci] release (withastro#2587) Add changeset for withastro#2252 (withastro#2588) [ci] format Update dev dependencies (withastro#2582) Build performance optimizations for projects with large sidebars (withastro#2252) Fix a11y CI workflow (withastro#2503) Update `astro-expressive-code` to v0.38 (withastro#2551) Added social icon for Nostr (withastro#2579) [ci] format docs(showcase): add docs.reactbricks.com to showcase (withastro#2586) i18n(ja): Update site-search.mdx (withastro#2577) i18n(ja): Update pages.mdx (withastro#2576) i18n(fr): Update `reference/plugins.mdx` from withastro#2549 (withastro#2574) [ci] format docs: update showcase-sites.astro (withastro#2562) Throw an error if a showcase image does not have the required dimensions (withastro#2573) i18n(ja): Update frontmatter.md (withastro#2566) ...

Co-authored-by: Chris Swithinbank <[email protected]>

HiDeoo · 2024-11-11T14:08:55Z

Updated the branch with the changes discussed above, hope I did not forget anything:

Adds the config:setup hook and deprecate the setup one
- I added a few tests to ensure we make sure to totally remove setup before v1
Renames the new hook to i18n:setup
Cleans up and renames the new path utility to absolutePathToLang
- It's fairly easy to add some checks to ensure the paths are the ones we expect for a document in a content collection altho, this would fail as soon as something like import { Content } from '../../something.md' is used (this would even fail with our EmptyMarkdown file).
- Should we explicitly mention that if it's not matching a configured locale, it's falling back to the default locale?
Adds a test to ensure we migrate @astrojs/starlight-docsearch to the config:setup hook before v1
Adds a new HookParameters utility type and its documentation
- A lot of plugin are already doing something like Parameters<StarlightPlugin['hooks']['setup']>['0']['something'] but now this would be even longer with the addition of a nullable so the new type should help with that like in Astro.
Updates starlight-links-validator to a new version where I refactored some very old legacy types to avoid type errors
- The link validation is currently failing, I've opened [i18nIgnore] Update starlight-links-validator and fix link #2598 to fix this
Updates the useTranslations() documentation & example to mention it's a BCP-47 tag and to use a region subtag in the example

I have a question: this PR adds multiple changesets but I think .changeset/polite-fishes-remain.md should come first. Altho, I don't know if there is a way to enforce that from this PR, right?

Co-authored-by: Chris Swithinbank <[email protected]>

HiDeoo · 2025-01-09T09:22:21Z

I’d guess we should just tweak the CHANGELOG in the release PR when the time comes.

Makes sense, that was also my guess, thanks. I added a new todo to the PR body to remember about that.

delucis

Perfect! Just noticed one detail with the DocSearch update.

packages/docsearch/index.ts

Co-authored-by: Chris Swithinbank <[email protected]>

delucis

Perfect! OK, should be ready to go I think! I’m thinking of trying to get Astro.locals ready too, so that these two changes breaking plugins can go out together. I think we’re almost there.

HiDeoo · 2025-01-09T09:47:08Z

I’m thinking of trying to get Astro.locals ready too, so that these two changes breaking plugins can go out together. I think we’re almost there.

Makes sense 👍 I already gathered some feedback/concerns regarding the route data PR to publish when it's ready for review, really excited about this one 🤩

trueberryless · 2025-01-10T10:42:04Z

I have a question: this PR adds multiple changesets but I think .changeset/polite-fishes-remain.md should come first. Altho, I don't know if there is a way to enforce that from this PR, right?

I'm not 100% sure, but I think that changesets just reads the files alphabetically, which means changing the filename from polite-fishes-remain.md to e.g. attractive-fishes-remain.md should do the trick.

Altho I have to say, I personally would also double check it in the ci PR later, so leaving the ToDo is also my recommendation. Nonetheless, trying it out would be interesting 🤔

~~Reference: In one of my releases you can see that in the patch section it works that way, but that's actually not a trustworthy reference because it could have many other reasons...~~

…me effect in #2578

trueberryless · 2025-02-15T11:02:44Z

Wait, this PR also got merged today?!? Holy moly, how incredible is that! 💝

Co-authored-by: Chris Swithinbank <[email protected]>

* main: (493 commits) i18n(de): update `sidebar.mdx` (withastro#2900) Adding all samples for badges in sidebar as example (withastro#2881) i18n(fr): fix highlighting in `reference/plugins.md` (withastro#2898) i18n(fr): update `reference/plugins` & `guides/i18n` (withastro#2886) i18n(fr): update `reference/overrides` & `guides/sidebar` (withastro#2887) i18n(fr): add `guides/route-data` and `reference/route-data` (withastro#2884) i18n(fr): update `guides/overriding-components` (withastro#2885) i18n(fr): update `reference/configuration` (withastro#2888) i18n(de): update German translation with withastro#2578 (withastro#2882) [ci] format i18n(ru): update some translations (withastro#2895) i18n(de): update `reference/configuration.mdx` (withastro#2883) [ci] format i18n(ko-KR): update `configuration.mdx` (withastro#2892) i18n(ko-KR): update `overrides.md` (withastro#2893) i18n(ko-KR): update `overriding-components.mdx` (withastro#2890) i18n(ko-KR): update `i18n.mdx` and `plugins.md` (withastro#2889) [ci] format i18n(ko-KR): create `guides/route-data.mdx` and `reference/route-data.mdx` (withastro#2896) i18n(ko-KR): update `/resources/plugins.mdx` (withastro#2894) ...

Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]>

feat: exposes fs translation system to plugins

5eb0121

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

HiDeoo commented Nov 5, 2024

View reviewed changes

feat: update ec getBlockLocale() with the change of 2551

9844dc1

delucis reviewed Nov 7, 2024

View reviewed changes

HiDeoo and others added 12 commits November 9, 2024 17:46

refactor: rename plugin hooks

3b79cce

fix: demo plugin lock file

0d73832

fix: add async hook comment

8ddfb98

fix: add ec pathToLang comment

850d3f1

docs: tweak useTranslations documentation

57e8a06

Co-authored-by: Chris Swithinbank <[email protected]>

refactor pathToLang() → absolutePathToLang()

c40f599

test: add test to ensure DocSearch plugin use config:setup hook

fe6e68c

feat: add HookParameters utility type

5ddf2f1

fix: remove absolutePathToLang() error

6f41499

fix: add starlight-links-validator patch

60dbc9c

chore: add HookParameters changeset

b1cb641

HiDeoo mentioned this pull request Nov 10, 2024

[i18nIgnore] Update starlight-links-validator and fix link #2598

Merged

HiDeoo added 3 commits November 10, 2024 16:04

fix: remove temporary starlight-links-validator patch

71cbdb5

docs: update useTranslations() example

5aab231

docs: mention BCP-47 in useTranslations() description

36ef34f

HiDeoo mentioned this pull request Nov 18, 2024

Fix i18n type issue with multiple data content collections #2611

Merged

delucis added 2 commits December 21, 2024 00:28

Merge branch 'main' into pr/2578

80af330

Update Astro version in demo plugin

56baf37

HiDeoo and others added 4 commits January 9, 2025 09:56

refactor: destructure some variables

e00a3b1

Co-authored-by: Chris Swithinbank <[email protected]>

feat: use config:setup hook in docsearch plugin

94927f3

chore: remove demo plugin

8e87088

chore: remove unused import

f543ed9

github-actions bot added the 🌟 docsearch Changes to Starlight’s DocSearch plugin label Jan 9, 2025

delucis reviewed Jan 9, 2025

View reviewed changes

packages/docsearch/index.ts Show resolved Hide resolved

chore: bump starlight peer dependency version in docsearch plugin

e80caa4

Co-authored-by: Chris Swithinbank <[email protected]>

delucis approved these changes Jan 9, 2025

View reviewed changes

delucis added this to the v0.31 milestone Jan 9, 2025

delucis modified the milestones: v0.31, v0.32 Jan 10, 2025

delucis added 4 commits February 6, 2025 11:47

Merge branch 'main' into hd-refactor-inject-translations

498c268

Merge branch 'main' into hd-refactor-inject-translations

1c4b186

Merge branch 'main' into hd-refactor-inject-translations

37398b2

Bump Starlight peer dep for Doscsearch package to 0.32

a6661b3

delucis merged commit f895f75 into withastro:main Feb 15, 2025
16 checks passed

astrobot-houston mentioned this pull request Feb 15, 2025

[ci] release #2861

Merged

delucis added a commit that referenced this pull request Feb 15, 2025

Removes DocSearch plugin changeset as one was already added to the sa…

0496d99

…me effect in #2578

trueberryless added a commit to trueberryless/withastro-starlight that referenced this pull request Feb 15, 2025

update translation with withastro#2578

e94298a

trueberryless mentioned this pull request Feb 15, 2025

i18n(de): update German translation with #2578 #2882

Merged

HiDeoo mentioned this pull request Feb 16, 2025

i18n(fr): update reference/plugins & guides/i18n #2886

Merged

jsparkdev mentioned this pull request Feb 16, 2025

i18n(ko-KR): update i18n.mdx and plugins.md #2889

Merged

delucis added a commit that referenced this pull request Feb 16, 2025

i18n(de): update German translation with #2578 (#2882)

67120a1

Co-authored-by: Chris Swithinbank <[email protected]>

liruifengv mentioned this pull request Mar 23, 2025

i18n(zh-cn): Update i18n.mdx and Update plugins.md #2940

Merged

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

Expose FS translation system to plugins (withastro#2578)

4a243f2

Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]>

Uh oh!

Expose FS translation system to plugins #2578

Expose FS translation system to plugins #2578

Uh oh!

Conversation

HiDeoo commented Nov 5, 2024 • edited by delucis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Remaining tasks

Uh oh!

changeset-bot bot commented Nov 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Nov 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

HiDeoo Nov 5, 2024

Choose a reason for hiding this comment

Uh oh!

astrobot-houston commented Nov 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

delucis Nov 7, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HiDeoo commented Nov 8, 2024

Uh oh!

HiDeoo commented Nov 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HiDeoo commented Jan 9, 2025

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

HiDeoo commented Jan 9, 2025

Uh oh!

trueberryless commented Jan 10, 2025

Uh oh!

Uh oh!

trueberryless commented Feb 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

HiDeoo commented Nov 5, 2024 •

edited by delucis

Loading

changeset-bot bot commented Nov 5, 2024 •

edited

Loading

netlify bot commented Nov 5, 2024 •

edited

Loading

astrobot-houston commented Nov 5, 2024 •

edited

Loading

HiDeoo commented Nov 11, 2024 •

edited

Loading