4.6.0 minor docs update

src/content/docs/en/guides/dev-toolbar.mdx

@@ -34,7 +34,7 @@ The dev toolbar aims to provide a quick and easy way to catch common issues duri
 
 ### Settings
 
-The Settings app allows you to toggle different settings for the development toolbar, such as verbose logging, and the ability to disable notifications.
+The Settings app allows you to configure options for the development toolbar, such as verbose logging, disabling notifications, and adjusting its placement on your screen.
 
 ## Extending the dev toolbar
 

src/content/docs/en/install/auto.mdx

@@ -13,7 +13,7 @@ Read our [step-by-step manual installation guide](/en/install/manual/) instead.
 :::
 #### Prerequisites
 
-- **Node.js** - `v18.14.1` or higher.
+- **Node.js** - `v18.17.1` or `v20.3.0` or higher. ( `v19` is not supported.)
 - **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode).
 - **Terminal** - Astro is accessed through its command-line interface (CLI).
 

src/content/docs/en/reference/api-reference.mdx

@@ -238,7 +238,7 @@ Sets the cookie `key` to the given value. This will attempt to convert the cooki
 **Type:** `(key: string, options?: CookieDeleteOptions) => void`
 </p>
 
-Marks the cookie as deleted. Once a cookie is deleted `Astro.cookies.has()` will return `false` and `Astro.cookies.get()` will return an [`AstroCookie`](#astrocookie) with a `value` of `undefined`. Options allow setting the `domain` and `path` of the cookie to delete.
+Marks the cookie as deleted. Once a cookie is deleted `Astro.cookies.has()` will return `false` and `Astro.cookies.get()` will return an [`AstroCookie`](#astrocookie) with a `value` of `undefined`. Options available when deleting a cookie are: `domain`, `path`, `httpOnly`, `sameSite`, and `secure`.
 
 ##### `headers`
 
@@ -1395,6 +1395,282 @@ This function can be used by integrations/adapters to programmatically execute t
 
 A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.
 
+## Internationalization (`astro:i18n`)
+
+<p><Since v="3.5.0" /></p>
+
+This module provides functions to help you create URLs using your project's configured locales.
+
+Creating routes for your project with the i18n router will depend on certain configuration values you have set that affect your page routes. When creating routes with these functions, be sure to take into account your individual settings for:
+
+- [`base`](/en/reference/configuration-reference/#base)
+- [`trailingSlash`](/en/reference/configuration-reference/#trailingslash)
+- [`build.format`](/en/reference/configuration-reference/#buildformat)
+- [`site`](/en/reference/configuration-reference/#site)
+
+Also, note that the returned URLs created by these functions for your `defaultLocale` will reflect your `i18n.routing` configuration.
+
+For features and usage examples, [see our i18n routing guide](/en/guides/internationalization/).
+
+### `getRelativeLocaleUrl()` 
+
+`getRelativeLocaleUrl(locale: string, path?: string,  options?: GetLocaleOptions): string`
+
+Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error. 
+
+```astro
+---
+getRelativeLocaleUrl("fr");
+// returns /fr
+
+getRelativeLocaleUrl("fr", "");
+// returns /fr
+
+getRelativeLocaleUrl("fr", "getting-started");
+// returns /fr/getting-started
+
+getRelativeLocaleUrl("fr_CA", "getting-started", {
+  prependWith: "blog"
+}); 
+// returns /blog/fr-ca/getting-started
+
+getRelativeLocaleUrl("fr_CA", "getting-started", {
+  prependWith: "blog",
+  normalizeLocale: false
+}); 
+// returns /blog/fr_CA/getting-started
+---
+```
+
+### `getAbsoluteLocaleUrl()` 
+
+`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string` 
+
+Use this function to retrieve an absolute path for a locale when [`site`] has a value. If [`site`] isn't configured, the function returns a relative URL. If the locale doesn't exist, Astro throws an error.
+
+
+```astro title="src/pages/index.astro"
+---
+// If `site` is set to be `https://example.com`
+
+getAbsoluteLocaleUrl("fr"); 
+// returns https://example.com/fr
+
+getAbsoluteLocaleUrl("fr", ""); 
+// returns https://example.com/fr
+
+getAbsoluteLocaleUrl("fr", "getting-started"); 
+// returns https://example.com/fr/getting-started
+
+getAbsoluteLocaleUrl("fr_CA", "getting-started", {
+  prependWith: "blog"
+}); 
+// returns https://example.com/blog/fr-ca/getting-started
+
+getAbsoluteLocaleUrl("fr_CA", "getting-started", {
+  prependWith: "blog",
+  normalizeLocale: false
+}); 
+// returns https://example.com/blog/fr_CA/getting-started
+---
+```
+
+### `getRelativeLocaleUrlList()` 
+
+`getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]`
+
+
+Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales.
+
+
+### `getAbsoluteLocaleUrlList()` 
+
+`getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]`
+
+Use this like [`getAbsoluteLocaleUrl`](/en/guides/internationalization/#custom-locale-paths) to return a list of absolute paths for all the locales.
+
+### `getPathByLocale()` 
+
+`getPathByLocale(locale: string): string`
+
+A function that returns the `path` associated to one or more `codes` when [custom locale paths](/en/guides/internationalization/#custom-locale-paths) are configured.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  i18n: {
+    locales: ["es", "en", {
+      path: "french",
+      codes: ["fr", "fr-BR", "fr-CA"]
+    }]
+  }
+})
+```
+
+```astro title="src/pages/index.astro"
+---
+getPathByLocale("fr"); // returns "french"
+getPathByLocale("fr-CA"); // returns "french"
+---
+```
+
+### `getLocaleByPath`
+
+ `getLocaleByPath(path: string): string`
+
+A function that returns the `code` associated to a locale `path`.
+
+```js title="astro.config.mjs"
+export default defineConfig({
+  i18n: {
+    locales: ["es", "en", {
+      path: "french",
+      codes: ["fr", "fr-BR", "fr-CA"]
+    }]
+  }
+})
+```
+
+```astro title="src/pages/index.astro"
+---
+getLocaleByPath("french"); // returns "fr" because that's the first code configured
+---
+```
+
+### `redirectToDefaultLocale()`
+
+`redirectToDefaultLocale(context: APIContext, statusCode?: ValidRedirectStatus): Promise<Response>`
+
+<p><Since v="4.6.0" /></p>
+
+:::note
+Available only when `i18n.routing` is set to `"manual"`
+:::
+
+A function that returns a `Response` that redirects to the `defaultLocale` configured. It accepts an optional valid redirect status code.
+
+```js title="middleware.js"
+import { defineMiddleware } from "astro:middleware";
+import { redirectToDefaultLocale } from "astro:i18n";
+
+export const onRequest = defineMiddleware((context, next) => {
+  if (context.url.pathname.startsWith("/about")) {
+    return next();
+  } else {
+    return redirectToDefaultLocale(context, 302);
+  }
+})
+```
+
+### `redirectToFallback()`
+
+`redirectToFallback(context: APIContext, response: Response): Promise<Response>`
+
+<p><Since v="4.6.0" /></p>
+
+:::note
+Available only when `i18n.routing` is set to `"manual"`
+:::
+
+A function that allows you to use your [`i18n.fallback` configuration](/en/reference/configuration-reference/#i18nfallback) in your own middleware.
+
+```js title="middleware.js"
+import { defineMiddleware } from "astro:middleware";
+import { redirectToFallback } from "astro:i18n";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const response = await next();
+  if (response.status >= 300) {
+    return redirectToFallback(context, response)
+  }
+  return response;
+})
+```
+
+### `notFound()`
+
+`notFound(context: APIContext, response: Response): Promise<Response>`
+
+<p><Since v="4.6.0" /></p>
+
+:::note
+Available only when `i18n.routing` is set to `"manual"`
+:::
+
+Use this function in your routing middleware to return a 404 when:
+- the current path isn't a root. e.g. `/` or `/<base>`
+- the URL doesn't contain a locale
+
+When a `Response` is passed, the new `Response` emitted by this function will contain the same headers of the original response.
+
+```js title="middleware.js"
+import { defineMiddleware } from "astro:middleware";
+import { notFound } from "astro:i18n";
+
+export const onRequest = defineMiddleware((context, next) => {
+  const pathNotFound = notFound(context);
+  if (pathNotFound) {
+    return pathNotFound;
+  }
+  return next();
+})
+```
+
+### `middleware()`
+
+`middleware(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean })`
+
+<p><Since v="4.6.0" /></p>
+
+:::note
+Available only when `i18n.routing` is set to `"manual"`
+:::
+
+A function that allows you to programmatically create the Astro i18n middleware.
+
+This is use useful when you still want to use the default i18n logic, but add only a few exceptions to your website.
+
+```js title="middleware.js"
+import { middleware } from "astro:i18n";
+import { sequence, defineMiddleware } from "astro:middleware";
+
+const customLogic = defineMiddleware(async (context, next) => {
+  const response = await next();
+
+  // Custom logic after resolving the response.
+  // It's possible to catch the response coming from Astro i18n middleware.
+
+  return response;
+});
+
+export const onRequest = sequence(customLogic, middleware({
+	prefixDefaultLocale: true,
+	redirectToDefaultLocale: false
+}))
+```
+
+### `requestHasLocale()`
+
+`requestHasLocale(context: APIContext): boolean`
+
+<p><Since v="4.6.0" /></p>
+
+:::note
+Available only when `i18n.routing` is set to `"manual"`
+:::
+
+Checks whether the current URL contains a configured locale. Internally, this function will use `APIContext#url.pathname`.
+
+```js title="middleware.js"
+import { defineMiddleware } from "astro:middleware";
+import { requestHasLocale } from "astro:i18n";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  if (requestHasLocale(context)) {
+    return next();
+  }
+  return new Response("Not found", { status: 404 });
+})
+```
 
 ## Built-in Components
 

src/content/docs/en/reference/configuration-reference.mdx

@@ -1107,6 +1107,18 @@ When `true`, all URLs will display a language prefix.
 URLs will be of the form `example.com/[locale]/content/` for every route, including the default language.
 Localized folders are used for every language, including the default.
 
+```js
+export default defineConfig({
+	i18n: {
+		defaultLocale: "en",
+		locales: ["en", "fr", "pt-br", "es"],
+		routing: {
+			prefixDefaultLocale: true,
+		}
+	}
+})
+```
+
 #### i18n.routing.redirectToDefaultLocale
 
 <p>
@@ -1134,6 +1146,30 @@ export default defineConfig({
 })
 ```
 
+#### i18n.routing.manual
+
+<p>
+
+**Type:** `string`<br />
+<Since v="4.6.0" />
+</p>
+
+When this option is enabled, Astro will **disable** its i18n middleware so that you can implement your own custom logic. No other `routing` options (e.g. `prefixDefaultLocale`) may be configured with `routing: "manual"`.
+
+You will be responsible for writing your own routing logic, or executing Astro's i18n middleware manually alongside your own.
+
+```js
+export default defineConfig({
+	i18n: {
+		defaultLocale: "en",
+		locales: ["en", "fr", "pt-br", "es"],
+		routing: {
+			prefixDefaultLocale: true,
+		}
+	}
+})
+```
+
 ## Legacy Flags
 
 To help some users migrate between versions of Astro, we occasionally introduce `legacy` flags.
@@ -1340,7 +1376,34 @@ export default defineConfig({
 });
 ```
 
-Both page routes built and URLs returned by the `astro:i18n` helper functions [`getAbsoluteLocaleUrl()`](/en/guides/internationalization/#getabsolutelocaleurl) and [`getAbsoluteLocaleUrlList()`](/en/guides/internationalization/#getabsolutelocaleurllist) will use the options set in `i18n.domains`.
+Both page routes built and URLs returned by the `astro:i18n` helper functions [`getAbsoluteLocaleUrl()`](/en/reference/api-reference/#getabsolutelocaleurl) and [`getAbsoluteLocaleUrlList()`](/en/reference/api-reference/#getabsolutelocaleurllist) will use the options set in `i18n.domains`.
 
 See the [Internationalization Guide](/en/guides/internationalization/#domains-experimental) for more details, including the limitations of this experimental feature.
 
+### experimental.security
+
+<p>
+
+**Type:** `boolean`<br />
+**Default:** `false`<br />
+<Since v="4.6.0" />
+</p>
+
+Enables CSRF protection for Astro websites.
+
+The CSRF protection works only for pages rendered on demand (SSR) using `server` or `hybrid` mode. The pages must opt out of prerendering in `hybrid` mode.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  output: "server",
+  experimental: {
+    security: {
+      csrfProtection: {
+        origin: true
+      }
+    }
+  }
+})
+```
+