4.9.0 minor release docs (#8369)

Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: sarah11918 <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Emanuele Stoppa <[email protected]>
withastro · May 23, 2024 · 226c525 · 226c525
1 parent 9c5598d
commit 226c525
Show file tree

Hide file tree

Showing 5 changed files with 548 additions and 253 deletions.
diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx
@@ -178,7 +178,6 @@ Setting `prefixDefaultLocale: true` will also automatically set `redirectToDefau
 
 You can opt out of this behavior by [setting `redirectToDefaultLocale: false`](/en/reference/configuration-reference/#i18nroutingredirecttodefaultlocale). This allows you to have a site home page that exists outside of your configured locale folder structure.
 
-
 ### `manual`
 
 <p><Since v="4.6.0" /></p>
@@ -246,48 +245,48 @@ export const onRequest = sequence(
 )
 ```
 
-## Custom locale paths
+## `domains`
 
-In addition to defining your site's supported `locales` as strings (e.g. "en", "pt-br"), Astro also allows you to map an arbitrary number of [browser-recognized language `codes`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax) to a custom URL `path`. While locales can be strings of any format as long as they correspond to your project folder structure, `codes` must follow the browser's accepted syntax.
+<p><Since v="4.9.0" /></p>
 
-Pass an object to the `locales` array with a `path` key to define a custom URL prefix, and `codes` to indicate the languages mapped to this URL. In this case, your `/[locale]/` folder name must match exactly the value of the `path` and your URLs will be generated using the `path` value.
+This routing option allows you to customize your domains on a per-language basis for `server` rendered projects using the [`@astrojs/node`](/en/guides/integrations-guide/node/) or [`@astrojs/vercel`](/en/guides/integrations-guide/vercel/) adapter with a `site` configured.
 
-This is useful if you support multiple variations of a language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these variations mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`):
+Add `i18n.domains` to map any of your supported `locales` to custom URLs:
 
-```js title="astro.config.mjs" del={5} ins={6-9}
+```js title="astro.config.mjs" {3-7} ins={14-21}
 import { defineConfig } from "astro/config"
 export default defineConfig({
+  site: "https://example.com",
+  output: "server", // required, with no prerendered pages
+  adapter: node({
+    mode: 'standalone',
+  }),
   i18n: {
     defaultLocale: "en",
-    locales: ["es", "en", "fr"],
-    locales: ["es", "en", {
-        path: "french", // no slashes included
-        codes: ["fr", "fr-BR", "fr-CA"]
-    }],
+    locales: ["es", "en", "fr", "ja"],
     routing: {
-        prefixDefaultLocale: true
+      prefixDefaultLocale: false
+    },
+    domains: {
+        fr: "https://fr.example.com",
+        es: "https://example.es"
     }
   }
 })
 ```
 
-When using functions from the [`astro:i18n` virtual module](/en/reference/api-reference/#internationalization-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](/en/reference/api-reference/#getlocalebypath).
-
-## Browser language detection
-
-Astro’s i18n routing allows you to access two properties for browser language detection in pages rendered on demand: `Astro.preferredLocale` and `Astro.preferredLocaleList`. All pages, including static prerendered pages, have access to `Astro.currentLocale`.
-
-These combine the browser's `Accept-Language` header, and your `locales` (strings or `codes`) to automatically respect your visitor's preferred languages.
+All non-mapped `locales` will follow your `prefixDefaultLocales` configuration. However, even if this value is `false`, page files for your `defaultLocale` must also exist within a localized folder. For the configuration above, an `/en/` folder is required.
 
-- [`Astro.preferredLocale`](/en/reference/api-reference/#astropreferredlocale):  Astro can compute a **preferred locale** for your visitor if their browser's preferred locale is included in your `locales` array. This value is undefined if no such match exists.
+With the above configuration:
 
-- [`Astro.preferredLocaleList`](/en/reference/api-reference/#astropreferredlocalelist): An array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. The value is `[]` if none of the browser's requested languages are found in your `locales` array. If the browser does not specify any preferred languages, then this value will be [`i18n.locales`].
-
-- [`Astro.currentLocale`](/en/reference/api-reference/#astrocurrentlocale): The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to [`i18n.defaultLocale`](/en/reference/configuration-reference/#i18ndefaultlocale).
+- The file `/fr/about.astro` will create the URL `https://fr.example.com/about`.
+- The file `/es/about.astro` will create the URL `https://example.es/about`.
+- The file `/ja/about.astro` will create the URL `https://example.com/ja/about`.
+- The file `/en/about.astro` will create the URL `https://example.com/about`.
 
-In order to successfully match your visitors' preferences, provide your `codes` using the same pattern [used by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax).
+The above URLs will also be returned by the `getAbsoluteLocaleUrl()` and `getAbsoluteLocaleUrlList()` functions.
 
-## Fallback
+## `fallback`
 
 Astro's i18n routing allows you to configure a **fallback routing strategy**. When a page in one language doesn't exist (e.g. a page that is not yet translated), instead of displaying a 404 page, you can redirect a user from one locale to another on a per-language basis. This is useful when you do not yet have a page for every route, but you want to still provide some content to your visitors.
 
@@ -308,49 +307,32 @@ export default defineConfig({
 
 Astro will ensure that a page is built in `src/pages/fr` for every page that exists in `src/pages/es/`. If the page does not already exist, then a page with a redirect to the corresponding `es` route will be created.
 
-## `domains` (experimental)
+## Custom locale paths
 
-<p><Since v="4.3.0" /></p>
+In addition to defining your site's supported `locales` as strings (e.g. "en", "pt-br"), Astro also allows you to map an arbitrary number of [browser-recognized language `codes`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax) to a custom URL `path`. While locales can be strings of any format as long as they correspond to your project folder structure, `codes` must follow the browser's accepted syntax.
 
-This routing option allows you to customize your domains on a per-language basis for `server` rendered projects using the [`@astrojs/node`](/en/guides/integrations-guide/node/) or [`@astrojs/vercel`](/en/guides/integrations-guide/vercel/) adapter with a `site` configured.
+Pass an object to the `locales` array with a `path` key to define a custom URL prefix, and `codes` to indicate the languages mapped to this URL. In this case, your `/[locale]/` folder name must match exactly the value of the `path` and your URLs will be generated using the `path` value.
 
-To enable this in your project, [configure i18n routing](#configure-i18n-routing) with your preferences if you have not already done so. Then, set the `experimental.i18nDomains` flag to `true` and add `i18n.domains` to map any of your supported `locales` to custom URLs:
+This is useful if you support multiple variations of a language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these variations mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`):
 
-```js title="astro.config.mjs" {3-7} ins={14-21}
+```js title="astro.config.mjs" del={5} ins={6-9}
 import { defineConfig } from "astro/config"
 export default defineConfig({
-  site: "https://example.com",
-  output: "server", // required, with no prerendered pages
-  adapter: node({
-    mode: 'standalone',
-  }),
   i18n: {
     defaultLocale: "en",
-    locales: ["es", "en", "fr", "ja"],
+    locales: ["es", "en", "fr"],
+    locales: ["es", "en", {
+        path: "french", // no slashes included
+        codes: ["fr", "fr-BR", "fr-CA"]
+    }],
     routing: {
-      prefixDefaultLocale: false
-    },
-    domains: {
-        fr: "https://fr.example.com",
-        es: "https://example.es"
+        prefixDefaultLocale: true
     }
-  },
-  experimental: {
-    i18nDomains: true
   }
 })
 ```
 
-All non-mapped `locales` will follow your `prefixDefaultLocales` configuration. However, even if this value is `false`, page files for your `defaultLocale` must also exist within a localized folder. For the configuration above, an `/en/` folder is required.
-
-With the above configuration: 
-
-- The file `/fr/about.astro` will create the URL `https://fr.example.com/about`.
-- The file `/es/about.astro` will create the URL `https://example.es/about`.
-- The file `/ja/about.astro` will create the URL `https://example.com/ja/about`.
-- The file `/en/about.astro` will create the URL `https://example.com/about`.
-
-The above URLs will also be returned by the `getAbsoluteLocaleUrl()` and `getAbsoluteLocaleUrlList()` functions.
+When using functions from the [`astro:i18n` virtual module](/en/reference/api-reference/#internationalization-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](/en/reference/api-reference/#getlocalebypath).
 
 #### Limitations
 
@@ -366,5 +348,19 @@ Astro relies on the following headers in order to support the feature:
 
 Make sure that your server proxy/hosting platform is able to provide this information. Failing to retrieve these headers will result in a 404 (status code) page.
 
+## Browser language detection
+
+Astro’s i18n routing allows you to access two properties for browser language detection in pages rendered on demand: `Astro.preferredLocale` and `Astro.preferredLocaleList`. All pages, including static prerendered pages, have access to `Astro.currentLocale`.
+
+These combine the browser's `Accept-Language` header, and your `locales` (strings or `codes`) to automatically respect your visitor's preferred languages.
+
+- [`Astro.preferredLocale`](/en/reference/api-reference/#astropreferredlocale):  Astro can compute a **preferred locale** for your visitor if their browser's preferred locale is included in your `locales` array. This value is undefined if no such match exists.
+
+- [`Astro.preferredLocaleList`](/en/reference/api-reference/#astropreferredlocalelist): An array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. The value is `[]` if none of the browser's requested languages are found in your `locales` array. If the browser does not specify any preferred languages, then this value will be [`i18n.locales`].
+
+- [`Astro.currentLocale`](/en/reference/api-reference/#astrocurrentlocale): The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to [`i18n.defaultLocale`](/en/reference/configuration-reference/#i18ndefaultlocale).
+
+In order to successfully match your visitors' preferences, provide your `codes` using the same pattern [used by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax).
+
 [`site`]: /en/reference/configuration-reference/#site
 [`i18n.locales`]: /en/reference/configuration-reference/#i18nlocales