# General Translation Integrations: 解析导入语句
URL: https://generaltranslation.com/zh/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 配置，Node.js 版本需支持运行 TypeScript。

不会读取 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)。[`webpackLikeConfig`](/docs/integrations/paraglide/reference/extension-api#bundler-configs) 可为 webpack 格式的配置文件创建 `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)：该函数返回导入解析到的目标文件，若无法解析则不返回任何内容。

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