Astro: Getting Started

Install the packages

Vite+

vp add @lingui/core lingui-for-astro
vp add -D @lingui/cli @lingui/conf unplugin-lingui-macro

npm

npm install @lingui/core lingui-for-astro
npm install -D @lingui/cli @lingui/conf unplugin-lingui-macro

pnpm

pnpm add @lingui/core lingui-for-astro
pnpm add -D @lingui/cli @lingui/conf unplugin-lingui-macro

yarn

yarn add @lingui/core lingui-for-astro
yarn add -D @lingui/cli @lingui/conf unplugin-lingui-macro

Tip

unplugin-lingui-macro is only needed if you use Lingui macros in plain JavaScript or TypeScript files. If you only use macros in .astro files, you can skip installing this package and remove it from vite.plugins in astro.config.ts. See Plain JS/TS Setup for the full setup guide.

Configure Astro

astro.config.ts

import { defineConfig } from "astro/config";
import linguiForAstro from "lingui-for-astro/integration";
import linguiMacro from "unplugin-lingui-macro/vite";

export default defineConfig({
  integrations: [linguiForAstro()],
  vite: {
    plugins: [linguiMacro()],
  },
});

Configure Lingui

lingui.config.ts

import babelExtractor from "@lingui/cli/api/extractors/babel";
import { defineConfig } from "lingui-for-astro/config";
import { astroExtractor } from "lingui-for-astro/extractor";

export default defineConfig({
  locales: ["en", "ja"],
  sourceLocale: "en",
  catalogs: [{ path: "src/lib/i18n/locales/{locale}" }],
  extractors: [astroExtractor, babelExtractor],
});

Tip

If you do not use Lingui macros in plain JavaScript or TypeScript files, you can omit babelExtractor from the extractors array and skip the import.

Use the optional framework.astro field in this config when you need Astro-specific options such as custom macro package names, whitespace handling, or runtime warning switches. See Framework Config for details.

Initialize Lingui for your output mode

For server and hybrid output, call setLinguiContext from middleware before any page renders. This is where you load the compiled catalog for the current request.

src/middleware.ts

import { defineMiddleware } from "astro:middleware";
import { setupI18n } from "@lingui/core";
import { setLinguiContext } from "lingui-for-astro";
import { catalog } from "./lib/i18n/catalog";

export const onRequest = defineMiddleware((context, next) => {
  const locale = resolveLocale(context); // your locale resolution logic
  const i18n = setupI18n({ locale, messages: catalog });
  setLinguiContext(context.locals, i18n);
  return next();
});

Note

Middleware runs for every page regardless of output mode: for server/hybrid output it handles each request, and for static output it runs per page during the build. It is the recommended initialization pattern in all cases. For simple static pages with no locale logic, page frontmatter setup is also available as an escape hatch. Keep that setup at the page or layout boundary, not inside reusable components. See i18n Context.

Tip

catalog is a locale-keyed object exported from a shared setup file. See Load Compiled Catalogs for how to create that file and choose between bundling all locales upfront or loading them on demand.

Use macros in .astro

src/pages/index.astro

---
import { Trans, t } from "lingui-for-astro/macro";
---

<h1>{t`Hello from Astro`}</h1>
<p><Trans>Macro-first translation in Astro</Trans></p>

Next pages

• Read i18n Context for how Astro.locals carries the i18n instance, how static and request-aware setup differ, and how to access it manually.
• Read Using Islands if you have client framework islands that need translation.
• Read Astro caveats for server/runtime boundaries.