# General Translation Integrations: 拡張 API URL: https://generaltranslation.com/ja/docs/integrations/paraglide/reference/extension-api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Paraglide JS として扱う対象、解析対象のファイル形式、インポート文の解決方法をカスタマイズします。ターゲット、言語、バンドラー設定、リゾルバーの API リファレンスです。 このページで紹介するものはすべて `@generaltranslation/paraglide-js/compiler` からエクスポートされており、オプション経由で [`collectContext`](/docs/integrations/paraglide/reference/collect-context) に渡します。解析処理そのもの (モジュールグラフ、使用箇所の検出、レンダリング) は内部で行われます。 ## 概要 [#overview] | API | 説明 | | ----------------------------------- | ------------------------------------------ | | [ターゲット](#targets) | 解決済みファイルのうち Paraglide JS に属するものと、そのエクスポート。 | | [言語](#languages) | フレームワークのツールによって TypeScript に変換されるファイル形式。 | | [バンドラー設定](#bundler-configs) | インポートのエイリアスの読み込み元となる設定ファイル。 | | [リゾルバー](#resolvers) | インポートをファイルに解決する関数と、その組み込み先となるコレクター。 | ## ターゲット [#targets] ターゲットは、解決済みのファイルのうちどれが Paraglide JS に属するか、また各ファイルのエクスポートがそれぞれ何であるかを指定します。ターゲットは [`targets`](/docs/integrations/paraglide/reference/collect-context#targets) オプションで渡します。1 つのファイルに複数のターゲットが一致する場合は、最後に指定したものが優先されます。 ```ts type ParaglideTarget = { name: string; // 使用箇所に付けるラベル（例: "message"） matches(file: TargetFile): boolean; // エクスポートを追跡しない場合は undefined を返します。 exportSymbol(exportName: string, file: TargetFile): SymbolSpec | undefined; }; type TargetFile = { file: string; // スラッシュ区切りの絶対パス outdir: string | undefined; // ファイルを含む出力ディレクトリ outdirPath: string | undefined; // outdir からの相対パス（例: "messages.js"） }; type SymbolSpec = | { type: 'namespace'; member(name: string): SymbolSpec | undefined } // methods: 呼び出しも使用箇所としてカウントされるメソッド（例: messages の .parts()） | { type: 'value'; name: string; methods?: readonly string[] }; ``` | エクスポート | 説明 | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultTargets` | `messagesTarget`、`runtimeTarget`、`serverTarget`、`registryTarget`、`adapterTargets`。 | | `messagesTarget` | `messages.js` (`m` 名前空間を含む) と、`messages/` 内のすべてのモジュール。名前は `message`。 | | `runtimeTarget`, `serverTarget`, `registryTarget` | `runtime.js`、`server.js`、`registry.js` のすべてのエクスポート。 | | `adapterTargets` | Paraglide のフレームワークアダプター (`@inlang/paraglide-js-react`、`-solid`、`-svelte`、`-vue`) と、Paraglide JS 1 の `@inlang/paraglide-sveltekit`、`@inlang/paraglide-next`、`@inlang/paraglide-astro`。 | | `defineTarget(target)` | ターゲットをそのまま `ParaglideTarget` 型として返します。 | | `generatedFileTarget(name, outdirPath)` | 出力ディレクトリ内のファイル。そのすべてのエクスポートが追跡対象になります。 | | `packageTarget(name, packageName)` | インストール済みのパッケージ。その名前付きエクスポートが追跡対象になります。 | *注：[メタデータファイル](/docs/integrations/paraglide/reference/metadata-files)に書き込まれるのは、`message` ターゲットの使用箇所のみです。その他のターゲットの使用箇所も解析はされますが、書き込み先となるメッセージキーがありません。* ## 言語 [#languages] 言語は、フレームワーク独自のツールを使ってファイル形式を 1 つの JavaScript または TypeScript モジュールに変換するアダプターです。言語は [`languages`](/docs/integrations/paraglide/reference/collect-context#languages) オプションで渡します ([ファイル形式の追加](/docs/integrations/paraglide/guides/adding-file-formats)を参照) 。 ```ts type SourceLanguage = { name: string; extensions: readonly string[]; // .ts ファイル内の Angular コンポーネントなど、スクリプト系の拡張子を扱う場合に必須です。 detect?(source: string, file: string): boolean; // アプリに必要なパッケージ。不足している場合はそのパッケージ名が表示されます。 requires?: readonly string[]; // 必要なパッケージを依存関係として導入するパッケージ: { svelte2tsx: 'svelte-check' }。 installedWith?: Readonly>; // ツールがインストールされていない場合は undefined を返し、ツールがファイルを // 拒否した場合は例外をスローします。いずれの場合もファイルはスキップされます。 generate( source: string, file: string, context: LanguageContext ): GeneratedSource | undefined | Promise; }; type LanguageContext = { // アプリにインストールされたパッケージをインポートします。インストールされていない場合は undefined です。 load(specifier: string): Promise; }; type ParseLang = 'js' | 'jsx' | 'ts' | 'tsx'; ``` ### 生成されたソース `generate` は `GeneratedSource` を返します。マッピングを持たないコードが使用箇所として扱われることはありません。 | フィールド | 説明 | 型 | 任意 | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------- | --- | | `code` | 1 つのモジュールとして表現したファイル。 | `string` | いいえ | | `lang` | `code` の言語。 | `ParseLang` | いいえ | | `mappings` | `code` の各範囲がファイル内のどこに対応するか。 | `Mapping[]` | いいえ | | `elements` | ファイルのマークアップ。各使用箇所に、その要素を示すラベルを付けます。このラベルはメタデータファイルには書き込まれません。 | `SourceElement[]` | はい | | `scripts` | ファイル内に含まれる独立したモジュール (Astro ページのクライアントスクリプトなど) 。それぞれ `GeneratedScript`: `{ code, lang, mappings }` として表されます。 | `GeneratedScript[]` | はい | | `componentFields` | Angular のテンプレートのように、テンプレートが宣言なしでフィールドを参照するクラス。それぞれ `ComponentFields`: `{ specifier, className?, range? }` として表されます。 | `ComponentFields[]` | はい | | `scopeObjects` | メンバーがモジュール内の名前と同様に解決されるオブジェクト (Vue の `__VLS_ctx` など) 。 | `string[]` | はい | | `props` | 呼び出し元から渡された props をコンポーネントが読み取る箇所: `{ calls?, members?, variables?, undeclared? }`。 | `object` | はい | | `componentInstances` | 生成されたコードが、インポートしたコンポーネントを JSX 以外の方法でレンダリングする方法: `{ via: 'new' \| 'call', path }`。 | `object` | はい | ### マッピングと要素 ```ts // 生成コード側の [generated, generated + length) は // ソース側の [source, source + sourceLength) に対応します。sourceLength のデフォルトは length です。 type Mapping = { generated: number; source: number; length: number; sourceLength?: number; }; // svelte2tsx が出力するようなバージョン 3 のソースマップから生成します。マップはオブジェクト // （@jridgewell/trace-mapping の EncodedSourceMap）または JSON 文字列として渡します。 function mappingsFromSourceMap( map: EncodedSourceMap | string, generatedCode: string, sourceCode: string ): Mapping[]; // Volar の仮想コードのマッピングから生成します: // @vue/language-core, @mdx-js/language-service, Glint. // Volar のマッピングをそのまま渡してください。 function mappingsFromVolar( mappings: readonly { sourceOffsets: readonly number[]; generatedOffsets: readonly number[]; lengths: readonly number[]; generatedLengths?: readonly number[]; }[] ): Mapping[]; ``` `SourceElement` は、1 つのマークアップ要素をソース上のオフセット付きで表します。プロパティは `name`、`start`、`end`、`nameStart`、`nameEnd`、`openEnd`、`component`、`attributes` です (`attributes` の各要素は `{ name, start, end }` の形式で、範囲は属性値の位置を示します) 。 ### 組み込みの言語 `defaultLanguages` には、`vueLanguage`、`svelteLanguage`、`astroLanguage`、`mdxLanguage`、`markdownLanguage`、`angularComponentLanguage`、`angularTemplateLanguage`、`analogLanguage`、`markoLanguage`、`emberLanguage` がこの順に含まれています。いずれも個別にエクスポートされています。各言語が対応するファイルとツールについては、[サポートされているファイル形式](/docs/integrations/paraglide/reference/file-formats)を参照してください。 ## バンドラー設定 [#bundler-configs] バンドラー設定を使うと、バンドラーを実行せずに設定ファイルからインポートエイリアスを読み取れます。バンドラー設定は [`bundlerConfigs`](/docs/integrations/paraglide/reference/collect-context#bundler-configs) オプションで指定します ([インポートの解決](/docs/integrations/paraglide/guides/resolving-imports#bundler-config)を参照してください) 。 ```ts type BundlerConfig = { name: string; files: readonly string[]; // 設定ファイル名の候補 // file は絶対パスです。失敗した場合（戻り値・スローのいずれでも）は報告され、 // その設定はスキップされます。 read( file: string, context: ConfigContext ): Promise; }; type ImportResolution = { aliases: readonly ImportAlias[]; rootDirectory?: string; // /src/a.js を解決する際の基準ディレクトリ（Vite の root） }; type ConfigFailure = { error: string }; type ConfigContext = { // アプリからパッケージをインポートします。未インストールの場合は undefined を返します。 load(specifier: string): Promise; }; type ImportAlias = { find: string | RegExp; // 文字列の場合、find と find/… の両方に一致します replacement: string; exact?: boolean; // 文字列の場合、find そのものにのみ一致します（webpack の name$ に相当） }; type AliasOption = Readonly> | readonly ImportAlias[]; ``` | Export | 説明 | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `defaultBundlerConfigs` | `viteConfig`、`webpackConfig`、`rspackConfig` をこの順序で含みます。 | | `viteConfig` | アプリ自身の Vite を使用して `vite.config.*` を読み取ります。解決済みのエイリアスと Vite のルートを返します。 | | `webpackConfig`, `rspackConfig` | `webpack.config.*` および `rspack.config.*` をインポートし、`resolve.alias` を読み取ります。 | | `webpackLikeConfig(name, baseName)` | ファイル名が `baseName` で、拡張子が `.js`、`.mjs`、`.ts`、`.cjs`、`.mts`、`.cts` のいずれかである webpack 形式の設定ファイル用に、バンドラー設定を作成します。 | webpack 形式の設定ファイルは、オブジェクト、関数、またはそれらのリストをエクスポートできます。リストの場合は最初のエントリが使用されます。関数は、空の `env` と `{ mode: 'production' }` を引数として呼び出されます。 ## リゾルバー [#resolvers] リゾルバーは、インポートの解決先となるファイル、または `undefined` を返します。独自のリゾルバーを使用するには、[`collectContext`](/docs/integrations/paraglide/reference/collect-context) が内部でラップしているコレクターを自分で作成してください ([インポートの解決](/docs/integrations/paraglide/guides/resolving-imports#custom-resolver)を参照) 。 ```ts type Resolver = ( specifier: string, importer: string ) => Promise; function createCollector( options: ParaglideContextOptions, environment: CollectorEnvironment ): ContextCollector; type CollectorEnvironment = { root: string; // プロジェクト、またはその中のディレクトリ logger: CollectorLogger; // { warn(message), info(message) } resolver: Resolver; }; ``` `ParaglideContextOptions` は、`collectContext` のオプションのうち解決に関係しないもの (`include`、`exclude`、`targets`、`languages`、`inlangProjects`、`radius`、`outdirs`、`autoImports`) を保持します。返された `ContextCollector` で `scanAll()` を呼び出してプロジェクトを解析し、続けて `write()` を呼び出してメタデータファイルを書き出します。 | Export | 説明 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nodeResolver(options?)` | バンドラーなしで、バンドラーと同様に解決を行います。対象は、エイリアス、パッケージの `exports` と `imports`、各インポート元に最も近い `tsconfig.json` の `paths`、および TypeScript の `./a.js` から `./a.ts` への解決です。`NodeResolverOptions` (`{ alias?, rootDirectory?, conditions? }`) を受け取ります。 | | `ProjectResolver` | `collectContext` が使用するリゾルバーです。まずアプリのバンドラー設定のエイリアスを適用し、次に `nodeResolver` を使用します。 | ```ts import { createCollector, ProjectResolver, } from '@generaltranslation/paraglide-js/compiler'; const environment = { root: process.cwd(), logger: console }; // ProjectResolverOptions: NodeResolverOptions と bundlerConfigs const resolver = new ProjectResolver({ alias: { '~': '/app/src' } }, environment); const collector = createCollector( { include: ['src'] }, { ...environment, resolver: resolver.resolve } ); await collector.scanAll(); await collector.write(); await resolver.warnUnresolved(); // 未宣言のエイリアスの可能性があるインポート文を一覧表示する ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.