抽出、コンパイル、検証

パイプラインは 3 つの段階に分けて考える

抽出 (lingui extract)
- メッセージ記述子を見つけてカタログに書き出します
コンパイル (lingui compile)
- カタログを実行時に使える形へ整えます
検証
- アプリが期待どおりの翻訳結果を描画することを確認します

この 3 つを分けて扱うと、問題の切り分けがかなり楽になります。

変換と抽出は別の関心事

Lingui マクロを使う各ファイル種別では、2 つの設定をそれぞれ独立して行う必要があります。

ビルド時にマクロ呼び出しを実行時呼び出しへコンパイルする ビルド変換
lingui extract がソースファイルからメッセージ記述子を見つけられるようにする エクストラクタ

これらは別の段階で動作します。ビルドが成功したからといって、抽出まで正しく動いているとは限りません。エクストラクタは Lingui CLI から別個に実行されるため、個別に設定しなければなりません。

ファイル種別	ビルド変換	エクストラクタ
`.svelte`	`lingui-for-svelte/unplugin/vite`	`lingui-for-svelte/extractor`
`.astro`	`lingui-for-astro/integration`	`lingui-for-astro/extractor`
`.ts`, `.js`, `.tsx`, `.jsx`	`unplugin-lingui-macro/vite`	`@lingui/cli/api/extractors/babel`（デフォルトエクスポート）

混在したプロジェクトでは、両方のエクストラクタを並べて指定する必要があります。たとえば、共通ユーティリティを素の TypeScript で持つ SvelteKit プロジェクトでは次のようになります。

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

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

babelExtractor を入れないと、.ts ファイル内の t 呼び出しはビルド時には正しくコンパイルされても、エクストラクタによって抽出されたカタログには現れません。

フレームワーク変換に設定可能な振る舞いがある場合は、その設定を lingui.config.ts の対応する framework キーの下に置いてください。ビルド変換とエクストラクタは同じ設定を読み込むため、リッチテキストのコンポーネントマクロにおける空白のような設定も 1 か所に置けます。

import { defineConfig } from "lingui-for-svelte/config";
import { svelteExtractor } from "lingui-for-svelte/extractor";

export default defineConfig({
  locales: ["en", "ja"],
  framework: {
    svelte: {
      whitespace: "jsx",
    },
  },
  extractors: [svelteExtractor],
});

詳しくはコンポーネントマクロにおける空白を参照してください。

どのツールが何を担当するか

lingui-for-svelte と lingui-for-astro
- フレームワーク構文への対応と、フレームワーク固有のエクストラクタ
unplugin-lingui-macro
- 素の JS / TS における Lingui マクロ変換
Lingui CLI
- 抽出とカタログのコンパイル

抽出、コンパイル、検証

パイプラインは 3 つの段階に分けて考える

変換と抽出は別の関心事

どのツールが何を担当するか

おすすめの進め方