feat: support customize i18n translation

[wych42]

Describe the pull request

Adds internationalization (i18n) support for all UI strings in the generated documentation.

Why

Need localization UI strings when publish API site to non-english speaking users.

How

By uses Starlight’s UI translation system, by allow user to override UI labels in config src/content/i18n/{locale}.json

Screenshots

[changeset-bot]

🦋 Changeset detected

Latest commit: b9d2dcb

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

This PR includes changesets to release 1 package

Name	Type
starlight-openapi	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

[vercel]

@wych42 is attempting to deploy a commit to the HiDeoo's projects Team on Vercel.

A member of the Team first needs to authorize it.

[HiDeoo]

Thanks for the pull request.

By quickly skimming through the changes (I did not really take a deep look yet), it looks like this PR currently only handles UI strings translations. Am I correct?

To add complete internationalization support, I think we also need to:

• Generates locale-specific pages depending on the Starlight configuration, e.g. if no locale is set, keep the behavior as is; but if we have multiple locales, generate all pages for each locale.
• All links should be locale-aware, meaning that if a user is browsing the French version of the site, all internal links should point to the French pages.
• Take into account if a root locale is set or not, and adjust the URL structure accordingly.

In plugins like this one mostly generating pages, this can definitely be quite a bit of work (for example, that's what the starlight-blog plugin does and could be used as a reference). Let me know if you are interested in working on this further, or if you would prefer to have me take over from here when I have some time.

[wych42]

Thanks for the pull request.

By quickly skimming through the changes (I did not really take a deep look yet), it looks like this PR currently only handles UI strings translations. Am I correct?

To add complete internationalization support, I think we also need to:

• Generates locale-specific pages depending on the Starlight configuration, e.g. if no locale is set, keep the behavior as is; but if we have multiple locales, generate all pages for each locale.
• All links should be locale-aware, meaning that if a user is browsing the French version of the site, all internal links should point to the French pages.
• Take into account if a root locale is set or not, and adjust the URL structure accordingly.

In plugins like this one mostly generating pages, this can definitely be quite a bit of work (for example, that's what the starlight-blog plugin does and could be used as a reference). Let me know if you are interested in working on this further, or if you would prefer to have me take over from here when I have some time.

Thanks for the suggestion and the starlight-blog reference!

I looked into locale-aware generation, but I wanted to clarify the use case first. Currently, I achieved multi-locale API docs by specifying the locale prefix in base:

starlightOpenAPI([
   { base: 'api',    schema: './specs/en/openapi.yaml', label: 'API' },
   { base: 'ja/api', schema: './specs/ja/openapi.yaml', label: 'API (日本語)' },
])

With this approach:

• Sidebar correctly filters to show only the current locale's API
• Internal links stay within the current locale
• Root locale (defaultLocale: 'root') works as expected (no URL prefix for default language)

Given that this already works, I'm not confidence about what specific improvements you had in mind with the locale-aware generation approach? For example: is it automatic generation from a single schema across all configured Starlight locales? or a cleaner config API (e.g., locales: { en: {...}, ja: {...} }) instead of multiple configs or something else?

I'm happy to implement once I'm aligned with your concerns. and it's totally fine if you want to take over.

[HiDeoo]

Oh, you bring a really good point that I didn't consider before, and maybe we should have gone through an issue to discuss it before moving on to the implementation.

For example, let's say you have this simple basic usage:

starlightOpenAPI([
  {
    base: "api",
    schema: "../schemas/api-schema.yaml",
  },
]);

But your website is supporting two locales, e.g.

locales: {
	root: { label: 'English', lang: 'en' },
	fr: { label: 'Français', lang: 'fr' },
};

If you visit the /api/ page, you get the API docs as expected. However, if you're using the language picker to switch to French, you would get redirected to /fr/api/, which would result in a 404 error. That behavior is not compatible with Starlight's internationalization principles and probably not what users would expect.

However, it looks like in your case, you're using different schemas for different locales? Am I correct in assuming that and the content of the schemas is using a different language per schema?

If so, this is definitely a use case I hadn't considered before and which could be tricky to reconcile with the previous one as I guess both use cases are valid and would need to be supported. Maybe there is also the case where you have 3 locales configured, but only 2 of them have specific API docs, while the 3rd one should fallback to another one.

Not quite sure yet what would be the best approach here, but I guess this definitely require more thoughts and discussions before deciding on anything. Maybe even collect more feedback from other users 🤔

[wych42]

Sure. Agree to move this to issue for more discussions.

Yes, the content of the schemas is using a different language per schema.

Actually I do have three locales: en, ja, kr, and each has its own translation for the same content. But I think the case do exists for some locales can fallback to other locale, like en-GB can fallback to en-US?