# Astro

Source: https://verbaly.dev/docs/frameworks/astro

The official Astro integration. One line in astro.config wires live extraction, typed keys and the build report; if you use the pre-translated mirror flow, verbaly render runs by itself after every build.

What you can accomplish:

- Write your text directly in `.astro` files, frontmatter and markup: keys, types and catalogs stay in sync while you code
- Ship every language as static pages, with two flows to choose from
- In the mirror flow, `verbaly render` runs by itself after every build: pre-translated pages, hreflang and a per-language sitemap with zero extra steps
- A build that lists missing translations, the same report as every other Verbaly setup

## Installation

Add the runtime and this integration, then the compiler, which is where the `verbaly` command lives. `init` writes your config and your source catalog.

```sh
npm install verbaly @verbaly/astro
# or: pnpm add verbaly @verbaly/astro
# or: yarn add verbaly @verbaly/astro
# or: bun add verbaly @verbaly/astro
```

```sh
npm install -D @verbaly/compiler
# or: pnpm add -D @verbaly/compiler
# or: yarn add -D @verbaly/compiler
# or: bun add -D @verbaly/compiler
```

```sh
npx verbaly init
```

## Wire it up

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import verbaly from '@verbaly/astro';

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

That single line injects the Vite plugin with your project root pinned: live extraction while you code, the typed `verbaly/app` module and the build report. The generated types live inside Astro's own `.astro` folder, and `npx verbaly extract` writes that same file, so none is added to your project. Options are the same as the Vite plugin (`locales`, `sourceLocale`, `dir`, `failOnMissing`…), and they live in your `verbaly.config`, where `verbaly check` and `verbaly extract` read them too.

## Write the text in place

```astro title="src/pages/index.astro"
---
import { createRequestInstance, sourceLocale } from 'verbaly/app';

const { t } = await createRequestInstance(Astro.currentLocale ?? sourceLocale);
const name = 'Ada';
const count = 3;
const title = t`Search and find`;
---

<h1>{title}</h1>
<p>{t`Hello ${name}, you have ${count} messages`}</p>
<img alt={t`Company logo`} src="/logo.png" />
```

The compiler reads your `.astro` files like any other source. The frontmatter and the markup expressions both extract, every message becomes a stable key with typed params, and an untranslated entry is listed by every build and fails `verbaly check` before it ships.

## Two ways to ship the languages

Astro sites are static by default, so the language has to be decided at build time. Pick the flow that matches your routing:

### Path-based pages

If Astro's i18n routing owns your URLs (`/es/…`, `/pt/…`), build one instance per request and use `t` as usual. Astro owns the routes, Verbaly owns the catalogs and the type safety. `createRequestInstance` waits for the catalog before it returns, which is what makes the page arrive translated instead of flashing, and `Astro.currentLocale` is empty outside a localized route, so the fallback is not decoration.

```astro title="src/pages/[locale]/index.astro"
---
import { createRequestInstance, sourceLocale } from 'verbaly/app';
const { t } = await createRequestInstance(Astro.currentLocale ?? sourceLocale);
---
```

The integration reads `i18n` in your `astro.config`, so `switchLocale` and `localePath` go to the page Astro serves in the other language: your source language at the root and the rest under their prefix, or every language under one with `prefixDefaultLocale: true`. A prefix mode your `verbaly.config` names stays as it is, and so does Astro's `routing: 'manual'`. `npx verbaly doctor` shows the mode in use.

In two cases Verbaly keeps one address, and the dev server and the build say so:

- Astro's `defaultLocale` is not your `sourceLocale` and `prefixDefaultLocale` is off: make them the same language, or turn it on.
- A language has a path that is none of its codes: use the language code as its path.

### Mirror mode

One page tree, pre-translated in every language. Bind your markup with `data-verbaly` attributes and add a `render` section to your config. After `astro build`, the integration mirrors the site into `dist/es/`, `dist/pt/`… with every message pre-filled, plus hreflang alternates and a per-language sitemap when you set `baseUrl`. No flash of untranslated content, and no client work.

```js title="verbaly.config.mjs"
export default {
  locales: ['en', 'es', 'pt'],
  render: { baseUrl: 'https://example.com', sitemap: true },
};
```

The sitemap holds the pages a search engine should index. Your redirects and your 404 stay out of it, because they say so themselves, and they are still mirrored into every language so a visitor who reaches one gets it there. Leave more out with `render.exclude`.

Every address the mirror writes, in hreflang, the sitemap, the canonical and the links between pages, follows your `trailingSlash`. With `'never'` the Spanish home is `/es`, so each page has one address.

With `<ClientRouter />`, `verbaly/app` takes the language of each page before it swaps in, so a live `bindDom` paints the new page in its own language. It binds the whole document, so it keeps working after the router replaces the page's body.

A mirrored site can go further: text that only one page shows does not need to reach the browser at all, because the mirror already wrote it into the HTML. Name those groups under `bundle` and every other page stops downloading them.

```js title="verbaly.config.mjs"
export default {
  locales: ['en', 'es', 'pt'],
  bundle: { exclude: ['changelog'] },
  render: { baseUrl: 'https://example.com', sitemap: true },
};
```

### Each page brings only its own words

A mirrored page arrives already translated, and yet the visitor still downloads every message of that language, most of which the page never shows. Turn on `inlineCatalog` and the mirror writes into each page exactly the messages it renders, so a translated page needs no catalog of its own.

```js title="verbaly.config.mjs"
export default {
  locales: ['en', 'es', 'pt'],
  render: { baseUrl: 'https://example.com', inlineCatalog: true },
};
```

On this site the Spanish messages weigh about 59 KB compressed. The home page uses 3 KB of them, so a first visit stops downloading about 56 KB, nine times what all of Verbaly’s runtime weighs here. The heaviest page is the changelog, and even that one saves 25 KB.

If your page later asks for a message it did not show, Verbaly fetches the rest once and updates, rather than quietly showing your source language. Your source pages get nothing extra: their messages already travel with the app.

With `<ClientRouter />` this keeps working as the visitor clicks around, and you write no code for it: `verbaly/app` hands the runtime each page's own messages as that page swaps in.

> **The mirror is opt-in**
>
> It only runs when your config has a `render` section (or you pass `render: true` to the integration), so path-based sites are never mirrored on top. Server output skips it too, and there the page above is the answer: build the instance per request from `Astro.currentLocale`.
