Ce contenu n’est pas encore disponible dans votre langue.
Astro’s internationalization (i18n) features allow you to adapt your project for an international audience.
i18n RoutingSection titled i18n Routing
Ajouté à la version :
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 new features as this API continues to develop!
Configure i18n routingSection titled Configure i18n routing
Enable the routing option by adding an
i18nobject to your Astro configuration with a default location (
defaultLocale) and a list of all languages to support (
Choose and configure a
routingbased on the desired URL path for your
"prefixDefaultLocale: false"(default): URLs in your default language will not have a
/[locale]/prefix. All other locales will.
"prefixDefaultLocale: true": All URLs, including your default language, will have a
Organize your content folders with localized content by language. Your folder names must match the items in
localesexactly, and your folder organization must match the URL paths chosen for your
Include a localized folder for your
defaultLocaleonly if you configure
prefixDefaultLocale: trueto show a localized URL path.
The localized folders do not need to be at the root of the
/[locale]/folders anywhere within
src/pages/and Astro’s file-based routing will create your pages at corresponding URL paths.
With i18n routing configured, you can now compute links to pages within your site using the
getRelativeLocaleURL()helper available from the
astro:i18nmodule. This will always provide the correct, localized route and can help you correctly use, or check, URLs on your site. You can also still write the links manually.
Section titled routing
Astro’s built-in file-based routing automatically creates URL routes for you based on your file structure within
src/pages/. When you configure i18n routing, the
routing value now allows you to specify your file structure (and corresponding URL paths generated) in order to use helper functions to generate, use, and verify the routes in your project.
Section titled prefixDefaultLocale: false
This is the default value. Set this option when URLs in your default language will not have a
/[locale]/ prefix and files in your default language exist at the root of
src/pages/blog.astrowill produce the route
src/pages/fr/blog.astrowill produce the route
- If there is no file at
src/pages/es/blog.astro, then the route
example.com/es/blog/will 404 unless you specify a fallback strategy.
Section titled prefixDefaultLocale: true
Set this option when all routes will have their
/locale/ prefix in their URL and when all page content files, including those for your
defaultLocale, exist in a localized folder:
- index.astro // Note: this file is always required
- URLs without a locale prefix, (e.g.
example.com/blog/) will return a 404 (not found) status code.
Section titled redirectToDefaultLocale
Ajouté à la version :
Configures whether or not the home URL (
/) generated by
src/pages/index.astro will redirect to
prefixDefaultLocale: true will also automatically set
redirectToDefaultLocale: true in your
routing config object. By default, the required
src/pages/index.astro file will automatically redirect to the index page of your default locale.
You can opt out of this behavior by setting
redirectToDefaultLocale: false. This allows you to have a site home page that exists outside of your configured locale folder structure.
Section titled domains (experimental)
Ajouté à la version :
To enable this in your project, 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:
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.astrowill create the URL
- The file
/es/about.astrowill create the URL
- The file
/ja/about/astrowill create the URL
- The file
/en/about.astrowill create the URL
The above URLs will also be returned by the
LimitationsSection titled Limitations
This feature has some restrictions:
siteoption is mandatory.
outputoption must be set to
- There cannot be any individual prerendered pages.
- The adapter feature
functionPerRouteis not supported.
Astro relies on the following headers in order to support the feature:
Host. Astro will use the former, and if not present, will try the latter.
URL#protocolof the server request.
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.
Routing logicSection titled Routing logic
Astro uses a middleware to implement its routing logic. This middleware function is placed in the first position where it awaits every
Response coming from any additional middleware and each page route before finally executing its own logic.
This means that operations (e.g. redirects) from your own middleware and your page logic are run first, your routes are rendered, and then the i18n middleware performs its own actions such as verifying that a localized URL corresponds to a valid route.
Section titled defaultLocale and locales
Each entry in the
locales configuration array must be either a string (e.g.
"pt-br") or a custom locale path.
locales may contain a combination of strings and custom paths.
/[locale]/ folder names must match exactly the
locales in the list (either the string or the
path value), and your 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
Custom locale pathsSection titled 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 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
This is useful if you support multiple variations of a language (e.g.
"fr-CA") and you want to have all these variations mapped under the same URL
/fr/, or even customize it entirely (e.g.
Browser language detectionSection titled Browser language detection
Astro’s i18n routing combined with one of Astro’s on-demand server rendering modes (
output:'hybrid') allow you to access two properties for browser language detection:
These combine the browser’s
Accept-Language 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
localesarray. 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
localesarray. If the browser does not specify any preferred languages, then this value will be
Astro.currentLocale: The locale computed from the current URL, using the syntax specified in your
localesconfiguration. If the URL does not contain a
/[locale]/prefix, then the value will default to
In order to successfully match your visitors’ preferences, provide your
codes using the same pattern used by the browser.
FallbackSection titled 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.
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.
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.
Virtual module Section titled Virtual module astro:i18n
This module provides functions that can 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:
Also, note that the returned URLs created by these functions for your
defaultLocale will reflect your
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.
Section titled 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.
Section titled getAbsoluteLocaleUrl()
getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string
Section titled getRelativeLocaleUrlList()
Use this like
getRelativeLocaleUrl to return a list of relative paths for all the locales.
getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string
Section titled getAbsoluteLocaleUrlList()
getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string
Use this like
getAbsoluteLocaleUrl to return a list of absolute paths for all the locales.
Section titled getPathByLocale(locale: string): string
getPathByLocale(locale: string): string
A function that returns the
path associated to one or more
codes when custom locale paths are configured.
Generating URLs from custom pathsSection titled Generating URLs from custom paths
locale is a custom path, use the
path as the value for
For example, use
french in the i18n helper functions for the
locales configuration below:
Note that other
astro:i18n functions will return the following results for the same configuration:
Section titled getLocaleByPath(path: string): string
getLocaleByPath(path: string): string
A function that returns the
code associated to a locale
Retrieve the locale for a custom pathSection titled Retrieve the locale for a custom path
Given a custom path configured with multiple
codes, the function will return the first code configured: