# General Translation Integrations: API di estensione URL: https://generaltranslation.com/it/docs/integrations/paraglide/reference/extension-api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Personalizza cosa viene considerato Paraglide JS, quali formati di file vengono analizzati e come vengono risolte le importazioni. Riferimento API per target, linguaggi, configurazioni dei bundler e resolver. Tutto ciò che è descritto in questa pagina viene esportato da `@generaltranslation/paraglide-js/compiler` e passato a [`collectContext`](/docs/integrations/paraglide/reference/collect-context) tramite le relative opzioni. L'analisi vera e propria (grafo dei moduli, utilizzi e rendering) è gestita internamente. ## Panoramica [#overview] | API | Descrizione | | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | | [Target](#targets) | Quali file risolti appartengono a Paraglide JS e quali sono i rispettivi export. | | [Linguaggi](#languages) | Formati di file che gli strumenti di un framework convertono in TypeScript. | | [Configurazioni del bundler](#bundler-configs) | File di configurazione da cui vengono letti gli alias di importazione. | | [Resolver](#resolvers) | Funzioni che risolvono un'importazione in un file e il collector a cui si agganciano. | ## Target [#targets] Un target indica quali file risolti appartengono a Paraglide JS e cosa rappresenta ciascuno dei loro export. Specifica i target tramite l'opzione [`targets`](/docs/integrations/paraglide/reference/collect-context#targets). Se più target corrispondono a uno stesso file, prevale l'ultimo. ```ts type ParaglideTarget = { name: string; // etichetta sugli utilizzi, ad esempio "message" matches(file: TargetFile): boolean; // Restituisci undefined per non tracciare un export. exportSymbol(exportName: string, file: TargetFile): SymbolSpec | undefined; }; type TargetFile = { file: string; // assoluto, con barre in avanti (/) outdir: string | undefined; // la directory di output che contiene il file outdirPath: string | undefined; // relativo a outdir, ad esempio "messages.js" }; type SymbolSpec = | { type: 'namespace'; member(name: string): SymbolSpec | undefined } // methods: metodi le cui chiamate vengono conteggiate anch'esse, ad esempio .parts() sui messaggi | { type: 'value'; name: string; methods?: readonly string[] }; ``` | Export | Descrizione | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultTargets` | `messagesTarget`, `runtimeTarget`, `serverTarget`, `registryTarget` e `adapterTargets`. | | `messagesTarget` | `messages.js`, con il relativo namespace `m`, e tutti i moduli in `messages/`. Ha nome `message`. | | `runtimeTarget`, `serverTarget`, `registryTarget` | Tutti gli export di `runtime.js`, `server.js` e `registry.js`. | | `adapterTargets` | Gli adattatori per framework di Paraglide: `@inlang/paraglide-js-react`, `-solid`, `-svelte` e `-vue`, oltre a `@inlang/paraglide-sveltekit`, `@inlang/paraglide-next` e `@inlang/paraglide-astro` di Paraglide JS 1. | | `defineTarget(target)` | Restituisce il target invariato, tipizzato come `ParaglideTarget`. | | `generatedFileTarget(name, outdirPath)` | Un file nella directory di output di cui vengono tracciati tutti gli export. | | `packageTarget(name, packageName)` | Un pacchetto installato di cui vengono tracciati gli export con nome. | *Nota: solo gli utilizzi del target `message` vengono scritti nei [file di metadati](/docs/integrations/paraglide/reference/metadata-files). Gli utilizzi degli altri target vengono analizzati, ma non hanno una chiave di messaggio sotto cui essere scritti.* ## Linguaggi [#languages] Un linguaggio converte un formato di file in un unico modulo JavaScript o TypeScript tramite gli strumenti nativi del framework. Per passare i linguaggi, usa l'opzione [`languages`](/docs/integrations/paraglide/reference/collect-context#languages). (Vedi [Aggiungere formati di file](/docs/integrations/paraglide/guides/adding-file-formats)). ```ts type SourceLanguage = { name: string; extensions: readonly string[]; // Necessario per gestire estensioni di script, come i componenti Angular nei file .ts. detect?(source: string, file: string): boolean; // I pacchetti necessari nell'app, indicati per nome quando ne manca uno. requires?: readonly string[]; // Il pacchetto che installa quello richiesto: { svelte2tsx: 'svelte-check' }. installedWith?: Readonly>; // Restituisce undefined quando gli strumenti non sono installati; genera un errore quando // rifiutano il file. In entrambi i casi il file viene ignorato. generate( source: string, file: string, context: LanguageContext ): GeneratedSource | undefined | Promise; }; type LanguageContext = { // Importa un pacchetto installato nell'app; undefined se non è installato. load(specifier: string): Promise; }; type ParseLang = 'js' | 'jsx' | 'ts' | 'tsx'; ``` ### Sorgente generata `generate` restituisce un `GeneratedSource`. Il codice senza una mappatura non viene mai conteggiato come utilizzo. | Campo | Descrizione | Tipo | Facoltativo | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | | `code` | Il file come singolo modulo. | `string` | No | | `lang` | Il linguaggio di `code`. | `ParseLang` | No | | `mappings` | Da quale punto del file proviene ciascun intervallo di `code`. | `Mapping[]` | No | | `elements` | Il markup del file, che etichetta ogni utilizzo con il relativo elemento. L'etichetta non viene scritta nei file di metadati. | `SourceElement[]` | Sì | | `scripts` | Moduli autonomi presenti nel file, come gli script client di una pagina Astro, ciascuno sotto forma di `GeneratedScript`: `{ code, lang, mappings }`. | `GeneratedScript[]` | Sì | | `componentFields` | Classi i cui campi vengono letti da un template senza essere dichiarati, come accade nei template Angular. Ciascuna è un `ComponentFields`: `{ specifier, className?, range? }`. | `ComponentFields[]` | Sì | | `scopeObjects` | Oggetti i cui membri vengono risolti come nomi del modulo, ad esempio `__VLS_ctx` di Vue. | `string[]` | Sì | | `props` | Dove il componente legge le props passate dai punti di chiamata: `{ calls?, members?, variables?, undeclared? }`. | `object` | Sì | | `componentInstances` | Come il codice generato renderizza i componenti importati al di fuori di JSX: `{ via: 'new' \| 'call', path }`. | `object` | Sì | ### Mappature ed elementi ```ts // L'intervallo generato [generated, generated + length) corrisponde // all'intervallo sorgente [source, source + sourceLength). Il valore predefinito di sourceLength è length. type Mapping = { generated: number; source: number; length: number; sourceLength?: number; }; // Da una source map versione 3, come quella di svelte2tsx: la mappa come oggetto // (EncodedSourceMap di @jridgewell/trace-mapping) o come stringa JSON. function mappingsFromSourceMap( map: EncodedSourceMap | string, generatedCode: string, sourceCode: string ): Mapping[]; // Dalle mappature del codice virtuale di Volar: // @vue/language-core, @mdx-js/language-service, Glint. // Passa le mappature di Volar senza modificarle. function mappingsFromVolar( mappings: readonly { sourceOffsets: readonly number[]; generatedOffsets: readonly number[]; lengths: readonly number[]; generatedLengths?: readonly number[]; }[] ): Mapping[]; ``` Un `SourceElement` descrive un singolo elemento di markup, con i relativi offset nel testo sorgente: `name`, `start`, `end`, `nameStart`, `nameEnd`, `openEnd`, `component` e `attributes` (ciascuno nella forma `{ name, start, end }`, dove l'intervallo corrisponde al valore dell'attributo). ### Linguaggi integrati `defaultLanguages` contiene, nell'ordine: `vueLanguage`, `svelteLanguage`, `astroLanguage`, `mdxLanguage`, `markdownLanguage`, `angularComponentLanguage`, `angularTemplateLanguage`, `analogLanguage`, `markoLanguage` e `emberLanguage`. Ognuno viene esportato anche singolarmente. Per i file e gli strumenti supportati da ciascuno, consulta [Formati di file supportati](/docs/integrations/paraglide/reference/file-formats). ## Configurazioni del bundler [#bundler-configs] Una configurazione del bundler legge gli alias di importazione da un file di configurazione senza eseguire il bundler. Passale tramite l'opzione [`bundlerConfigs`](/docs/integrations/paraglide/reference/collect-context#bundler-configs). (Vedi [Risoluzione delle importazioni](/docs/integrations/paraglide/guides/resolving-imports#bundler-config)). ```ts type BundlerConfig = { name: string; files: readonly string[]; // possibili nomi del file di configurazione // file è un percorso assoluto. Un errore, restituito o lanciato, viene segnalato e la // config viene ignorata. read( file: string, context: ConfigContext ): Promise; }; type ImportResolution = { aliases: readonly ImportAlias[]; rootDirectory?: string; // da dove si risolve /src/a.js (la radice di Vite) }; type ConfigFailure = { error: string }; type ConfigContext = { // Importa un pacchetto dall'app; undefined se non è installato. load(specifier: string): Promise; }; type ImportAlias = { find: string | RegExp; // una stringa corrisponde a find e a find/… replacement: string; exact?: boolean; // una stringa corrisponde solo a find in sé (il name$ di webpack) }; type AliasOption = Readonly> | readonly ImportAlias[]; ``` | Export | Descrizione | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultBundlerConfigs` | `viteConfig`, `webpackConfig` e `rspackConfig`, in quest'ordine. | | `viteConfig` | Legge `vite.config.*` usando il Vite dell'app stessa. Restituisce gli alias risolti e la radice di Vite. | | `webpackConfig`, `rspackConfig` | Importano `webpack.config.*` e `rspack.config.*` e leggono `resolve.alias`. | | `webpackLikeConfig(name, baseName)` | Crea una configurazione del bundler per un file in formato webpack con nome `baseName` ed estensione `.js`, `.mjs`, `.ts`, `.cjs`, `.mts` o `.cts`. | Una configurazione del bundler in formato webpack può esportare un oggetto, una funzione o un array di oggetti o funzioni; nel caso di un array, viene usata la prima voce. Le funzioni vengono chiamate con un `env` vuoto e con `{ mode: 'production' }`. ## Resolver [#resolvers] Un resolver restituisce il file a cui si risolve un'importazione, oppure `undefined`. Per usarne uno personalizzato, crea il collector che [`collectContext`](/docs/integrations/paraglide/reference/collect-context) racchiude. (Vedi [Risoluzione delle importazioni](/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; // il progetto, o una sua directory logger: CollectorLogger; // { warn(message), info(message) } resolver: Resolver; }; ``` `ParaglideContextOptions` contiene le opzioni di `collectContext` non legate alla risoluzione: `include`, `exclude`, `targets`, `languages`, `inlangProjects`, `radius`, `outdirs` e `autoImports`. Sul `ContextCollector` restituito, chiama `scanAll()` per analizzare il progetto, poi `write()` per scrivere i file di metadati. | Export | Descrizione | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `nodeResolver(options?)` | Risolve i moduli come un bundler, ma senza richiederne uno: alias, `exports` e `imports` del pacchetto, `paths` di `tsconfig.json` ricavati dal `tsconfig.json` più vicino a ciascun file importatore e la mappatura di TypeScript da `./a.js` a `./a.ts`. Accetta `NodeResolverOptions`: `{ alias?, rootDirectory?, conditions? }`. | | `ProjectResolver` | Il resolver usato da `collectContext`: prima gli alias della configurazione del bundler dell'app, poi `nodeResolver`. | ```ts import { createCollector, ProjectResolver, } from '@generaltranslation/paraglide-js/compiler'; const environment = { root: process.cwd(), logger: console }; // ProjectResolverOptions: NodeResolverOptions e 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(); // elenca le importazioni che potrebbero essere alias non dichiarati ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.