# General Translation Integrations: collectContext
URL: https://generaltranslation.com/en-US/docs/integrations/paraglide/reference/collect-context.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Analyze an app and write the source code context of its Paraglide JS messages from code. API reference for collectContext.

Import it from `@generaltranslation/paraglide-js/compiler`. The package root exports nothing. The [`paraglide-context`](/docs/integrations/paraglide/reference/paraglide-context) command calls this function with options built from its flags.

## Overview [#overview]

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

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

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

The promise resolves once the metadata files are written. Problems that skip a file, a format, or a directory are reported through [`logger.warn`](#logger) and do not reject it. It rejects when a metadata file cannot be written.

## Options [#options]

Paths are relative to the project root: the nearest `package.json` at or above [`root`](#root).

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`root`](#root) | The project, or a directory in it. | `string` | Yes | Working directory |
| [`include`](#include) | Paths or globs to analyze. | `string[]` | Yes | The whole project |
| [`exclude`](#exclude) | Paths or globs to skip. | `string[]` | Yes | `DEFAULT_EXCLUDE` |
| [`radius`](#radius) | Lines of context above and below each usage. | `number` | Yes | `10` |
| [`outdirs`](#outdirs) | Paraglide JS output directories to use without verification. | `string[]` | Yes | Detected |
| [`inlangProjects`](#inlang-projects) | inlang project directories whose messages get metadata files. | `string[]` | Yes | Detected |
| [`autoImports`](#auto-imports) | Names used without an import. | `false \| AutoImportOptions` | Yes | Detected |
| [`alias`](#alias) | Import aliases. | `AliasOption` | Yes | — |
| [`bundlerConfigs`](#bundler-configs) | Bundler configs to read aliases from. | `BundlerConfig[]` | Yes | `defaultBundlerConfigs` |
| [`rootDirectory`](#root-directory) | Where root paths such as `/src/a.js` resolve from. | `string` | Yes | The bundler config's root |
| [`conditions`](#conditions) | Package export conditions. | `string[]` | Yes | `["import", "module", "browser", "default"]` |
| [`targets`](#targets) | What counts as Paraglide JS. | `ParaglideTarget[]` | Yes | `defaultTargets` |
| [`languages`](#languages) | File formats besides JavaScript and TypeScript. | `SourceLanguage[]` | Yes | `defaultLanguages` |
| [`logger`](#logger) | Receives warnings and the summary. | `CollectorLogger` | Yes | Warnings to `console.warn` |

## `root` [#root]

**Type** `string` · **Optional** · **Default** working directory

The project, or a directory in it, such as one app of a monorepo. Bundler configs are looked for here and in the project root. inlang projects are looked for from here up to the monorepo root.

## `include` [#include]

**Type** `string[]` · **Optional** · **Default** the whole project

Paths or globs to analyze. A path outside the project is analyzed when it is listed (`../shared`). An entry that does not exist is reported in a warning.

Always skipped, whatever `include` lists: `node_modules`, build and framework output, and files a `.gitignore` ignores.

## `exclude` [#exclude]

**Type** `string[]` · **Optional** · **Default** `DEFAULT_EXCLUDE`

Paths or globs to skip. Setting it replaces the default, which skips tests and tool configs:

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

**Type** `number` · **Optional** · **Default** `10`

Lines of source code kept above and below each usage, as the `before` and `after` of its [metadata entry](/docs/integrations/paraglide/reference/metadata-files#format).

## `outdirs` [#outdirs]

**Type** `string[]` · **Optional** · **Default** detected

Paraglide JS output directories to use without verifying them. Output directories are [detected](/docs/integrations/paraglide/reference/usage-detection#outdirs) without this option. Set it when a warning says a directory was not used as one.

## `inlangProjects` [#inlang-projects]

**Type** `string[]` · **Optional** · **Default** detected

inlang project directories, such as `project.inlang`. Each message file of their base locale gets a metadata file. Setting it replaces the [search for each output directory's project](/docs/integrations/paraglide/reference/usage-detection#inlang-projects).

## `autoImports` [#auto-imports]

**Type** `false | AutoImportOptions` · **Optional** · **Default** detected

Names the app uses without importing them. Each key is a name; its value is the module that exports it, relative to the project root, or `{ from, export }` when the export has another name.

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

Auto-imports of unplugin-auto-import, unplugin-vue-components, and Nuxt are read from their generated `.d.ts` files without this option. `false` turns off both the detection and the option.

## `alias` [#alias]

**Type** `AliasOption` · **Optional** · **Default** —

Import aliases, like a bundler's `resolve.alias`. Either an object from name to replacement, or a list of `{ find, replacement, exact? }` where `find` is a string or a `RegExp`. They are matched before the aliases of a bundler config.

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

(See [Resolving imports](/docs/integrations/paraglide/guides/resolving-imports)).

## `bundlerConfigs` [#bundler-configs]

**Type** `BundlerConfig[]` · **Optional** · **Default** `defaultBundlerConfigs`

Bundler configs to read import aliases from: Vite, webpack, and rspack by default. Only the first config file found is read. `[]` reads none. To add one, see [`BundlerConfig`](/docs/integrations/paraglide/reference/extension-api#bundler-configs).

## `rootDirectory` [#root-directory]

**Type** `string` · **Optional** · **Default** the bundler config's root

The directory that root paths such as `/src/a.js` resolve from, like Vite's `root`. A Vite config provides it. Without one, root paths are resolved as file system paths.

## `conditions` [#conditions]

**Type** `string[]` · **Optional** · **Default** `["import", "module", "browser", "default"]`

The conditions used to pick an entry of a package's `exports` and `imports`.

## `targets` [#targets]

**Type** `ParaglideTarget[]` · **Optional** · **Default** `defaultTargets`

Which resolved files belong to Paraglide JS and what each of their exports is. (See [Targets](/docs/integrations/paraglide/reference/extension-api#targets)).

## `languages` [#languages]

**Type** `SourceLanguage[]` · **Optional** · **Default** `defaultLanguages`

The file formats analyzed besides JavaScript, TypeScript, and JSX. (See [Supported file formats](/docs/integrations/paraglide/reference/file-formats) and [Adding file formats](/docs/integrations/paraglide/guides/adding-file-formats)).

## `logger` [#logger]

**Type** `CollectorLogger` · **Optional** · **Default** warnings to `console.warn`

An object with `warn(message)` and `info(message)`. Warnings report what was skipped. `info` receives the summary and the config the aliases were read from; the default logger drops it.

```ts
await collectContext({ logger: console }); // warnings and the summary
```

## Example [#example]

Collect the context of one app in a monorepo, including a shared package, before translating:

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