# General Translation Integrations: Разрешение инструкций импорта
URL: https://generaltranslation.com/ru/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. `paths` в `tsconfig.json` и `imports` в `package.json`.

Конфигурации сборщиков считываются по-разному:

* **Vite:** конфигурацию разрешает Vite, установленный в вашем проекте, поэтому работают алиасы, добавляемые плагинами (`$lib` в SvelteKit), и корневые пути (`/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` или добавьте его в `paths` в `tsconfig.json`.
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) создаёт такой `BundlerConfig` для файла в формате webpack:

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

await collectContext({
  bundlerConfigs: [
    ...defaultBundlerConfigs,
    // Читает resolve.alias из webpack.prod.js, .mjs, .ts, …
    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`:** несколько алиасов, которые не объявлены ни в одной конфигурации.
* **`paths` в `tsconfig.json`:** алиасы, о которых должны знать также ваш редактор и средство проверки типов.
* **`BundlerConfig`:** алиасы, которые уже заданы в файле конфигурации другого сборщика.
* **`Resolver`:** разрешение, которое нельзя описать алиасами, например виртуальные модули.

## Next steps

- /docs/integrations/paraglide/guides/adding-file-formats

## Sitemap

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