# General Translation Integrations: API расширений URL: https://generaltranslation.com/ru/docs/integrations/paraglide/reference/extension-api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Настройте, что считается Paraglide JS, какие форматы файлов анализируются и как разрешаются инструкции импорта. Справочник API по целям, языкам, конфигурациям сборщиков и резолверам. Всё, что описано на этой странице, экспортируется из `@generaltranslation/paraglide-js/compiler` и передаётся в [`collectContext`](/docs/integrations/paraglide/reference/collect-context) через его варианты. Сам анализ (граф модулей, места использования и рендеринг) выполняется внутри и наружу не предоставляется. ## Обзор [#overview] | API | Описание | | ----------------------------------- | ----------------------------------------------------------------------------- | | [Цели](#targets) | Какие разрешённые файлы относятся к Paraglide JS и что они экспортируют. | | [Языки](#languages) | Форматы файлов, которые инструменты фреймворка преобразуют в TypeScript. | | [Конфигурации сборщика](#bundler-configs) | Файлы конфигурации, из которых считываются алиасы импортов. | | [Резолверы](#resolvers) | Функции, разрешающие импорт в файл, и коллектор, к которому они подключаются. | ## Цели [#targets] Цель определяет, какие разрешённые файлы относятся к Paraglide JS и чем является каждый из их экспортов. Цели задаются вариантом [`targets`](/docs/integrations/paraglide/reference/collect-context#targets). Если файлу соответствует несколько целей, применяется последняя. ```ts type ParaglideTarget = { name: string; // метка для использований, например «message» matches(file: TargetFile): boolean; // Верните undefined, чтобы экспорт не отслеживался. exportSymbol(exportName: string, file: TargetFile): SymbolSpec | undefined; }; type TargetFile = { file: string; // абсолютный, с прямыми слешами (/) outdir: string | undefined; // выходной каталог, в котором находится файл outdirPath: string | undefined; // относительно outdir, например «messages.js» }; type SymbolSpec = | { type: 'namespace'; member(name: string): SymbolSpec | undefined } // methods: методы, вызовы которых тоже учитываются, например .parts() у messages | { type: 'value'; name: string; methods?: readonly string[] }; ``` | Экспорт | Описание | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultTargets` | `messagesTarget`, `runtimeTarget`, `serverTarget`, `registryTarget` и `adapterTargets`. | | `messagesTarget` | `messages.js` с пространством имён `m` и все модули в `messages/`. Имя — `message`. | | `runtimeTarget`, `serverTarget`, `registryTarget` | Все экспорты `runtime.js`, `server.js` и `registry.js`. | | `adapterTargets` | Адаптеры Paraglide для фреймворков: `@inlang/paraglide-js-react`, `-solid`, `-svelte` и `-vue`, а также `@inlang/paraglide-sveltekit`, `@inlang/paraglide-next` и `@inlang/paraglide-astro` из Paraglide JS 1. | | `defineTarget(target)` | Возвращает цель без изменений с типом `ParaglideTarget`. | | `generatedFileTarget(name, outdirPath)` | Файл в выходном каталоге; отслеживаются все его экспорты. | | `packageTarget(name, packageName)` | Установленный пакет; отслеживаются его именованные экспорты. | *Примечание: в [файлы метаданных](/docs/integrations/paraglide/reference/metadata-files) записываются только использования цели `message`. Использования других целей тоже анализируются, но у них нет ключа сообщения, под которым их можно было бы записать.* ## Языки [#languages] Язык преобразует файл определённого формата в один модуль JavaScript или TypeScript с помощью собственных инструментов фреймворка. Языки передаются через вариант [`languages`](/docs/integrations/paraglide/reference/collect-context#languages) (см. [Добавление форматов файлов](/docs/integrations/paraglide/guides/adding-file-formats)). ```ts type SourceLanguage = { name: string; extensions: readonly string[]; // Обязательно, чтобы закрепить за языком расширения скриптов, например компоненты Angular в файлах .ts. detect?(source: string, file: string): boolean; // Пакеты, которые нужны ему в приложении; если какого-то нет, он указывается по имени. requires?: readonly string[]; // Пакет, вместе с которым устанавливается обязательный: { svelte2tsx: 'svelte-check' }. installedWith?: Readonly>; // Верните undefined, если инструменты не установлены; выбросьте исключение, если они // отклоняют файл. В обоих случаях файл пропускается. generate( source: string, file: string, context: LanguageContext ): GeneratedSource | undefined | Promise; }; type LanguageContext = { // Импортирует пакет, установленный в приложении; undefined, если он не установлен. load(specifier: string): Promise; }; type ParseLang = 'js' | 'jsx' | 'ts' | 'tsx'; ``` ### Сгенерированный источник `generate` возвращает `GeneratedSource`. Код без сопоставления никогда не считается использованием. | Поле | Описание | Тип | Необязательный | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | -------------- | | `code` | Файл в виде единого модуля. | `string` | Нет | | `lang` | Язык `code`. | `ParseLang` | Нет | | `mappings` | Из какого места файла взят каждый диапазон `code`. | `Mapping[]` | Нет | | `elements` | Разметка файла, в которой каждое использование помечено своим элементом. Метка не записывается в файлы метаданных. | `SourceElement[]` | Да | | `scripts` | Отдельные модули внутри файла, например клиентские скрипты страницы Astro, каждый в виде `GeneratedScript`: `{ code, lang, mappings }`. | `GeneratedScript[]` | Да | | `componentFields` | Классы, к полям которых шаблон обращается без объявления, как это происходит в шаблонах Angular. Каждый из них — `ComponentFields`: `{ specifier, className?, range? }`. | `ComponentFields[]` | Да | | `scopeObjects` | Объекты, члены которых разрешаются так же, как имена модуля, например `__VLS_ctx` во Vue. | `string[]` | Да | | `props` | Где компонент считывает пропсы, передаваемые в местах его вызова: `{ calls?, members?, variables?, undeclared? }`. | `object` | Да | | `componentInstances` | Как сгенерированный код выполняет рендеринг импортированных компонентов помимо JSX: `{ via: 'new' \| 'call', path }`. | `object` | Да | ### Сопоставления и элементы ```ts // Сгенерированный диапазон [generated, generated + length) соответствует // исходному диапазону [source, source + sourceLength). По умолчанию sourceLength равно length. type Mapping = { generated: number; source: number; length: number; sourceLength?: number; }; // Из source map версии 3 (например, от svelte2tsx): карта в виде объекта // (EncodedSourceMap из @jridgewell/trace-mapping) или JSON-строки. function mappingsFromSourceMap( map: EncodedSourceMap | string, generatedCode: string, sourceCode: string ): Mapping[]; // Из сопоставлений виртуального кода Volar: // @vue/language-core, @mdx-js/language-service, Glint. // Передавайте сопоставления Volar без изменений. function mappingsFromVolar( mappings: readonly { sourceOffsets: readonly number[]; generatedOffsets: readonly number[]; lengths: readonly number[]; generatedLengths?: readonly number[]; }[] ): Mapping[]; ``` `SourceElement` описывает один элемент разметки со смещениями в источнике: `name`, `start`, `end`, `nameStart`, `nameEnd`, `openEnd`, `component` и `attributes` (каждый атрибут представлен как `{ name, start, end }`, где диапазон охватывает значение атрибута). ### Встроенные языки `defaultLanguages` содержит в следующем порядке: `vueLanguage`, `svelteLanguage`, `astroLanguage`, `mdxLanguage`, `markdownLanguage`, `angularComponentLanguage`, `angularTemplateLanguage`, `analogLanguage`, `markoLanguage` и `emberLanguage`. Каждый из них также экспортируется отдельно. Файлы и инструменты для каждого языка описаны в разделе [Поддерживаемые форматы файлов](/docs/integrations/paraglide/reference/file-formats). ## Конфигурации сборщика [#bundler-configs] Конфигурация сборщика позволяет считать алиасы импортов из файла конфигурации, не запуская сам сборщик. Передайте их через вариант [`bundlerConfigs`](/docs/integrations/paraglide/reference/collect-context#bundler-configs). (См. [Разрешение импортов](/docs/integrations/paraglide/guides/resolving-imports#bundler-config).) ```ts type BundlerConfig = { name: string; files: readonly string[]; // возможные имена файлов конфигурации // file — абсолютный путь. О сбое (возвращённом или выброшенном) выводится // сообщение, а конфигурация пропускается. read( file: string, context: ConfigContext ): Promise; }; type ImportResolution = { aliases: readonly ImportAlias[]; rootDirectory?: string; // относительно чего разрешается /src/a.js (root в Vite) }; type ConfigFailure = { error: string }; type ConfigContext = { // Импортирует пакет из приложения; undefined, если он не установлен. load(specifier: string): Promise; }; type ImportAlias = { find: string | RegExp; // строка совпадает с find и find/… replacement: string; exact?: boolean; // строка совпадает только с самим find (name$ в webpack) }; type AliasOption = Readonly> | readonly ImportAlias[]; ``` | Экспорт | Описание | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultBundlerConfigs` | `viteConfig`, `webpackConfig` и `rspackConfig` — именно в таком порядке. | | `viteConfig` | Читает `vite.config.*` с помощью Vite, установленного в самом приложении. Возвращает разрешённые алиасы и корневой каталог Vite. | | `webpackConfig`, `rspackConfig` | Импортируют `webpack.config.*` и `rspack.config.*` и читают `resolve.alias`. | | `webpackLikeConfig(name, baseName)` | Создаёт конфигурацию сборщика для файла в формате webpack с именем `baseName` и расширением `.js`, `.mjs`, `.ts`, `.cjs`, `.mts` или `.cts`. | Конфигурация в формате webpack может экспортировать объект, функцию или список из них; если экспортирован список, используется его первый элемент. Функция вызывается с пустым `env` и `{ mode: 'production' }`. ## Резолверы [#resolvers] Резолвер возвращает файл, на который указывает импорт, или `undefined`. Чтобы использовать собственный резолвер, создайте коллектор, который оборачивает функция [`collectContext`](/docs/integrations/paraglide/reference/collect-context). (См. [Разрешение импортов](/docs/integrations/paraglide/guides/resolving-imports#custom-resolver).) ```ts type Resolver = ( specifier: string, importer: string ) => Promise; function createCollector( options: ParaglideContextOptions, environment: CollectorEnvironment ): ContextCollector; type CollectorEnvironment = { root: string; // проект или один из его каталогов logger: CollectorLogger; // { warn(message), info(message) } resolver: Resolver; }; ``` `ParaglideContextOptions` содержит варианты `collectContext`, не связанные с разрешением модулей: `include`, `exclude`, `targets`, `languages`, `inlangProjects`, `radius`, `outdirs` и `autoImports`. У возвращаемого `ContextCollector` вызовите `scanAll()`, чтобы проанализировать проект, а затем `write()`, чтобы записать файлы метаданных. | Экспорт | Описание | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nodeResolver(options?)` | Разрешает модули так же, как сборщик, но без самого сборщика: алиасы, `exports` и `imports` пакета, `paths` из ближайшего к каждому импортирующему файлу `tsconfig.json`, а также `./a.js` в `./a.ts`, как это делает TypeScript. Принимает `NodeResolverOptions`: `{ alias?, rootDirectory?, conditions? }`. | | `ProjectResolver` | Резолвер, который использует `collectContext`: сначала алиасы из конфигурации сборщика приложения, затем `nodeResolver`. | ```ts import { createCollector, ProjectResolver, } from '@generaltranslation/paraglide-js/compiler'; const environment = { root: process.cwd(), logger: console }; // ProjectResolverOptions: NodeResolverOptions и bundlerConfigs const resolver = new ProjectResolver({ alias: { '~': '/app/src' } }, environment); const collector = createCollector( { include: ['src'] }, { ...environment, resolver: resolver.resolve } ); await collector.scanAll(); await collector.write(); await resolver.warnUnresolved(); // выводит импорты, которые могут оказаться необъявленными алиасами ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.