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)

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

🦋 Changeset detected

Latest commit: 36ef34f

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
starlight-demo-plugin	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 · 2024-11-05T16:59:18Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`36ef34f`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67320f48d9677500080ed596
😎 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

@@ -152,7 +151,7 @@ export function getStarlightEcConfigPreprocessor({
 				},
 				...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 🚀

delucis · 2024-11-07T17:28:48Z

.changeset/large-balloons-compete.md

+  name: 'plugin-with-translations',
+  hooks: {
+-   setup({ injectTranslations }) {
+   init({ injectTranslations }) {


Regarding the hook naming, I was wondering if we should follow the colon-separated pattern used by Astro integrations? Both of these hooks are essentially “setup” hooks, so the new hook would become i18n:setup() or translations:setup() or something. i18n is nice because it’s short, but maybe a bit misleading if you don’t set up i18n config here, only translations.

Ideally maybe we’d even align both hooks like this, although that’s a bit of an annoying breaking change to impose on everyone:

interface Plugin { name: string; hooks: { 'i18n:setup': (opts: I18nSetupOptions) => void; 'config:setup': (opts: ConfigSetupOptions) => void; } }

That said, I don’t know if there’s a future where this starts to be silly. Like is there anything Starlight would do/need that is not “setup”? I guess we might have a config:done hook like Astro does that gives access to the final resolved Starlight config?

I guess the flipside of an i18n-focused naming is if we think this “early” initialization phase is going to be used for other things (which your current docs kind of suggests: “initialization function called before Starlight is initialized (during the astro:config:setup integration hook)”). In that case something more focused on lifecycle like pre:setup (😅) or whatever could make sense. I find it hard to evaluate the probability of that, so open to hear opinions. The i18n approach does kind of help communicate use case up front as well, so maybe it’s OK.

(If we do rename setup() it doesn’t have to be in this PR and can be done in a backwards compatible way where we still call setup() if defined but mark it as deprecated.)

Regarding the hook naming, I was wondering if we should follow the colon-separated pattern used by Astro integrations?

I personally like that idea.

but maybe a bit misleading if you don’t set up i18n config here, only translations.

I guess, altho if we compare with our configuration file, we use the locales key to configure i18n, not i18n so I think it's fine.

I guess we might have a config:done hook like Astro does that gives access to the final resolved Starlight config?

Maybe, I don't really see the need for it right now and I'm not even sure what you would do with it.

which your current docs kind of suggests: “initialization function called before Starlight is initialized (during the astro:config:setup integration hook)”

Well, to be fair, like I said, I didn't really put any thought at all about the naming of the hook, and I documented it mostly to give an overview of all the changes and mimick what we had before.

I think if we ever need something else to be done before config:setup that is not i18n, we could still add an xyz:setup and call it before config:setup like we do with i18n:setup and it would be fine.

If we do rename setup() it doesn’t have to be in this PR and can be done in a backwards compatible way where we still call setup() if defined but mark it as deprecated.

I think we maybe do want to do that at the same time, would be easier to communicate and organize docs? And we can still soft deprecate the setup method in the code so it's still run.

OK, that sounds good! So if you think i18n is not problematic, I think it’s nice to have that concise hook name. And +1 to do the backwards compatible deprecation of setup in favour of config:setup.

Regarding what you might do with a config:done: most often I see the astro:config:done hook used to share the final config with some other code via the integration closure, e.g.

function integration() { const lazy: { config?: AstroConfig } = {}; return { name: 'example', hooks: { 'astro:config:setup'() { // add something referencing `lazy` e.g. a Vite plugin // that will run _after_ the done hook but wants the // final config shape }, 'astro:config:done'({config}) { lazy.config = config; }, }, }; }

But not suggesting we add that now. No point until some more clear needs emerge.

Perfect, I'll get started asap on the new changes, thanks again.

delucis · 2024-11-07T17:31:27Z

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

@@ -63,6 +59,34 @@ export default defineVitestConfig({
 						},
 					});
 				},
+				async setup({ config, updateConfig, useTranslations, pathToLang }) {
+					await Promise.resolve();


Is this here for a reason or is it just left over from some debugging?

Oh… I see it was already there in the previous version of this hook. I guess my question still stands though 😅

Maybe it’s ensuring the hook is really async to test that? Whatever it is, if it’s important to keep, it’s probably a good idea to add a comment for next time I’m reviewing this and confused.

I'll add a comment, this is mostly to ensure type-wise it supports async setup() while avoiding to add a type test for it as type tests are still a bit broken within a Vitest workspace setup like we have.

delucis · 2024-11-07T18:36:44Z

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

-import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
-import { pathToLocale } from '../shared/pathToLocale';
+import type { StarlightConfig, StarlightPlugin } from '../../types';
+import { pathToLang } from '../shared/pathToLang';


Remind me why EC uses this rather than the one passed from the plugins instance?

Maybe this deserves a comment somewhere, but it's for the <Code> component basically which runs in a different context.

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! 🧠

delucis · 2024-11-07T18:57:54Z