Astro 3.5: i18n Routing

By
Erika
Emanuele Stoppa
Matthew Phillips
Nate Moore
Bjorn Lu

Astro 3.5 is out today and features new i18n routing, prefetch optimization, and more. This may be one of the biggest minor releases in Astro history!

Release highlights include:

To take advantage of the latest features, make sure you’re running the latest version of Astro. You can upgrade to Astro 3.5 by running the upgrade command for your package manager of choice:

npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

i18n Routing (experimental)

It’s now easier than ever to build multilingual apps with Astro.

Astro’s experimental i18n routing API 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.

Enable the experimental routing option by adding an i18n object to your Astro configuration with a default location and a list of all languages to support:

// astro.config.mjs
import {defineConfig} from "astro/config";


export default defineConfig({
  experimental: {
    i18n: {
      defaultLocale: "en",
      locales: ["en", "es", "pt-br"]
    }
  }
})

Organize your content folders by locale depending on your i18n.routingStrategy, and Astro will handle generating your routes and showing your preferred URLs to your visitors.

├── src
│   ├── pages
│   │   ├── about.astro
│   │   ├── index.astro
│   │   ├── es
│   │   │   ├── about.astro
│   │   │   ├── index.astro
│   │   ├── pt-br
│   │   │   ├── about.astro
│   │   │   ├── index.astro

Compute relative URLs for your links with getLocaleRelativeURL from the new astro:i18n module:

---
import {getRelativeLocaleUrl} from "astro:i18n";
const aboutUrl = getRelativeLocaleUrl("pt-br", "about");
---
<p>Learn more <a href={aboutUrl}>About</a> this site!</p>

Enabling i18n routing also provides two new properties for browser language detection: Astro.preferredLocale and Astro.preferredLocaleList. These combine the browser’s Accept-Language header, and your site’s list of supported languages and can be used to automatically respect your visitor’s preferred languages.

Read more about Astro’s experimental i18n routing in our documentation.

Prefetch

Prefetch is a browser feature to fetch pages in advance for your visitors so that they are partially-loaded even before navigation. For multi-page apps, prefetch is an important part of keeping your site speedy.

Prefetch in Astro had previously been available via an official integration (@astrojs/prefetch). Today we are bringing prefetch into core as an opt-in feature, and expanding what it can do.

You can enable prefetching by setting prefetch:true in your Astro config:

// astro.config.js
import { defineConfig } from 'astro/config';


export default defineConfig({
  prefetch: true
})

In addition to now being a core feature, the new prefetch also comes with more flexibility:

  • Configure whether prefetching occurs on tap (a touch that’s not a full click), hover, or upon entering the viewport.
  • Define which strategy is used on a per-link basis using the data-astro-prefetch attribute.
  • Set prefetching on all links by default (the existing behavior when using <ViewTransitions />).
  • Ignore hover and scroll events that occur quickly, to prevent overfetching content your visitor is not likely to click.

Prefetch is enabled by default when using View Transitions and the new implementation now makes it possible to opt out of prefetch on a per-link basis:

<a href="/logout" data-astro-prefetch="false">Logout</a>

Visit the Prefetch guide for more information.

Content Collections Build Cache (experimental)

Large static sites that heavily use Content Collections can try out the new experimental build cache.

This includes multiple refactors to Astro’s build process to optimize how Content Collections are handled, which should provide significant performance improvements for users with many collections.

Users building a static site can opt in to preview the new build cache by adding the following flag to your Astro config:

// astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  experimental: {
    contentCollectionCache: true,
  },
})

When this experimental feature is enabled, the files generated from your content collections will be stored in the cacheDir (by default, node_modules/.astro) and reused between builds. Most CI environments automatically restore files in node_modules/ by default.

In our internal testing on the real world Astro Docs project, this feature reduces the bundling step of astro build from 133.20s to 10.46s, about 92% faster. The end-to-end astro build process used to take 4mins 58s and now takes just over 60s for a total reduction of 80%.

If you run into any issues with this experimental feature, please let us know!

You can always bypass the cache for a single build by passing the --force flag to astro build.

astro build --force

Form support in View Transitions

The <ViewTransitions /> router can now handle form submissions, allowing the same animated transitions and stateful UI retention on form posts that are already available on <a> links. With this addition, your Astro project can have animations in all of these scenarios:

  • Clicking links between pages.
  • Making stateful changes in forms (e.g. updating site preferences).
  • Manually triggering navigation via the navigate() API.

This feature is currently opt-in, but will be enabled by default starting in Astro 4.0. To enable, add the handleForms prop to the <ViewTransitions /> component on your page:

---
// src/layouts/MainLayout.astro
import { ViewTransitions } from 'astro:transitions';
---


<html>
  <head>
    <!-- ... -->
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Just as with links, if you don’t want the routing handling a form submission, you can opt out on a per-form basis with the data-astro-reload property:

---
// src/components/Contact.astro
---
<form class="contact-form" action="/request" method="post" data-astro-reload>
  <!-- ...-->
</form>

Form support works on post method="get" and method="post" forms.

Image optimization improvements

Astro assets has continued to undergo improvements and in 3.5 we now have:

  • Original images are deleted from the final build that are not used outside of the optimization pipeline. For users with a large number of these images (e.g. thumbnails), this should reduce storage consumption and deployment times.
  • A new property, propertiesToHash, has been added to allow specifying which properties of getImage() / <Image /> / <Picture /> should be used for hashing the result files when doing local transformations. For most services, this will include properties such as src, width, or quality that directly change the content of the generated image.
  • The <Picture /> component will now use jpg and jpeg respectively as fallback formats when the original image is in those formats.

Integration Hooks to add Middleware

It’s now possible in Astro for an integration to add middleware on behalf of the user. Previously when a third party wanted to provide middleware, the user would need to create a src/middleware.ts file themselves. Now, adding third-party middleware is as easy as adding a new integration.

For integration authors, there is a new addMiddleware function in the astro:config:setup hook. This function allows you to specify a middleware module and the order in which it should be applied:

// my-package/middleware.js
import { defineMiddleware } from 'astro:middleware';


export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();


  if(response.headers.get('content-type') === 'text/html') {
    let html = await response.text();
    html = minify(html);
    return new Response(html, {
      status: response.status,
      headers: response.headers
    });
  }


  return response;
});

You can now add your integration’s middleware and specify that it runs either before or after the application’s own defined middleware (defined in src/middleware.{js,ts})

// my-package/integration.js
export function myIntegration() {
  return {
    name: 'my-integration',
    hooks: {
      'astro:config:setup': ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: 'my-package/middleware',
          order: 'pre'
        });
      }
    }
  };
}

Multiple code themes (experimental)

Astro recently upgraded to use the shikiji library for syntax highlighting, and we’ve now added the ability to support multiple themes via a new markdown.shikiConfig.experimentalThemes option.

This enables you to more easily define a light and dark mode theme for syntax highlighted code blocks. You might use it like this:

// astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  markdown: {
    shikiConfig: {
      experimentalThemes: {
        light: 'github-light',
        dark: 'github-dark'
      }
    }
  }
});

Qwik Integration

From our community, there is now an Astro integration for using Qwik with Astro! You can install the Qwik integration by running:

npx astro add @qwikdev/astro

Or you can install the integration yourself, and update your config:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import qwikdev from '@qwikdev/astro';


export default defineConfig({
  integrations: [qwikdev()],
});

Check out the blog post to learn more about the new integration and if you run into any issues visit the integration repository.

Bug Fixes

Additional bug fixes are included in this release. Check out the release notes to learn more.