Directive Aside title doesn't respect astro i18n

[margarizaldi]

What version of starlight are you using?

0.37.6

What version of astro are you using?

5.17.2

What package manager are you using?

pnpm

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

Aside title when using directive syntax :::note does's respect the astro i18n config.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-nrmod2zp?file=src%2Fcontent%2Fdocs%2Findex.mdx

Participation

• I am willing to submit a pull request for this issue.

[HiDeoo]

Thanks for the feedback 🙌

I can confirm this is an issue at the moment.

First, I'd like to note that your documented workaround is actually the recommended approach to configure i18n, and relying on the Astro’s i18n config option is only supported for more advanced i18n scenarios (which may be your case, but if not, you can safely use your workaround as a long-term solution).

Now, regarding the issue itself, I'll share my investigation notes here for now:

• We run plugins if any (which can update the Starlight config), and generate some translation helpers that both can be used by plugins in their own code and by Starlight itself to access translations in remark plugins for examples (which is what happens when using an aside directive).
• After that, we process the i18n config, which means either generating an Astro i18n config from the Starlight config or updating the Starlight config based on the Astro i18n config.

In your case, since you have an Astro i18n config, the Starlight config is updated based on that, but the translation helpers are created before that, so they don't have access to the updated config, which causes them to not work as expected.

A quite easy fix for the linked reproduction would be to move the i18n config processing right before the translation helpers creation. I tested locally and this works as expected.

Altho, this raises a few more issues:

• Plugins receive the user provided Starlight configuration and can update the Starlight config, which currently includes updating the i18n config. This means that for the translation helpers to have access to the i18n config potentially updated by plugins, we would need to re-process the i18n config if a plugin updates the Starlight config. This brings two issues:
  • If a Starlight i18n config is provided, we can easily re-process the i18n config when a plugin update the Starlight config. For the absolutePathToLang helper, this would be enough to make it work as expected. Altho, for useTranslations, this is a bit more complicated. The creation of such helper relies on the i18n config, and is asynchronous (due to i18next.init() being async). Both updateConfig and useTranslations are synchronous, so we can't really re-create that useTranslations helper as we would need to for it to use the updated i18n config.
  • If we are in the case of a user that provided an Astro i18n config, and a plugin updates the Starlight i18n config, this is an unsupported scenario right now, as we can't really reconcile them both (even more considering that the plugin may have updated the Starlight i18n config based on the user provided Starlight config, which is empty in this scenario).

This is definitely a tricky issue, a bit of a chicken and egg problem and I would definitely need to think more about it. Right now, the few attemps I tried always involve some breaking changes for plugins (altho I'm not sure yet if this is fixable without a breaking change somehow) that don't cover all edge cases. Another possible solution coming to mind, which would still involve some breaking changes for plugins, is to prevent plugins from updating the Starlight i18n config. No plugins having ever done that comes to mind, I'm not quite even sure what would be the use case for that, but I definitely need to think more about it.

Also open to any suggestions anyone may have of course!

[margarizaldi]

@HiDeoo thanks for the reply.

Currently I don't have such complex i18n scenario, the workaround is just fine, and I'm ok.

But,

I feel something is weird, I get an error when I define both astro i18n and starlight locale config at the same time.

In my opinion, we shouldn't get any error, because:

• config.i18n belongs to astro, starlight can use it as needed
• starlight.locales is an exclusive starlight config, may override astro i18n only in scope of starlight.

To be honest, that error makes me worrying and asking this question:

• If I want to create homepage (foo.com) and docs (foo.com/docs) using the same astro project, will the starlight config applied to wider astro project?

---

Disclaimer: I'm totally new to astro and starlight so I realize that too many things I don't understand both in astro and starlight. Also not sure whether it is possible or not, to use starlight as part of wider astro project.

Regards.

[HiDeoo]

Currently I don't have such complex i18n scenario, the workaround is just fine, and I'm ok.

Perfect, so following our "Configure i18n" guide should be enough (which is currently your workaround).

What will happen internally, is that Starlight will automatically take your starlight.locales and generate and apply the correct config.i18n configuration for you. It will work on your Starlight documentation and your homepage, and they both will use the same i18n configuration.

We could probably improve a bit this part of the documentation and see if we can make it clearer, I'm taking note of it.

Regarding the setup for a homepage and Starlight at a subpath, this is totally possible. You may already have found it, but we have a small guide about it here but sharing in case you haven't: https://starlight.astro.build/manual-setup/#use-starlight-at-a-subpath (the guide use foo.com/guides as an example, but for your case with foo.com/docs, your documentation pages will be located in a src/content/docs/docs/ directory (notice the double docs directory for the subpath)).

[margarizaldi]

What will happen internally, is that Starlight will automatically take your starlight.locales and generate and apply the correct config.i18n configuration for you. It will work on your Starlight documentation and your homepage, and they both will use the same i18n configuration.

Ah, it's great for me to know that...

Alright, thank you very much...

Though this issue will remain opened, I really appreciate all your efforts to reply me in this discussion, also all your works for us...

[delucis]

We do already have the i18n:setup hook in the plugin API which we currently use for injectTranslations(). I wonder if we should also move any i18n configuration changes to that hook? So a plugin that modifies i18n, should do it in that earlier step, not after, and all plugins would get a consistent i18n configuration.

[HiDeoo]

I wonder if we should also move any i18n configuration changes to that hook?

This was one of my potential idea when I mentioned preventing plugins from updating the Starlight i18n config (in updateConfig basically). Altho, it may still be a bit tricky, because if a plugin want to modify the i18n config, it should be able to do so knowing exactly what is going on, e.g. what did the user config look like:

• No i18n config provided by the user (in this case, we still generate an Astro i18n config but don't generate a Starlight i18n config)
• Starlight i18n config provided by the user (we generate an Astro i18n config that is equivalent to the Starlight i18n config provided by the user)
• Astro i18n config provided by the user (we provide a Starlight i18n config that is equivalent)

I definitely need to play with the idea, but I wonder if we would need to (and how) surface all cases so the plugin can act accordingly, depending on what the user config looks like, then convert it back to the Astro i18n config format but also pass it down verbatim to other plugins that may want to update the Starlight i18n config too.