Astro: はじめに

パッケージをインストールする

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

ヒント

unplugin-lingui-macro が必要なのは、素の JavaScript または TypeScript ファイルで Lingui マクロを使う場合だけです。 マクロを .astro ファイルでしか使わないなら、このパッケージのインストールは省略でき、astro.config.ts の vite.plugins からも外せます。 詳しい設定は プレーンな JS/TS でのセットアップ を参照してください。

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()],
  },
});

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],
});

ヒント

素の JavaScript または TypeScript ファイルで Lingui マクロを使わないなら、extractors 配列から babelExtractor を外し、インポートも省略できます。

カスタムのマクロパッケージ名、空白処理、実行時警告の切り替えなど、Astro 固有のオプションが必要な場合は、framework.astro フィールドを設定してください。 詳細は フレームワーク設定 を参照してください。

出力モードに応じて Lingui を初期化する

server と hybrid 出力では、ページが描画される前にミドルウェアから setLinguiContext を呼びます。 ここで、そのリクエスト向けのコンパイル済みカタログを読み込みます。

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); // 独自のロケール解決ロジック
  const i18n = setupI18n({ locale, messages: catalog });
  setLinguiContext(context.locals, i18n);
  return next();
});

注意

ミドルウェアは出力モードに関係なくすべてのページで動きます。 server / hybrid 出力では各リクエストで処理され、static 出力ではビルド時に各ページごとに処理されます。 どの場合でも、これが推奨される初期化パターンです。 ロケールのロジックを持たない単純な静的ページでは、ページのフロントマターで初期化することもできますが、これはエスケープハッチです。 この場合も、再利用コンポーネント内ではなく、ページまたはレイアウト境界に置いてください。 詳しくは i18n コンテキスト を参照してください。

ヒント

catalog は共有設定ファイルからエクスポートされる、ロケールをキーにしたオブジェクトです。 このファイルの作り方と、全ロケールを最初からまとめてバンドルするか必要時に読み込むかの選び方は コンパイル済みカタログの読み込み を参照してください。

.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>

次に読むページ

• Astro.locals が i18n インスタンスをどう保持するか、静的サイトとリクエスト依存の初期化がどう違うか、手動でどうアクセスするかは i18n コンテキスト を参照してください。
• クライアントフレームワークのアイランドで翻訳が必要なら アイランドを使う を参照してください。
• サーバーと実行時の境界については Astro の注意点 を参照してください。