# General Translation Integrations: collectContext
URL: https://generaltranslation.com/zh/docs/integrations/paraglide/reference/collect-context.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 分析应用，从代码中提取 Paraglide JS 消息的源代码上下文并写入。collectContext 的 API 参考。

请从 `@generaltranslation/paraglide-js/compiler` 导入。该软件包的根入口不导出任何内容。[`paraglide-context`](/docs/integrations/paraglide/reference/paraglide-context) 命令会根据其命令行选项构建参数选项，并以此调用该函数。

## 概览 [#overview]

```ts
function collectContext(options?: CollectContextOptions): Promise<void>;
```

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

await collectContext({ root: './apps/web', include: ['src'] });
```

元数据文件写入完成后，该 Promise 即兑现。若因某些问题跳过了某个文件、某种格式或某个目录，这些问题会通过 [`logger.warn`](#logger) 报告，而不会导致 Promise 被拒绝。仅当元数据文件无法写入时，Promise 才会被拒绝。

## 选项 [#options]

路径均相对于项目根目录：即 [`root`](#root) 所在目录或其上层目录中最近的 `package.json` 所在位置。

| 选项                                   | 描述                                 | 类型                           | 可选 | 默认                                           |
| ------------------------------------ | ---------------------------------- | ---------------------------- | -- | -------------------------------------------- |
| [`root`](#root)                      | 项目本身，或项目中的某个目录。                    | `string`                     | 是  | 工作目录                                         |
| [`include`](#include)                | 要分析的路径或 glob 模式。                   | `string[]`                   | 是  | 整个项目                                         |
| [`exclude`](#exclude)                | 要跳过的路径或 glob 模式。                   | `string[]`                   | 是  | `DEFAULT_EXCLUDE`                            |
| [`radius`](#radius)                  | 每处用法上下各保留的上下文行数。                   | `number`                     | 是  | `10`                                         |
| [`outdirs`](#outdirs)                | 无需验证即可直接使用的 Paraglide JS 输出目录。     | `string[]`                   | 是  | 自动检测                                         |
| [`inlangProjects`](#inlang-projects) | 需为其消息生成元数据文件的 inlang 项目目录。         | `string[]`                   | 是  | 自动检测                                         |
| [`autoImports`](#auto-imports)       | 无需导入即可使用的名称。                       | `false \| AutoImportOptions` | 是  | 自动检测                                         |
| [`alias`](#alias)                    | 导入别名。                              | `AliasOption`                | 是  | —                                            |
| [`bundlerConfigs`](#bundler-configs) | 用于读取别名的打包工具配置。                     | `BundlerConfig[]`            | 是  | `defaultBundlerConfigs`                      |
| [`rootDirectory`](#root-directory)   | `/src/a.js` 这类根路径的解析起点。            | `string`                     | 是  | 打包工具配置中的根目录                                  |
| [`conditions`](#conditions)          | 软件包导出条件。                           | `string[]`                   | 是  | `["import", "module", "browser", "default"]` |
| [`targets`](#targets)                | 哪些内容视为 Paraglide JS。               | `ParaglideTarget[]`          | 是  | `defaultTargets`                             |
| [`languages`](#languages)            | JavaScript 和 TypeScript 以外的其他文件格式。 | `SourceLanguage[]`           | 是  | `defaultLanguages`                           |
| [`logger`](#logger)                  | 接收警告和汇总信息。                         | `CollectorLogger`            | 是  | 警告输出到 `console.warn`                         |

## `root` [#root]

**类型** `string` · **可选** · **默认** 当前工作目录

项目本身或项目中的某个目录，例如 monorepo 中的某个应用。系统会在此目录和项目根目录中查找打包工具配置；inlang 项目则从此目录开始逐级向上查找，直至 monorepo 根目录。

## `include` [#include]

**类型** `string[]` · **可选** · **默认** 整个项目

要分析的路径或 glob 模式。项目之外的路径只要列出 (如 `../shared`) ，同样会被分析。不存在的条目会以警告形式报告。

无论 `include` 中列出了什么，以下内容始终会被跳过：`node_modules`、构建产物和框架输出，以及被 `.gitignore` 忽略的文件。

## `exclude` [#exclude]

**类型** `string[]` · **可选** · **默认** `DEFAULT_EXCLUDE`

要跳过的路径或 glob 模式。设置后将覆盖默认值 (默认会跳过测试文件和工具配置文件) ：

```ts
import { DEFAULT_EXCLUDE } from '@generaltranslation/paraglide-js/compiler';

// *.config.?(c|m)[jt]s, **/*.{test,spec}.?(c|m)[jt]s?(x), **/__tests__/**,
// **/__mocks__/**, test/**, tests/**, e2e/**, cypress/**, playwright/**
await collectContext({ exclude: [...DEFAULT_EXCLUDE, 'src/stories/**'] });
```

## `radius` [#radius]

**类型** `number` · **可选** · **默认** `10`

每处使用位置上下各保留的源代码行数，分别作为其[元数据条目](/docs/integrations/paraglide/reference/metadata-files#format)中的 `before` 和 `after`。

## `outdirs` [#outdirs]

**类型** `string[]` · **可选** · **默认** 自动检测

指定 Paraglide JS 输出目录，直接使用而不进行验证。未设置此选项时，系统会自动[检测](/docs/integrations/paraglide/reference/usage-detection#outdirs)输出目录。如果出现警告提示某个目录未被用作输出目录，请设置此选项。

## `inlangProjects` [#inlang-projects]

**类型** `string[]` · **可选** · **默认** 自动检测

inlang 项目目录，例如 `project.inlang`。这些项目的基础区域设置下，每个消息文件都会生成一个对应的元数据文件。设置此项后，将不再[为每个输出目录查找所属项目](/docs/integrations/paraglide/reference/usage-detection#inlang-projects)。

## `autoImports` [#auto-imports]

**类型** `false | AutoImportOptions` · **可选** · **默认** 自动检测

应用中无需显式导入即可直接使用的名称。每个键是一个名称，对应的值是导出该名称的模块 (路径相对于项目根目录) ；若模块导出时使用了其他名称，则值为 `{ from, export }`。

```ts
await collectContext({
  autoImports: {
    m: './src/paraglide/messages.js',
    t: { from: './src/i18n.js', export: 'translate' },
  },
});
```

即使不设置此选项，unplugin-auto-import、unplugin-vue-components 和 Nuxt 的自动导入也会从它们生成的 `.d.ts` 文件中读取。设为 `false` 会同时关闭这项自动检测和此选项。

## `alias` [#alias]

**类型** `AliasOption` · **可选** · **默认** —

导入别名，类似于打包工具的 `resolve.alias`。可以是一个将名称映射到替换值的对象，也可以是由 `{ find, replacement, exact? }` 组成的列表，其中 `find` 为字符串或 `RegExp`。这些别名会优先于打包工具配置中的别名进行匹配。

```ts
await collectContext({
  alias: [
    { find: '~', replacement: '/app/src' }, // ~ 和 ~/…
    { find: 'config', replacement: '/app/src/config.ts', exact: true }, // 仅精确匹配 config
    { find: /^@ui\/(.*)$/, replacement: '/app/packages/ui/src/$1' },
  ],
});
```

 (参见[解析导入语句](/docs/integrations/paraglide/guides/resolving-imports)。)

## `bundlerConfigs` [#bundler-configs]

**类型** `BundlerConfig[]` · **可选** · **默认** `defaultBundlerConfigs`

从中读取导入别名的打包工具配置，默认包括 Vite、webpack 和 rspack。仅读取找到的第一个配置文件。设为 `[]` 则不读取任何配置。如需添加，请参阅 [`BundlerConfig`](/docs/integrations/paraglide/reference/extension-api#bundler-configs)。

## `rootDirectory` [#root-directory]

**类型** `string` · **可选** · **默认** 打包工具配置中的根目录

解析 `/src/a.js` 这类根路径时所基于的目录，类似 Vite 的 `root`。该值由 Vite 配置提供；若没有 Vite 配置，根路径将按文件系统路径解析。

## `conditions` [#conditions]

**类型** `string[]` · **可选** · **默认** `["import", "module", "browser", "default"]`

从软件包的 `exports` 和 `imports` 中选取条目时所依据的条件。

## `targets` [#targets]

**类型** `ParaglideTarget[]` · **可选** · **默认** `defaultTargets`

指定哪些已解析的文件属于 Paraglide JS，以及这些文件中的每个导出分别是什么 (参见 [Targets](/docs/integrations/paraglide/reference/extension-api#targets)) 。

## `languages` [#languages]

**类型** `SourceLanguage[]` · **可选** · **默认** `defaultLanguages`

除 JavaScript、TypeScript 和 JSX 外，还需要分析的文件格式。 (参见[支持的文件格式](/docs/integrations/paraglide/reference/file-formats)和[添加文件格式](/docs/integrations/paraglide/guides/adding-file-formats)。)

## `logger` [#logger]

**类型** `CollectorLogger` · **可选** · **默认** 将警告输出到 `console.warn`

一个包含 `warn(message)` 和 `info(message)` 方法的对象。警告用于报告哪些内容被跳过。`info` 会接收摘要信息，以及读取别名时所依据的配置；默认 logger 会忽略这些信息。

```ts
await collectContext({ logger: console }); // 输出警告和摘要
```

## 示例 [#example]

在翻译前，收集 monorepo 中某个应用 (包括其依赖的共享软件包) 的上下文：

```ts title="scripts/collect-context.ts"
import {
  collectContext,
  DEFAULT_EXCLUDE,
} from '@generaltranslation/paraglide-js/compiler';

await collectContext({
  root: './apps/web',
  include: ['src', '../../packages/ui/src'],
  exclude: [...DEFAULT_EXCLUDE, '**/*.stories.tsx'],
  radius: 5,
  logger: console,
});
```

## Sitemap

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