# General Translation Integrations: collectContext
URL: https://generaltranslation.com/en-GB/docs/integrations/paraglide/reference/collect-context.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Analyse 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 analyse.                                    | `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&#39;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 analyse. A path outside the project is analysed 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&#39;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&#39;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&#39;s root

The directory that root paths such as `/src/a.js` resolve from, like Vite&#39;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&#39;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 analysed 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.