From 933f9f274dbfa5cb627d2d887cf95ef585b4325b Mon Sep 17 00:00:00 2001
From: Emanuele Stoppa <my.burning@gmail.com>
Date: Tue, 5 Dec 2023 15:09:13 +0000
Subject: [PATCH] fix: docs placement and wording (#9316)

* fix: docs placement and wording

* more changes

* Update packages/astro/src/@types/astro.ts

Co-authored-by:  Matthew Phillips <matthew@skypack.dev>

* apply Sarah's suggestion

* Remove  tag

---------

Co-authored-by: Matthew Phillips <matthew@skypack.dev>
Co-authored-by: = <otterlord.dev@gmail.com>
---
 packages/astro/src/@types/astro.ts | 42 +++++++++++++-----------------
 1 file changed, 18 insertions(+), 24 deletions(-)

diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts
index a34f24ffa696..fb623d8c20f7 100644
--- a/packages/astro/src/@types/astro.ts
+++ b/packages/astro/src/@types/astro.ts
@@ -1368,15 +1368,6 @@ export interface AstroUserConfig {
 	 */
 	legacy?: object;
 
-	/**
-	 * @docs
-	 * @kind heading
-	 * @name Experimental Flags
-	 * @description
-	 * Astro offers experimental flags to give users early access to new features.
-	 * These flags are not guaranteed to be stable.
-	 */
-
 	/**
 	 * @docs
 	 * @name i18n
@@ -1385,14 +1376,13 @@ export interface AstroUserConfig {
 	 * @type {object}
 	 * @description
 	 *
-	 * Configures experimental i18n routing and allows you to specify some customization options.
+	 * Configures i18n routing and allows you to specify some customization options.
 	 *
 	 * See our guide for more information on [internationalization in Astro](/en/guides/internationalization/)
 	 */
 	i18n?: {
 		/**
 		 * @docs
-		 * @kind h4
 		 * @name i18n.defaultLocale
 		 * @type {string}
 		 * @version 3.5.0
@@ -1405,7 +1395,6 @@ export interface AstroUserConfig {
 		defaultLocale: string;
 		/**
 		 * @docs
-		 * @kind h4
 		 * @name i18n.locales
 		 * @type {Locales}
 		 * @version 3.5.0
@@ -1421,7 +1410,6 @@ export interface AstroUserConfig {
 
 		/**
 		 * @docs
-		 * @kind h4
 		 * @name i18n.fallback
 		 * @type {Record<string, string>}
 		 * @version 3.5.0
@@ -1437,14 +1425,12 @@ export interface AstroUserConfig {
 		 *
 		 * ```js
 		 * export default defineConfig({
-		 * 	experimental: {
-		 * 		i18n: {
-		 * 			defaultLocale: "en",
-		 * 			locales: ["en", "fr", "pt-br", "es"],
-		 * 			fallback: {
-		 * 				pt: "es",
-		 * 			  fr: "en"
-		 * 			}
+		 * 	i18n: {
+		 * 		defaultLocale: "en",
+		 * 		locales: ["en", "fr", "pt-br", "es"],
+		 * 		fallback: {
+		 * 			pt: "es",
+		 * 		  fr: "en"
 		 * 		}
 		 * 	}
 		 * })
@@ -1454,7 +1440,6 @@ export interface AstroUserConfig {
 
 		/**
 		 * @docs
-		 * @kind h4
 		 * @name i18n.routing
 		 * @type {Routing}
 		 * @version 3.7.0
@@ -1466,6 +1451,7 @@ export interface AstroUserConfig {
 			/**
 			 * @docs
 			 * @name i18n.routing.prefixDefaultLocale
+			 * @kind h4
 			 * @type {boolean}
 			 * @default `false`
 			 * @version 3.7.0
@@ -1494,6 +1480,14 @@ export interface AstroUserConfig {
 		};
 	};
 
+	/**
+	 * @docs
+	 * @kind heading
+	 * @name Experimental Flags
+	 * @description
+	 * Astro offers experimental flags to give users early access to new features.
+	 * These flags are not guaranteed to be stable.
+	 */
 	experimental?: {
 		/**
 		 * @docs
@@ -2192,7 +2186,7 @@ export interface APIContext<
 	locals: App.Locals;
 
 	/**
-	 * Available only when `experimental.i18n` enabled and in SSR.
+	 * Available only when `i18n` configured and in SSR.
 	 *
 	 * It represents the preferred locale of the user. It's computed by checking the supported locales in `i18n.locales`
 	 * and locales supported by the users's browser via the header `Accept-Language`
@@ -2205,7 +2199,7 @@ export interface APIContext<
 	preferredLocale: string | undefined;
 
 	/**
-	 * Available only when `experimental.i18n` enabled and in SSR.
+	 * Available only when `i18n` configured and in SSR.
 	 *
 	 * It represents the list of the preferred locales that are supported by the application. The list is sorted via [quality value].
 	 *