コンポーネントマクロにおける空白

コンポーネントマクロは内部的には JSX 互換の仕組みで処理されますが、Svelte と Astro のテンプレートは JSX ではありません。

そのため、コンパイラが素の JSX のルールに従うと、子ノード間の空白が異なる形で解釈されることがあります。 これは Trans のようなリッチテキストメッセージで特に重要で、空白が足りなかったり余分だったりすると、抽出されるメッセージテキストが変わってしまいます。

whitespace オプションを使うと、こうした境界をどう扱うか選べます。 通常は未指定のままで問題ありません。 未指定の場合、コンポーネントマクロは生の JSX の意味論ではなく、フレームワークを考慮した空白の挙動に従います。

デフォルトの挙動

lingui-for-svelte と lingui-for-astro では、whitespace の既定値はそれぞれのフレームワークのモードです。 そのため、リッチテキストの子要素の境界では、明示的に jsx を選ばない限り、フレームワークに応じた空白処理が行われます。

• Svelte では、既定値は svelte です。
• Astro では、既定値は astro です。
• JSX 形式の空白の意味論を明示的に使いたい場合だけ jsx を選んでください。

何が変わるのか

たとえば、次のように書いたとします。

<Trans>
  Read
  <a href="/docs">docs</a>
  now
</Trans>

フレームワーク対応の既定値では、抽出されるリッチテキストメッセージに単語境界の空白が保たれます。

Read <0>docs</0> now

whitespace: "jsx" では、同じソースが JSX として正規化されるため、Svelte や Astro の利用者が残ると期待する空白が失われることがあります。

明示的な空白が優先される

すでに {" "} のような明示的な空白式を書いている場合は、それが優先されます。 フレームワーク対応の空白処理が、その隣にさらに空白を追加することはありません。

<Trans><strong>Read</strong>{" "}<em>carefully</em></Trans>

これは次と同等のままです。

<0>Read</0> <1>carefully</1>

オプションを設定する

whitespace 設定は、lingui.config.ts の対応するフレームワークキーの下に置きます。 フレームワークのビルド変換とエクストラクタはどちらもこの設定を読み込むため、Vite、Astro、エクストラクタの設定で同じオプションを繰り返す必要はありません。

警告

framework セクションを追加する場合は、lingui-for-svelte/config または lingui-for-astro/config の defineConfig を使ってください。 Lingui 公式の @lingui/conf ヘルパーや、defineConfig を使わない通常のオブジェクトでのエクスポートの場合、標準の Lingui 設定としては読み込めますが、フレームワーク固有の設定が無視される可能性があります。 詳しくは フレームワーク設定 を参照してください。

Svelte

lingui.config.ts

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

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

Astro

lingui.config.ts

import { defineConfig } from "lingui-for-astro/config";
import { astroExtractor } from "lingui-for-astro/extractor";

export default defineConfig({
  framework: {
    astro: {
      whitespace: "astro",
    },
  },
  extractors: [astroExtractor],
});

プロジェクトが標準ではない設定ファイルパスやインライン設定オブジェクトを使う場合は、必要に応じてフレームワークプラグインやインテグレーションと、エクストラクタのそれぞれに config オプションを渡してください。 デフォルトの lingui.config.* ファイルを使う場合、設定は自動的に発見されます。

Svelte

vite.config.ts

import { defineConfig } from "vite";
import linguiForSvelte from "lingui-for-svelte/unplugin/vite";

export default defineConfig({
  plugins: [linguiForSvelte()],
});

Astro

astro.config.ts

import { defineConfig } from "astro/config";
import linguiForAstro from "lingui-for-astro/integration";

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

jsx を使うべき場面

jsx は互換性維持のためのモードとしてだけ使ってください。

既定のフレームワーク対応モードは、Svelte や Astro がテンプレートノード間の空白を扱う方法に合わせます。 そのため、新しいコードでは通常こちらが適切です。 以前に JSX 形式の空白正規化で抽出したメッセージを維持したい場合や、リッチテキストの子要素境界を意図的に JSX と同じように扱いたい場合だけ jsx を選んでください。

jsx とフレームワーク対応モードを切り替えると、一部のコンポーネントマクロ呼び出しでは、抽出されるメッセージや生成される ID が変わる場合があります。 変換とエクストラクタでは同じ whitespace 設定を使ってください。

ビルド変換とエクストラクタが同じフレームワーク設定を共有する仕組みについては フレームワーク設定 を参照してください。