feat(astro:i18n): add docs for some missing public utilities

[ArmandPhilippot]

Description (required)

The i18nNoLocaleFoundInPath error suggests to use the pathHasLocale helper... but I couldn't find it in the docs. Actually we're missing a few utilities in the astro:i18n reference.

Adds documentation for:

• normalizeTheLocale() (since astro:i18n release? Maybe this was made public later but I couldn't find a PR suggesting this)
• pathHasLocale() (added in 4.6.0, feat(i18n): manual routing astro#10193)
• toCodes() (added in 4.0.0, feat(i18n): refined locales astro#9200)
• toPaths() (added in 4.0.0, feat(i18n): refined locales astro#9200)

I'm not quite sure about the use cases, so I added examples based on the getPathByLocale() one.

Related issues & labels (optional)

• Suggested label: add new content

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2167b9f
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/690b6a71ee9e170008a131ff
😎 Deploy Preview	https://deploy-preview-12264--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

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

File	Note
en/reference/modules/astro-i18n.mdx	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.

[sarah11918]

Thank you so much, @ArmandPhilippot ! I'm going to ask @ematipico to review this, make sure everything here should be in docs etc. before I look too closely! 🙌

[sarah11918]

Noting that Ema is on a few weeks of holidays right now, so we'll get around to this one, eventually! 😄

[HiDeoo]

Thanks for the PR, great catch 🕵️

We talked about it during T&D with Ema, and here is a brief overview of the action items we decided would be the best:

• We want to document them
• Looks like normalizeThePath is missing?
• The actual code should be moved away from internal code (this is a re-export)
• The actual code should be enhanced with some JSDoc and better documentation

The last 2 points should be done in the Astro repo.

[ArmandPhilippot]

• I was checking for normalizeThePath and it is indeed exported from the i18n module but not from the i18n virtual module. So, you can't import it from "astro:i18n". So, should we export it like the others?
• I'm not sure I get "moved away from internal code", do you mean this should be declared in packages/astro/src/i18n/utils.ts instead of packages/astro/src/i18n/index.ts?
• Yeah, that makes sense if they are public!

[HiDeoo]

• I was checking for normalizeThePath and it is indeed exported from the i18n module but not from the i18n virtual module. So, you can't import it from "astro:i18n". So, should we export it like the others?

Good catch, we definitely only want to document what is public, I probably got confused during the T&D call.

• I'm not sure I get "moved away from internal code", do you mean this should be declared in packages/astro/src/i18n/utils.ts instead of packages/astro/src/i18n/index.ts?

May need to double check if Ema had a specific idea in mind, but I guess the idea was to move public code away from i18n/index.ts so its content is no longer a mix of public and internal code.

[HiDeoo]

Left some extra thoughts that came to mind after T&D, mostly around trying to make the examples more obvious when such APIs could be useful. Let me know what you think.

[sarah11918]

When y'all are happy with this, no need to wait for me!

[ArmandPhilippot]

Noted, thanks! I was waiting for the core's PR because this is new content but if you don't see anything wrong here, then I guess it's safe to merge it with Ema and Yan approval! 😄

[yanthomasdev]

LGTM!

[ArmandPhilippot]

Since no one else has intervened since Yan's approval, I guess everyone is happy and this one is ready to be merged! If not, you still have time while the branch is updating. 😄