Repository files navigation

Built with ❤️ for all Astro crewmates 🧑‍🚀

Provide an internationalization (i18n) integration for Astro that:

• Supports thedefaultLocale
• Avoids template file duplication
• Is adapter agnostic
• Is UI framework agnostic
• Is compatible with@astrojs/sitemap

Install vianpm:

npm install astro-i18n-aut

In your Astroconfig file:

import{defineConfig}from"astro/config";import{i18n,filterSitemapByDefaultLocale}from"astro-i18n-aut/integration";importsitemapfrom"@astrojs/sitemap";constdefaultLocale="en";constlocales={en:"en-US",// the `defaultLocale` value must present in `locales` keyses:"es-ES",fr:"fr-CA",};exportdefaultdefineConfig({site:"https://example.com/",trailingSlash:"always",build:{format:"directory",},integrations:[i18n({      locales,      defaultLocale,}),sitemap({i18n:{        locales,        defaultLocale,},filter:filterSitemapByDefaultLocale({ defaultLocale}),}),],});

In your.gitignore file:

astro_tmp_pages_*

Now that you have set up the config, each.astro page will have additional renders with your other languages. For example,src/pages/about.astro will render as:

• /about/
• /es/about/
• /fr/about/

If you have enabledredirectDefaultLocale (true by default), redirects will be:

• /en/about/ =>/about/

Please note that thegetStaticPaths() function will only run once. This limitation means that you cannot have translated urls, such as/es/acerca-de/ for/about/. However, it also ensures compatibility with@astrojs/sitemap.

The Astro frontmatter and page content is re-run for every translated page. For example, theAstro.url.pathname will be:

• /about/
• /es/about/
• /fr/about/

It is up to you to detect which language is being rendered. You can use Astrocontent collections or any i18n UI framework, such asreact-i18next, for your translations. Here is a pureHello World example:

---import {getLocale }from"astro-i18n-aut";importLayoutfrom"../layouts/Layout.astro";const locale=getLocale(Astro.url);let title:string;switch (locale) {case"es":title="¡Hola Mundo!";break;case"fr":title="Bonjour Monde!";break;default:title="Hello World!";}---<Layouttitle={title}>  <h1>{title}</h1></Layout>

Several helper functions are included to make handling locales easier.

Please see the official Astro docs for more details:

• site
• trailingSlash
• format

You must set either:

• {site:"https://example.com/",trailingSlash:"always",build:{format:"directory",},}

• {site:"https://example.com",trailingSlash:"never",build:{format:"file",},}

All these options are related and must be set together. They affect whether your urls are:

• /about/
• /about

If you choose/about/, then/about will 404 and vice versa.

• locales: A record of all language locales.
• defaultLocale: The default language locale. The value must present inlocales keys.
• redirectDefaultLocale - Assuming thedefaultLocale: "en", whether/en/about/ redirects to/about/ (default:308).
• include: Glob pattern(s) to include (default:["pages/**/*"]).
• exclude: Glob pattern(s) to exclude (default:["pages/api/**/*"]).

Other Astro page file types:

• ✅.astro
• ❌.md
• ❌.mdx (with the MDX Integration installed)
• ❌.html
• ❌.js / .ts (as endpoints)

cannot be translated. If you choose to use them in thepages directory, please add them to the ignore glob patterns. For example:

["pages/api/**/*","pages/**/*.md"];

In Astro, thedocs state:

You can exclude pages or directories from being built by prefixing their names with an underscore (_). Files with the _ prefix won’t be recognized by the router and won’t be placed into the dist/ directory.

You can use this to temporarily disable pages, and also to put tests, utilities, and components in the same folder as their related pages.

Unfortunately, thisexcluding pages feature is not supported. Please only keep pages in your pages directory.

You can still exclude pages prefixed with an underscore (_) by addingpages/**/_* to the ignore glob patterns:

["pages/api/**/*","pages/**/_*"];

For.md and.mdx, use AstroContentCollections.

With this library and Astro Content Collections, you can keep your Markdown separate and organized incontent, while usingpages/blog/index.astro andpages/blog/[slug].astro to render all of your content, even with adefaultLocale! Here is an example folder structure:

.└── astro-project/    └── src/        ├── pages/        │   └── blog/        │       ├── index.astro        │       └── [id].astro        └── content/            └── blog/                ├── en/                │   ├── post-1.md                │   └── post-2.md                ├── es/                │   ├── post-1.md                │   └── post-2.md                └── fr/                    ├── post-1.md                    └── post-2.md

Astro does not support.tsx or.jsx as page file types.

For UI frameworks like React and Vue, use them how younormally would with Astro by importing them as components.

Feel free to pass the translated contenttitle={t('title')} or localelocale={locale} as props.

By default, all pages inpages/api/**/* are ignored.

For.ts and.js endpoints, how you handle multiple locales is up to you. As endpoints are not user-facing and there are many different ways to use endpoints, we leave the implementation up to your preferences.

MIT Licensed

PRs welcome! Thank you for your help. Read more in thecontributing guide for reporting bugs and making PRs.