# General Translation Integrations: API d’extension URL: https://generaltranslation.com/fr/docs/integrations/paraglide/reference/extension-api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Personnalisez ce qui est considéré comme du Paraglide JS, les formats de fichiers analysés et la manière dont les importations sont résolues. Référence de l’API pour les cibles, les langages, les configurations de bundler et les résolveurs. Tous les éléments de cette page sont exportés depuis `@generaltranslation/paraglide-js/compiler` et transmis à [`collectContext`](/docs/integrations/paraglide/reference/collect-context) via ses options. L’analyse proprement dite (graphe de modules, utilisations et rendu) reste interne. ## Vue d’ensemble [#overview] | API | Description | | --------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [Cibles](#targets) | Fichiers résolus qui appartiennent à Paraglide JS, et leurs exports. | | [Langages](#languages) | Formats de fichiers convertis en TypeScript par l’outillage d’un framework. | | [Configurations de bundler](#bundler-configs) | Fichiers de configuration dans lesquels sont lus les alias d’importation. | | [Résolveurs](#resolvers) | Fonctions qui résolvent une importation vers un fichier, et le collecteur auquel elles se branchent. | ## Cibles [#targets] Une cible indique quels fichiers résolus appartiennent à Paraglide JS et ce que représente chacun de leurs exports. Passez les cibles via l'option [`targets`](/docs/integrations/paraglide/reference/collect-context#targets). Lorsque plusieurs cibles correspondent à un même fichier, c'est la dernière qui l'emporte. ```ts type ParaglideTarget = { name: string; // libellé des utilisations, par exemple « message » matches(file: TargetFile): boolean; // Renvoyez undefined pour ne pas suivre un export. exportSymbol(exportName: string, file: TargetFile): SymbolSpec | undefined; }; type TargetFile = { file: string; // absolu, avec des barres obliques outdir: string | undefined; // le répertoire de sortie qui contient le fichier outdirPath: string | undefined; // relatif à outdir, par exemple « messages.js » }; type SymbolSpec = | { type: 'namespace'; member(name: string): SymbolSpec | undefined } // methods : méthodes dont les appels sont également comptabilisés, par exemple .parts() sur les messages | { type: 'value'; name: string; methods?: readonly string[] }; ``` | Export | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultTargets` | `messagesTarget`, `runtimeTarget`, `serverTarget`, `registryTarget` et `adapterTargets`. | | `messagesTarget` | `messages.js`, avec son espace de noms `m`, ainsi que chaque module de `messages/`. Nommée `message`. | | `runtimeTarget`, `serverTarget`, `registryTarget` | Tous les exports de `runtime.js`, `server.js` et `registry.js`. | | `adapterTargets` | Les adaptateurs de framework de Paraglide : `@inlang/paraglide-js-react`, `-solid`, `-svelte` et `-vue`, ainsi que `@inlang/paraglide-sveltekit`, `@inlang/paraglide-next` et `@inlang/paraglide-astro` de Paraglide JS 1. | | `defineTarget(target)` | Renvoie la cible telle quelle, typée en tant que `ParaglideTarget`. | | `generatedFileTarget(name, outdirPath)` | Un fichier du répertoire de sortie dont tous les exports sont suivis. | | `packageTarget(name, packageName)` | Un paquet installé dont les exports nommés sont suivis. | *Remarque : seules les utilisations de la cible `message` sont écrites dans les [fichiers de métadonnées](/docs/integrations/paraglide/reference/metadata-files). Les utilisations des autres cibles sont analysées, mais n’ont pas de clé de message sous laquelle être enregistrées.* ## Langages [#languages] Un langage convertit un format de fichier en un unique module JavaScript ou TypeScript à l’aide de l’outillage propre au framework. Transmettez les langages via l’option [`languages`](/docs/integrations/paraglide/reference/collect-context#languages) (voir [Ajouter des formats de fichier](/docs/integrations/paraglide/guides/adding-file-formats)). ```ts type SourceLanguage = { name: string; extensions: readonly string[]; // Obligatoire pour prendre en charge des extensions de script, comme les composants Angular dans des fichiers .ts. detect?(source: string, file: string): boolean; // Les paquets nécessaires dans l’application, indiqués par leur nom lorsque l’un d’eux est manquant. requires?: readonly string[]; // Le paquet qui installe un paquet requis : { svelte2tsx: 'svelte-check' }. installedWith?: Readonly>; // Renvoyer undefined si l’outillage n’est pas installé ; lever une erreur s’il rejette // le fichier. Dans les deux cas, le fichier est ignoré. generate( source: string, file: string, context: LanguageContext ): GeneratedSource | undefined | Promise; }; type LanguageContext = { // Importe un paquet installé dans l’application ; undefined s’il n’est pas installé. load(specifier: string): Promise; }; type ParseLang = 'js' | 'jsx' | 'ts' | 'tsx'; ``` ### Source générée `generate` renvoie un `GeneratedSource`. Le code dépourvu de correspondance n'est jamais comptabilisé comme une utilisation. | Champ | Description | Type | Facultatif | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ---------- | | `code` | Le fichier sous forme d'un module unique. | `string` | Non | | `lang` | Le langage de `code`. | `ParseLang` | Non | | `mappings` | La provenance, dans le fichier, de chaque plage de `code`. | `Mapping[]` | Non | | `elements` | Le balisage du fichier, qui associe à chaque utilisation son élément. Cette étiquette n'est pas écrite dans les fichiers de métadonnées. | `SourceElement[]` | Oui | | `scripts` | Les modules autonomes contenus dans le fichier, comme les scripts client d'une page Astro, chacun sous forme de `GeneratedScript` : `{ code, lang, mappings }`. | `GeneratedScript[]` | Oui | | `componentFields` | Les classes dont un modèle lit les champs sans les déclarer, comme c'est le cas des modèles Angular. Chacune est un `ComponentFields` : `{ specifier, className?, range? }`. | `ComponentFields[]` | Oui | | `scopeObjects` | Les objets dont les membres se résolvent comme des noms du module, par exemple `__VLS_ctx` dans Vue. | `string[]` | Oui | | `props` | L'endroit où le composant lit les props transmises par ses sites d'appel : `{ calls?, members?, variables?, undeclared? }`. | `object` | Oui | | `componentInstances` | La manière dont le code généré affiche les composants importés, en dehors de JSX : `{ via: 'new' \| 'call', path }`. | `object` | Oui | ### Correspondances et éléments ```ts // L'intervalle généré [generated, generated + length) correspond à // l'intervalle source [source, source + sourceLength). sourceLength vaut length par défaut. type Mapping = { generated: number; source: number; length: number; sourceLength?: number; }; // À partir d'une source map version 3, comme celle de svelte2tsx : la map sous forme d'objet // (EncodedSourceMap de @jridgewell/trace-mapping) ou de chaîne JSON. function mappingsFromSourceMap( map: EncodedSourceMap | string, generatedCode: string, sourceCode: string ): Mapping[]; // À partir des correspondances du code virtuel de Volar : // @vue/language-core, @mdx-js/language-service, Glint. // Transmettez les correspondances de Volar telles quelles, sans les modifier. function mappingsFromVolar( mappings: readonly { sourceOffsets: readonly number[]; generatedOffsets: readonly number[]; lengths: readonly number[]; generatedLengths?: readonly number[]; }[] ): Mapping[]; ``` Un `SourceElement` décrit un élément de balisage avec ses positions dans la source : `name`, `start`, `end`, `nameStart`, `nameEnd`, `openEnd`, `component` et `attributes` (chacun de la forme `{ name, start, end }`, la plage correspondant à la valeur de l'attribut). ### Langages intégrés `defaultLanguages` contient, dans l'ordre : `vueLanguage`, `svelteLanguage`, `astroLanguage`, `mdxLanguage`, `markdownLanguage`, `angularComponentLanguage`, `angularTemplateLanguage`, `analogLanguage`, `markoLanguage` et `emberLanguage`. Chacun est également exporté séparément. Pour connaître les fichiers et outils associés à chacun, consultez [Formats de fichiers pris en charge](/docs/integrations/paraglide/reference/file-formats). ## Configurations de bundler [#bundler-configs] Une configuration de bundler lit les alias d'importation depuis un fichier de configuration, sans exécuter le bundler. Transmettez-les via l'option [`bundlerConfigs`](/docs/integrations/paraglide/reference/collect-context#bundler-configs). (Voir [Résolution des importations](/docs/integrations/paraglide/guides/resolving-imports#bundler-config).) ```ts type BundlerConfig = { name: string; files: readonly string[]; // noms possibles du fichier de configuration // file est absolu. Un échec, renvoyé ou levé, est signalé et la // configuration est ignorée. read( file: string, context: ConfigContext ): Promise; }; type ImportResolution = { aliases: readonly ImportAlias[]; rootDirectory?: string; // répertoire à partir duquel /src/a.js est résolu (le root de Vite) }; type ConfigFailure = { error: string }; type ConfigContext = { // Importe un paquet depuis l'application ; undefined s'il n'est pas installé. load(specifier: string): Promise; }; type ImportAlias = { find: string | RegExp; // une chaîne de caractères correspond à find et à find/… replacement: string; exact?: boolean; // une chaîne de caractères ne correspond qu'à find lui-même (le name$ de webpack) }; type AliasOption = Readonly> | readonly ImportAlias[]; ``` | Export | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultBundlerConfigs` | `viteConfig`, `webpackConfig` et `rspackConfig`, dans cet ordre. | | `viteConfig` | Lit `vite.config.*` avec l'instance de Vite propre à l'application. Renvoie les alias résolus et la racine de Vite. | | `webpackConfig`, `rspackConfig` | Importent `webpack.config.*` et `rspack.config.*`, puis lisent `resolve.alias`. | | `webpackLikeConfig(name, baseName)` | Crée une configuration de bundler pour un fichier au format webpack nommé `baseName`, avec une extension `.js`, `.mjs`, `.ts`, `.cjs`, `.mts` ou `.cts`. | Une configuration au format webpack peut exporter un objet, une fonction ou une liste de l'un ou de l'autre ; dans le cas d'une liste, seule la première entrée est utilisée. Une fonction est appelée avec un `env` vide et `{ mode: 'production' }`. ## Résolveurs [#resolvers] Un résolveur renvoie le fichier vers lequel une importation se résout, ou `undefined`. Pour utiliser votre propre résolveur, créez le collecteur qu'encapsule [`collectContext`](/docs/integrations/paraglide/reference/collect-context) (voir [Résoudre les importations](/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; // le projet, ou l'un de ses répertoires logger: CollectorLogger; // { warn(message), info(message) } resolver: Resolver; }; ``` `ParaglideContextOptions` regroupe les options de `collectContext` qui ne concernent pas la résolution : `include`, `exclude`, `targets`, `languages`, `inlangProjects`, `radius`, `outdirs` et `autoImports`. Sur le `ContextCollector` renvoyé, appelez `scanAll()` pour analyser le projet, puis `write()` pour écrire les fichiers de métadonnées. | Export | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `nodeResolver(options?)` | Résout les modules comme le ferait un bundler, sans en nécessiter un : alias, `exports` et `imports` du paquet, `paths` du `tsconfig.json` le plus proche de chaque fichier importateur, et correspondance de `./a.js` vers `./a.ts` propre à TypeScript. Accepte `NodeResolverOptions` : `{ alias?, rootDirectory?, conditions? }`. | | `ProjectResolver` | Le résolveur utilisé par `collectContext` : les alias de la configuration du bundler de l'application, puis `nodeResolver`. | ```ts import { createCollector, ProjectResolver, } from '@generaltranslation/paraglide-js/compiler'; const environment = { root: process.cwd(), logger: console }; // ProjectResolverOptions : NodeResolverOptions et 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(); // liste les importations susceptibles d'être des alias non déclarés ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.