# General Translation Integrations: インポート文の解決
URL: https://generaltranslation.com/ja/docs/integrations/paraglide/guides/resolving-imports.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 解析がアプリのインポートエイリアスを辿って Paraglide JS ファイルに到達できるようにする方法。

インポート文が Paraglide JS として扱われるのは、Paraglide JS ファイルに解決される場合に限られます。`~/paraglide/messages.js` のように解析が認識できないエイリアスがあると、その先にある使用箇所はすべて検出されなくなります。実行時に未解決のインポート文に関する警告が出た場合や、検出された使用箇所が想定より少ない場合は、このガイドを参照してください。

## エイリアスの取得元を確認する [#alias-sources]

インポート文は、バンドラーを実行せずに、バンドラーと同じ方法で解決されます。エイリアスは次の取得元から、この順序で読み込まれます。

1. [`alias`](/docs/integrations/paraglide/reference/collect-context#alias) オプション。
2. ルートディレクトリまたはプロジェクトルートで最初に見つかった `vite.config.*`、`webpack.config.*`、または `rspack.config.*`。
3. `tsconfig.json` の `paths` と `package.json` の `imports`。

バンドラーの設定ファイルは、バンドラーごとに読み込み方が異なります。

* **Vite:** プロジェクト自体の Vite が設定を解決するため、プラグインが追加するエイリアス (SvelteKit の `$lib` など) やルートパス (`/src/a.js`) も機能します。
* **webpack と rspack:** 設定ファイルがインポートされます。完全一致 (`name$`) とワイルドカード (`"@/*"`) のエイリアスに対応しています。TypeScript の設定ファイルを使う場合は、TypeScript を実行できるバージョンの Node.js が必要です。

Next.js、Nuxt、Astro の設定ファイルは読み込まれません。これらのエイリアスは `tsconfig.json` から取得されます。

## エイリアスを宣言する [#declare-alias]

どの設定ファイルにも宣言されていないエイリアスを追加したり、既存のエイリアスを上書きしたりできます。独自に指定したエイリアスは、設定ファイルのエイリアスよりも優先して照合されます。

<Tabs items={['CLI', 'Library']}>
  <Tab value="CLI">
    ```bash
    # 相対パスの置換先はプロジェクトルートを基準に解決されます
    npx paraglide-context --alias ~=./src --alias @ui=./packages/ui/src
    ```
  </Tab>

  <Tab value="Library">
    ```ts
    import path from 'node:path';
    import { collectContext } from '@generaltranslation/paraglide-js/compiler';

    await collectContext({
      // 置換先は絶対パスで指定します
      alias: { '~': path.resolve('src') },
    });
    ```
  </Tab>
</Tabs>

## 未解決のインポート文を修正する [#unresolved]

バンドラーの設定を読み込めなかった場合、実行は警告とともに終了し、解決できなかったインポート文が一覧表示されます。これらは宣言されていないエイリアスである可能性があります。それぞれについて、次の手順を行ってください。

1. `--alias` で宣言するか、`tsconfig.json` の `paths` に追加します。
2. `paraglide-context --verbose` を再度実行します。サマリーに、エイリアスの読み込み元となった設定が表示されます。

バンドラーの設定は存在するものの、ビルド外で読み込むとエラーになる場合は、`--no-bundler-config` でその設定をスキップし、エイリアスを手動で宣言してください。

## 別のバンドラーの設定を読み取る [#bundler-config]

デフォルトでは対応していない設定ファイルからエイリアスを読み取るには、[`BundlerConfig`](/docs/integrations/paraglide/reference/extension-api#bundler-configs) を追加します。webpack 形式のファイルであれば、[`webpackLikeConfig`](/docs/integrations/paraglide/reference/extension-api#bundler-configs) を使ってその `BundlerConfig` を作成できます：

```ts
import {
  collectContext,
  defaultBundlerConfigs,
  webpackLikeConfig,
} from '@generaltranslation/paraglide-js/compiler';

await collectContext({
  bundlerConfigs: [
    ...defaultBundlerConfigs,
    // webpack.prod.js、.mjs、.ts などから resolve.alias を読み取ります
    webpackLikeConfig('webpack (production)', 'webpack.prod'),
  ],
});
```

その他の形式の場合は、`read` 関数を独自に記述してください：

```ts
import { readFile } from 'node:fs/promises';
import {
  collectContext,
  defaultBundlerConfigs,
  type BundlerConfig,
} from '@generaltranslation/paraglide-js/compiler';

const aliasFile: BundlerConfig = {
  name: 'aliases.json',
  files: ['aliases.json'], // ルートとプロジェクトルートから検索されます
  async read(file) {
    // { "~": "/app/src" }
    const entries = Object.entries(JSON.parse(await readFile(file, 'utf8')));

    return {
      aliases: entries.map(([find, replacement]) => ({
        find,
        replacement: String(replacement),
      })),
    };
  },
};

await collectContext({ bundlerConfigs: [...defaultBundlerConfigs, aliasFile] });
```

読み込まれるのは最初に見つかった設定のみです。`read` が失敗した場合は警告が出力され、その設定はスキップされます。

## 別のリゾルバーを使用する [#custom-resolver]

インポートの解決処理を完全に置き換えるには、コレクターを自分で作成し、[`Resolver`](/docs/integrations/paraglide/reference/extension-api#resolvers) を渡します。`Resolver` は、インポートの解決先となるファイルを返す関数です (解決先がない場合は何も返しません) 。

```ts
import {
  createCollector,
  nodeResolver,
} from '@generaltranslation/paraglide-js/compiler';

const fallback = nodeResolver();

const collector = createCollector(
  { include: ['src'] },
  {
    root: process.cwd(),
    logger: console,
    resolver: async (specifier, importer) =>
      specifier === 'virtual:messages'
        ? '/app/src/paraglide/messages.js'
        : fallback(specifier, importer),
  }
);

await collector.scanAll(); // 解析
await collector.write(); // メタデータファイルを書き出す
```

## 使い分け [#what-to-use]

* **`--alias` または `alias`:** どの設定にも宣言されていない少数のエイリアス。
* **`tsconfig.json` の `paths`:** エディターや型チェッカーにも認識させたいエイリアス。
* **`BundlerConfig`:** 別のバンドラーの設定ファイルですでに定義されているエイリアス。
* **`Resolver`:** 仮想モジュールなど、エイリアスでは表現できない解決処理。

## Next steps

- /docs/integrations/paraglide/guides/adding-file-formats

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.