From 12a56959b9344f8001d6c955d05f683879544ff0 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 29 Nov 2023 11:06:01 -0500 Subject: [PATCH 01/14] feat(i18n): add documentation for refined locales --- .../docs/en/guides/internationalization.mdx | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index b7b65172546a8..7dc8ee630b037 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -282,8 +282,55 @@ Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list o `getAbsoluteLocaleUrlList(locale: string, options?: GetLocaleOptions): string[]` - Use this like [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl) to return a list of absolute paths for all the locales. +### `getPathByLocale(locale: string): string` + +A function that return the `path` associated to a locale (defined as code). It's particularly useful in case you use [refined locales](#refined-locales). + + +### Refined locales + +Astro allows to map an arbitrary number of locales to a particular URL path. The `locales` array can accept an object, where the `path` key is what you'll see in the URL, and `codes` represents the languages mapped to this URL. + +This is useful if you support multiple variations of language, e.g. `"fr"`, `"fr-BR"` and `"fr-CA"` and you want to have all these locales mapped under the same URL, `/french`: + +```js title="astro.config.mjs" del={6} ins={7-10} +import { defineConfig } from "astro/config" +export default defineConfig({ + experimental: { + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + locales: ["es", "en", { + path: "french", // not slash needed + codes: ["fr", "fr-BR", "fr-CA"] + }], + routingStrategy: "prefix-always" + } + } +}) +``` + +If you rely on the [`astro:i18n` virtual module](#virtual-module-astroi18n), you'll have to use the `path` to compose the correct URL, for example: + +```astro title="src/pages/index.astro" +--- +import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from "astro:i18n"; + +getRelativeLocaleUrl("french", "blog"); // returns /french/blog + +// These functions are not particularly useful +getPathByLocale("fr"); // returns "french" +getPathByLocale("fr-CA"); // returns "french" +getPathByLocale("es"); // returns "es" +getLocaleByPath("french"); // returns "fr" because that's the first code configured +getLocaleByPath("es"); // returns "es" +--- +``` + +If you rely on [the browser language detection](#browser-language-detection), Astro will use the `codes` to determine the `Astro.preferredLocale` and `Astro.preferredLocaleList`. If so, it's advised to write the 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/#experimentali18nlocales From d6ea10bccdf326d4812d35975a23c7a4043cd248 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Thu, 30 Nov 2023 16:09:52 -0500 Subject: [PATCH 02/14] Apply suggestions from code review Co-authored-by: Sarah Rainsberger --- .../docs/en/guides/internationalization.mdx | 29 ++++++++++++------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 7dc8ee630b037..4bd8de83eb9f3 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -286,14 +286,16 @@ Use this like [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl) to return a list o ### `getPathByLocale(locale: string): string` -A function that return the `path` associated to a locale (defined as code). It's particularly useful in case you use [refined locales](#refined-locales). +A function that returns the `path` associated to one or more `codes` when [refined locales](#refined-locales) are configured. -### Refined locales +### Custom locale paths -Astro allows to map an arbitrary number of locales to a particular URL path. The `locales` array can accept an object, where the `path` key is what you'll see in the URL, and `codes` represents the languages mapped to this URL. +In addition to defining your site's supported `locales` as strings (e.g. "en", "pt-br") for a 1-to-1 correspondence between your folder structure and your URLs, Astro also allows you to map an arbitrary number of locales to a custom URL path. -This is useful if you support multiple variations of language, e.g. `"fr"`, `"fr-BR"` and `"fr-CA"` and you want to have all these locales mapped under the same URL, `/french`: +The `locales` array can also accept an object with a `path` key to define a custom URL prefix, and `codes` to indicate the languages mapped to this URL. + +This is useful if you support multiple variations of language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these locales mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`): ```js title="astro.config.mjs" del={6} ins={7-10} import { defineConfig } from "astro/config" @@ -303,7 +305,7 @@ export default defineConfig({ defaultLocale: "en", locales: ["es", "en", "fr"], locales: ["es", "en", { - path: "french", // not slash needed + path: "french", // no slashes included codes: ["fr", "fr-BR", "fr-CA"] }], routingStrategy: "prefix-always" @@ -312,24 +314,29 @@ export default defineConfig({ }) ``` -If you rely on the [`astro:i18n` virtual module](#virtual-module-astroi18n), you'll have to use the `path` to compose the correct URL, for example: +When using functions from the [`astro:i18n` virtual module](#virtual-module-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), use the `path` as value for `locale`. -```astro title="src/pages/index.astro" +For example, given the above configuration: + +```astro title="src/pages/index.ast'd ro" --- import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from "astro:i18n"; getRelativeLocaleUrl("french", "blog"); // returns /french/blog +--- +``` -// These functions are not particularly useful +Note that other `astro:i18n` functions will return the following results for the same configuration: + +```astro title="src/pages/index.astro" +--- getPathByLocale("fr"); // returns "french" getPathByLocale("fr-CA"); // returns "french" -getPathByLocale("es"); // returns "es" getLocaleByPath("french"); // returns "fr" because that's the first code configured -getLocaleByPath("es"); // returns "es" --- ``` -If you rely on [the browser language detection](#browser-language-detection), Astro will use the `codes` to determine the `Astro.preferredLocale` and `Astro.preferredLocaleList`. If so, it's advised to write the codes using the same pattern [used by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax). +Astro will use your configured `codes` and [the browser's language detection](#browser-language-detection) to determine `Astro.preferredLocale` and `Astro.preferredLocaleList`. 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 From 97919a84fc49839ac5bc20a0e4406a0f35c55c71 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Thu, 30 Nov 2023 16:45:22 -0500 Subject: [PATCH 03/14] update config name --- src/content/docs/en/guides/internationalization.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index c05834dbd886d..e28bf286ef6dc 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -315,7 +315,9 @@ export default defineConfig({ path: "french", // no slashes included codes: ["fr", "fr-BR", "fr-CA"] }], - routingStrategy: "prefix-always" + routing: { + prefixDefaultLocale: true + } } } }) From 79c97a140aaf11147ee4db41384375b00afb98f6 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Thu, 30 Nov 2023 16:53:56 -0500 Subject: [PATCH 04/14] fix link --- src/content/docs/en/guides/internationalization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index e28bf286ef6dc..793e971c1940d 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -293,7 +293,7 @@ Use this like [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl) to return a list o ### `getPathByLocale(locale: string): string` -A function that returns the `path` associated to one or more `codes` when [refined locales](#refined-locales) are configured. +A function that returns the `path` associated to one or more `codes` when [custom locale paths](#custom-locale-paths) are configured. ### Custom locale paths From b47e17f17f26c1ef897b2e0f88de09a301bb813e Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Fri, 1 Dec 2023 11:24:37 -0500 Subject: [PATCH 05/14] chore: remove experimental --- .../docs/en/guides/internationalization.mdx | 80 ++++++++----------- 1 file changed, 34 insertions(+), 46 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 793e971c1940d..7af272d9cc416 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -10,7 +10,7 @@ import Since from '~/components/Since.astro' Astro's internationalization (i18n) features allow you to adapt your project for an international audience. -## i18n Routing (Experimental) +## i18n Routing @@ -26,11 +26,9 @@ This routing API helps you generate, use, and verify the URLs that your multi-la ```js title="astro.config.mjs" import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["en", "es", "pt-br"] - } + i18n: { + defaultLocale: "en", + locales: ["en", "es", "pt-br"] } }) ``` @@ -44,13 +42,11 @@ This routing API helps you generate, use, and verify the URLs that your multi-la ```js title="astro.config.mjs" ins={8} import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - routing: { - prefixDefaultLocale: false - } + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + routing: { + prefixDefaultLocale: false } } }) @@ -104,13 +100,11 @@ Astro's built-in file-based routing automatically creates URL routes for you bas ```js title="astro.config.mjs" ins={8} import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - routing: { - prefixDefaultLocale: false - } + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + routing: { + prefixDefaultLocale: false } } }) @@ -128,13 +122,11 @@ This is the **default** value. Set this option when URLs in your default languag ```js title="astro.config.mjs" ins={8} import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - routing: { - prefixDefaultLocale: true - } + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + routing: { + prefixDefaultLocale: true } } }) @@ -189,13 +181,11 @@ For example, the configuration below sets `es` as the fallback locale for any mi ```js title="astro.config.mjs" ins={6,7-9} import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - fallback: { - fr: "es" - } + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + fallback: { + fr: "es" } } }) @@ -304,20 +294,18 @@ The `locales` array can also accept an object with a `path` key to define a cust This is useful if you support multiple variations of language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these locales mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`): -```js title="astro.config.mjs" del={6} ins={7-10} +```js title="astro.config.mjs" del={5} ins={6-9} import { defineConfig } from "astro/config" export default defineConfig({ - experimental: { - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - locales: ["es", "en", { - path: "french", // no slashes included - codes: ["fr", "fr-BR", "fr-CA"] - }], - routing: { - prefixDefaultLocale: true - } + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + locales: ["es", "en", { + path: "french", // no slashes included + codes: ["fr", "fr-BR", "fr-CA"] + }], + routing: { + prefixDefaultLocale: true } } }) From ba197ca93dcc915ff6f7aaac7cced55c9a2dddaf Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 15:33:58 -0400 Subject: [PATCH 06/14] fix typo --- src/content/docs/en/guides/internationalization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 7af272d9cc416..09c310365c4a5 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -315,7 +315,7 @@ When using functions from the [`astro:i18n` virtual module](#virtual-module-astr For example, given the above configuration: -```astro title="src/pages/index.ast'd ro" +```astro title="src/pages/index.astro" --- import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from "astro:i18n"; From 2e5cac362f6dca5f0e17eccd4b65234bf9e7a475 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 16:19:27 -0400 Subject: [PATCH 07/14] moved the content into appropriate sections --- .../docs/en/guides/internationalization.mdx | 76 +++++++++---------- 1 file changed, 36 insertions(+), 40 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 09c310365c4a5..32b7c0873dc6d 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -155,22 +155,50 @@ Set this option when all routes will have their `/locale/` prefix in their URL a Both a default language ([`defaultLocale`](/en/reference/configuration-reference/#experimentali18ndefaultlocale)) and a list of all supported languages ([`locales`](/en/reference/configuration-reference/#experimentali18nlocales)) must be specified in your `i18n` routing configuration. -Each language must be a string (e.g. `"fr"`, `"pt-br"`), but no particular language format or syntax is enforced while this feature is still experimental and under development. This may be subject to change in future versions. +Each entry in the `locales` configuration array must be either a string (e.g. `"fr"`, `"pt-br"`) or a [custom locale path](#custom-locale-paths). `locales` may contain a combination of strings and custom paths. -Your `/[locale]/` folder names must match exactly the `locales` in the list, and your [routing](#routing) must correspond to whether or not you have a localized folder for your default language. Every other supported language must have its own localized folder. +Your `/[locale]/` folder names must match exactly the `locale`s in the list (either the string or the `path` value), and your [routing](#routing) configuration must correspond to whether or not you have a localized folder for your default language. Every other supported language must have its own localized folder. -Depending on your deploy host, you may discover transformations in URL paths, so check your deployed site to determine the best syntax for your project. +Depending on your deploy host, you may discover transformations in URL paths, so check your deployed site to determine the best syntax for your `locale` values. + +### Custom locale paths + +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. + +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 is useful if you support multiple variations of language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these locales mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`): + +```js title="astro.config.mjs" del={5} ins={6-9} +import { defineConfig } from "astro/config" +export default defineConfig({ + i18n: { + defaultLocale: "en", + locales: ["es", "en", "fr"], + locales: ["es", "en", { + path: "french", // no slashes included + codes: ["fr", "fr-BR", "fr-CA"] + }], + routing: { + prefixDefaultLocale: true + } + } +}) +``` + +When using functions from the [`astro:i18n` virtual module](#virtual-module-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](#generating-urls-from-custom-paths). ### Browser language detection Astro's i18n routing combined with one of Astro's [on-demand server rendering modes (`output:'server'` or `output:'hybrid'`)](/en/guides/server-side-rendering/) allow you to access two properties for browser language detection: `Astro.preferredLocale` and `Astro.preferredLocaleList`. -These combine the browser's `Accept-Langauge` header, and your `locales` to automatically respect your visitor's preferred languages. +These combine the browser's `Accept-Langauge` header, and your `locales` (strings or `codes`) to automatically respect your visitor's preferred languages. - `Astro.preferredLocale`: 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`: 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`: 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`. - + +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). ### Fallback @@ -204,14 +232,12 @@ Creating routes for your project with the i18n router will depend on certain con - [`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. URLs created when `prefixDefaultLocale: true` is configured will include a `/lang/` path in the URL. URLs created with `prefixDefaultLocale: false` will not include a language prefix. ### `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. @@ -285,35 +311,9 @@ Use this like [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl) to return a list o A function that returns the `path` associated to one or more `codes` when [custom locale paths](#custom-locale-paths) are configured. +### Generatng URLs from custom paths -### Custom locale paths - -In addition to defining your site's supported `locales` as strings (e.g. "en", "pt-br") for a 1-to-1 correspondence between your folder structure and your URLs, Astro also allows you to map an arbitrary number of locales to a custom URL path. - -The `locales` array can also accept an object with a `path` key to define a custom URL prefix, and `codes` to indicate the languages mapped to this URL. - -This is useful if you support multiple variations of language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these locales mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`): - -```js title="astro.config.mjs" del={5} ins={6-9} -import { defineConfig } from "astro/config" -export default defineConfig({ - i18n: { - defaultLocale: "en", - locales: ["es", "en", "fr"], - locales: ["es", "en", { - path: "french", // no slashes included - codes: ["fr", "fr-BR", "fr-CA"] - }], - routing: { - prefixDefaultLocale: true - } - } -}) -``` - -When using functions from the [`astro:i18n` virtual module](#virtual-module-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), use the `path` as value for `locale`. - -For example, given the above configuration: +When a `locale` is a custom path, use the `path` as the value for `locale`. ```astro title="src/pages/index.astro" --- @@ -322,7 +322,6 @@ import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from "astro:i1 getRelativeLocaleUrl("french", "blog"); // returns /french/blog --- ``` - Note that other `astro:i18n` functions will return the following results for the same configuration: ```astro title="src/pages/index.astro" @@ -331,10 +330,7 @@ getPathByLocale("fr"); // returns "french" getPathByLocale("fr-CA"); // returns "french" getLocaleByPath("french"); // returns "fr" because that's the first code configured --- -``` - -Astro will use your configured `codes` and [the browser's language detection](#browser-language-detection) to determine `Astro.preferredLocale` and `Astro.preferredLocaleList`. 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/#experimentali18nlocales From dc9f8316c724cbc10163071ad4d69866195830e8 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 18:59:30 -0400 Subject: [PATCH 08/14] fix typo --- src/content/docs/en/guides/internationalization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index f771395ececee..d915325730e45 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -311,7 +311,7 @@ Use this like [`getAbsoluteLocaleUrl`](#getabsolutelocaleurl) to return a list o A function that returns the `path` associated to one or more `codes` when [custom locale paths](#custom-locale-paths) are configured. -### Generatng URLs from custom paths +### Generating URLs from custom paths When a `locale` is a custom path, use the `path` as the value for `locale`. From 049ed238599f24eb5d1afa1777394e5fc17fc02e Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 4 Dec 2023 11:42:43 +0000 Subject: [PATCH 09/14] fix code snippets --- src/content/docs/en/guides/internationalization.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index d915325730e45..4669438a6dc14 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -39,7 +39,7 @@ This routing API helps you generate, use, and verify the URLs that your multi-la - `"prefixDefaultLocale: true"`: All URLs, including your default language, will have a `/[locale]/` prefix. - ```js title="astro.config.mjs" ins={8} + ```js title="astro.config.mjs" ins={7} import { defineConfig } from "astro/config" export default defineConfig({ i18n: { @@ -97,7 +97,7 @@ Astro's built-in file-based routing automatically creates URL routes for you bas #### `prefixDefaultLocale: false` -```js title="astro.config.mjs" ins={8} +```js title="astro.config.mjs" ins={7} import { defineConfig } from "astro/config" export default defineConfig({ i18n: { @@ -119,7 +119,7 @@ This is the **default** value. Set this option when URLs in your default languag #### `prefixDefaultLocale: true` -```js title="astro.config.mjs" ins={8} +```js title="astro.config.mjs" ins={7} import { defineConfig } from "astro/config" export default defineConfig({ i18n: { @@ -206,7 +206,7 @@ Astro's i18n routing allows you to configure a **fallback routing strategy**. Wh For example, the configuration below sets `es` as the fallback locale for any missing `fr` routes. This means that a user visiting `example.com/fr/my-page/` will be redirected to and shown the content for `example.com/es/my-page/` instead of being taken to a 404 page when `src/pages/fr/my-page.astro` does not exist. -```js title="astro.config.mjs" ins={6,7-9} +```js title="astro.config.mjs" ins={6-8} import { defineConfig } from "astro/config" export default defineConfig({ i18n: { From ff758e0be1b7c9b9a908b2797275b16c9e8b6b54 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 4 Dec 2023 10:29:15 -0400 Subject: [PATCH 10/14] added config example for custom path examples --- src/content/docs/en/guides/internationalization.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 4669438a6dc14..4484ef9f44a5a 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -167,7 +167,7 @@ In addition to defining your site's supported `locales` as strings (e.g. "en", " 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 is useful if you support multiple variations of language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these locales mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`): +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" del={5} ins={6-9} import { defineConfig } from "astro/config" @@ -315,6 +315,15 @@ A function that returns the `path` associated to one or more `codes` when [custo When a `locale` is a custom path, use the `path` as the value for `locale`. +For example, use `french` in the i18n helper functions for the `locales` configuration below: + +```js +locales: ["es", "en", { + path: "french", + codes: ["fr", "fr-BR", "fr-CA"] +}], +``` + ```astro title="src/pages/index.astro" --- import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from "astro:i18n"; From 875e2ae14964aa15a1c4ad2fdf1541db0727cc11 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 4 Dec 2023 15:11:06 +0000 Subject: [PATCH 11/14] not experimental! not changing! --- src/content/docs/en/guides/internationalization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 4484ef9f44a5a..fae4761a237f8 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -14,9 +14,9 @@ Astro's internationalization (i18n) features allow you to adapt your project for -Astro's experimental i18n routing allows you to add your multilingual content with support for configuring a default language, computing relative page URLs, and accepting preferred languages provided by your visitor's browser. You can also specify fallback languages on a per-language basis so that your visitors can always be directed to existing content on your site. +Astro's i18n routing allows you to add your multilingual content with support for configuring a default language, computing relative page URLs, and accepting preferred languages provided by your visitor's browser. You can also specify fallback languages on a per-language basis so that your visitors can always be directed to existing content on your site. -This routing API helps you generate, use, and verify the URLs that your multi-language site produces. Check back and update regularly for the latest changes as this API continues to develop! +This routing API helps you generate, use, and verify the URLs that your multi-language site produces. Check back and update regularly for the latest new features as this API continues to develop! ### Configure i18n routing From 3769396eefec26ddd8d12a57b5c4da6133bbacb9 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 4 Dec 2023 15:14:14 +0000 Subject: [PATCH 12/14] prepare links for no longer pointing to experimental config - link checker will be angry! --- src/content/docs/en/guides/internationalization.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index fae4761a237f8..cbdad675da2c3 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -21,7 +21,7 @@ This routing API helps you generate, use, and verify the URLs that your multi-la ### Configure i18n routing -1. Enable the experimental routing option by adding an `i18n` object to your Astro configuration with a [default location (`defaultLocale`) and a list of all languages to support (`locales`)](#defaultlocale-and-locales): +1. Enable the routing option by adding an `i18n` object to your Astro configuration with a [default location (`defaultLocale`) and a list of all languages to support (`locales`)](#defaultlocale-and-locales): ```js title="astro.config.mjs" import { defineConfig } from "astro/config" @@ -153,7 +153,7 @@ Set this option when all routes will have their `/locale/` prefix in their URL a ### `defaultLocale` and `locales` -Both a default language ([`defaultLocale`](/en/reference/configuration-reference/#experimentali18ndefaultlocale)) and a list of all supported languages ([`locales`](/en/reference/configuration-reference/#experimentali18nlocales)) must be specified in your `i18n` routing configuration. +Both a default language ([`defaultLocale`](/en/reference/configuration-reference/#i18ndefaultlocale)) and a list of all supported languages ([`locales`](/en/reference/configuration-reference/#i18nlocales)) must be specified in your `i18n` routing configuration. Each entry in the `locales` configuration array must be either a string (e.g. `"fr"`, `"pt-br"`) or a [custom locale path](#custom-locale-paths). `locales` may contain a combination of strings and custom paths. @@ -342,4 +342,4 @@ getLocaleByPath("french"); // returns "fr" because that's the first code configu ``` [`site`]: /en/reference/configuration-reference/#site -[`i18n.locales`]: /en/reference/configuration-reference/#experimentali18nlocales +[`i18n.locales`]: /en/reference/configuration-reference/#i18nlocales From 35a125e6676a1fda690147b7938aed3eaa478426 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 4 Dec 2023 15:23:47 +0000 Subject: [PATCH 13/14] chore: document `getLocaleByPath` --- .../docs/en/guides/internationalization.mdx | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index cbdad675da2c3..4bc065247291b 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -339,7 +339,39 @@ getPathByLocale("fr"); // returns "french" getPathByLocale("fr-CA"); // returns "french" getLocaleByPath("french"); // returns "fr" because that's the first code configured --- -``` +``` + +### `getLocaleByPath(path: string): string` + +A function that returns the `code` associated to a locale `path`. + +### Retrieve the locale for a custom path + +Given a custom path configured with multiple `codes`, the function will return the **first** code configured: + +```js +// astro.config.mjs +import {defineConfig} from "astro/config" +export default defineConfig({ + i18n: { + defaultLocale: 'en', + locales: ['en', 'es', 'fr', { + path: "portugues", + codes: ["pt-AO", "pt", "pt-BR"] + }] + } +}) +``` + +```astro +--- +// src/pages/index.astro +import { getLocaleByPath } from "astro:18n"; +console.log(getLocaleByPath('en')) // will log "en" +console.log(getLocaleByPath('fr')) // will log "fr" +console.log(getLocaleByPath('portugues')) // will log "pt-AO" +--- +``` [`site`]: /en/reference/configuration-reference/#site [`i18n.locales`]: /en/reference/configuration-reference/#i18nlocales From 3a961446b948cbb87e3e93e59b909a19323517b1 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Tue, 5 Dec 2023 09:42:47 +0000 Subject: [PATCH 14/14] chore: document redirect of index --- src/content/docs/en/guides/internationalization.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/guides/internationalization.mdx b/src/content/docs/en/guides/internationalization.mdx index 4bc065247291b..6ea6e300cb630 100644 --- a/src/content/docs/en/guides/internationalization.mdx +++ b/src/content/docs/en/guides/internationalization.mdx @@ -150,6 +150,7 @@ Set this option when all routes will have their `/locale/` prefix in their URL a - URLs without a locale prefix, (e.g. `example.com/blog/`) will return a 404 (not found) status code. +- The home URL (`/`) redirects to `/`. ### `defaultLocale` and `locales`