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

Co-authored-by: HiDeoo <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Yan <[email protected]>

Author: 4 people

src/content/docs/en/reference/modules/astro-i18n.mdx

@@ -40,6 +40,10 @@ import {
   notFound,
   middleware,
   requestHasLocale,
+  normalizeTheLocale,
+  pathHasLocale,
+  toCodes,
+  toPaths
  } from 'astro:i18n';
 ```
 
@@ -337,3 +341,116 @@ export const onRequest = defineMiddleware(async (context, next) => {
   return new Response("Not found", { status: 404 });
 })
 ```
+
+### `normalizeTheLocale()`
+
+<p>
+
+**Type:** `(locale: string) => string`
+</p>
+
+Replaces underscores (`_`) with hyphens (`-`) in the given locale before returning a lowercase version.
+
+```astro title="src/pages/index.astro"
+---
+import { normalizeTheLocale } from "astro:i18n";
+
+normalizeTheLocale("it_VT") // returns `it-vt`
+// Assuming the current locale is `"pt-PR"`:
+normalizeTheLocale(Astro.currentLocale) // returns `pt-pt`
+---
+```
+
+### `pathHasLocale()`
+
+<p>
+
+**Type:** `(path: string) => boolean`<br />
+<Since v="4.6.0" />
+</p>
+
+Checks whether the given path contains a configured locale.
+
+This is useful to prevent errors before using an i18n utility that relies on a locale from a URL path.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  i18n: {
+    locales: [
+      { codes: ["it-VT", "it"], path: "italiano" },
+      "es"
+    ]
+  }
+})
+```
+
+```astro title="src/pages/index.astro"
+---
+import { pathHasLocale } from "astro:i18n";
+
+pathHasLocale("italiano"); // returns `true`
+pathHasLocale("es"); // returns `true`
+pathHasLocale('/es/blog/'); // returns `true`
+pathHasLocale("it-VT"); // returns `false`
+---
+```
+
+### `toCodes()`
+
+<p>
+
+**Type:** `(locales: Locales) => string[]`<br />
+<Since v="4.0.0" />
+</p>
+
+Retrieves the configured locale codes for each locale defined in your configuration. When multiple codes are associated to a locale, only the first one will be added to the array.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  i18n: {
+    locales: [
+      { codes: ["it-VT", "it"], path: "italiano" },
+      "es"
+    ]
+  }
+})
+```
+
+```astro title="src/pages/index.astro"
+---
+import { i18n } from "astro:config/client";
+import { toCodes } from "astro:i18n";
+
+toCodes(i18n!.locales); // ["it-VT", "es"]
+---
+```
+
+### `toPaths()`
+
+<p>
+
+**Type:** `(locales: Locales) => string[]`<br />
+<Since v="4.0.0" />
+</p>
+
+Retrieves the configured locale paths for each locale defined in your configuration.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  i18n: {
+    locales: [
+      { codes: ["it-VT", "it"], path: "italiano" },
+      "es"
+    ]
+  }
+})
+```
+
+```astro title="src/pages/index.astro"
+---
+import { i18n } from "astro:config/client";
+import { toPaths } from "astro:i18n";
+
+toPaths(i18n!.locales); // ["italiano", "es"]
+---
+```