# General Translation Integrations: Usage detection
URL: https://generaltranslation.com/en-US/docs/integrations/paraglide/reference/usage-detection.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How source files are selected, imports are resolved, and Paraglide JS message usages are found. Reference for usage detection.

A run of [`paraglide-context`](/docs/integrations/paraglide/reference/paraglide-context) or [`collectContext`](/docs/integrations/paraglide/reference/collect-context) reads the app's source and never runs its bundler. It supports Paraglide JS 1, 2, and 3 on Node.js 20 or later.

## How it works [#how-it-works]

| Step | What it decides |
| --- | --- |
| [Files](#files) | Which source files are analyzed. |
| [Imports](#imports) | Which imports end in a Paraglide JS file. |
| [Output directories](#outdirs) | Which directories hold Paraglide JS output. |
| [inlang projects](#inlang-projects) | Which message files get a metadata file. |
| [Usages](#usages) | Where each message is used. |

## Files [#files]

The analyzed files are those of [`include`](/docs/integrations/paraglide/reference/collect-context#include), minus [`exclude`](/docs/integrations/paraglide/reference/collect-context#exclude), `node_modules`, build and framework output, and anything a `.gitignore` ignores. Files outside the project are analyzed when `include` lists them (`../shared`).

A file that does not parse is skipped with a warning. For formats other than JavaScript, TypeScript, and JSX, see [Supported file formats](/docs/integrations/paraglide/reference/file-formats).

## Imports [#imports]

Imports are never matched by their text. Each one is resolved, followed through re-exports (ESM and CommonJS), and counted only if it ends in a Paraglide JS file.

They are resolved like the app's bundler would resolve them, without running it. Aliases come from, in order:

1. The [`alias`](/docs/integrations/paraglide/reference/collect-context#alias) option.
2. The first `vite.config.*`, `webpack.config.*`, or `rspack.config.*` found. Vite's is resolved by the project's own Vite, so plugin aliases (SvelteKit's `$lib`) and root paths (`/src/a.js`) work. A webpack or rspack config is imported, so a TypeScript config needs a Node.js version that runs TypeScript. Its `name$` and wildcard (`"@/*"`) aliases work.
3. `paths` in `tsconfig.json` and `imports` in `package.json`.

When no bundler config could be read, the imports that did not resolve are listed in a warning, since they may be undeclared aliases. (See [Resolving imports](/docs/integrations/paraglide/guides/resolving-imports)).

### Auto-imports

Names used without an import are read from the `.d.ts` files of unplugin-auto-import, unplugin-vue-components, and Nuxt. Declare others with [`autoImports`](/docs/integrations/paraglide/reference/collect-context#auto-imports).

## Output directories [#outdirs]

Paraglide JS output directories are detected, so several Paraglide JS projects in one app need no setup. A directory counts when it holds exactly what the installed Paraglide JS generates, on disk or as virtual modules. For Paraglide JS 1, it counts when it has the same structure.

A directory that looks like output but fails the check is skipped with a warning. List it in [`outdirs`](/docs/integrations/paraglide/reference/collect-context#outdirs) to use it anyway. When no output directory is found, a warning says that no usages can be recorded.

## inlang projects [#inlang-projects]

Each output directory is paired with one inlang project, whose base-locale message files get the metadata. The project is, in order:

1. The one the output directory's `README.md` names as the project it was compiled from.
2. The only `*.inlang` directory between [`root`](/docs/integrations/paraglide/reference/collect-context#root) and the monorepo root.
3. Of several such directories, the one that defines the most of the output directory's messages.

[`inlangProjects`](/docs/integrations/paraglide/reference/collect-context#inlang-projects) replaces that search. An output directory with no project gets a warning, and its messages get no metadata file.

## Usages [#usages]

Values are tracked with typescript-eslint's scope analysis through:

- Aliases (`const t = m`), destructuring, and reassignment
- Object spreads
- Function arguments and parameter defaults
- Component props, across modules and from templates
- Computed keys (`m["a"]`, `m[c ? "a" : "b"]`)

A message counts as used wherever it is:

| Usage | Example |
| --- | --- |
| Called | `m.tos()` |
| Called through one of its methods | `m.tos.parts()` |
| Referenced without a call | `message={m.tos}` |

Usages of messages that are missing from the generated catalog are listed in a warning.

By default, the Paraglide JS files are `messages.js`, the modules in `messages/`, `runtime.js`, `server.js`, `registry.js`, and Paraglide's framework adapter packages. (See [Targets](/docs/integrations/paraglide/reference/extension-api#targets)).

## Limits [#limits]

- **Aliases:** a bundler config gives only its aliases, and Vite's root, not its plugins' virtual modules. Next.js, Nuxt, and Astro configs are not read; their aliases come from `tsconfig.json`.
- **Other targets:** usages of runtime functions and adapter components are analyzed but not written. Only messages have a key to write under.
- **Value flow:** tracking stops at return values, React context, `provide`/`inject`, arrays, and objects assigned later. A read after an unconditional reassignment sees only the new value. Loops are not modeled.
- **Props:** props are followed into Svelte, Vue, and Astro components, but not into components registered with `app.component()` or rendered with `<svelte:component this={X}>`.
- **Computed keys:** a key with more than 16 alternatives becomes `*`, which matches no single message.
- **CommonJS:** exports below a module's top level are not followed.
- **Broken Astro files:** the rest of an element after an unclosed `{` is lost. With only `@astrojs/compiler` (Astro 6 and earlier), the rest of the line is lost.

## Sitemap

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