# General Translation Integrations: API de extensiones URL: https://generaltranslation.com/es/docs/integrations/paraglide/reference/extension-api.mdx Docs index: https://generaltranslation.com/llms.txt Description: Personaliza qué se considera Paraglide JS, qué formatos de archivo se analizan y cómo se resuelven las importaciones. Referencia de la API de los destinos, lenguajes, configuraciones del empaquetador y resolvedores. Todo lo que aparece en esta página se exporta desde `@generaltranslation/paraglide-js/compiler` y se pasa a [`collectContext`](/docs/integrations/paraglide/reference/collect-context) a través de sus opciones. El análisis en sí (grafo de módulos, usos y renderizado) es interno. ## Descripción general [#overview] | API | Descripción | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------- | | [Destinos](#targets) | Qué archivos resueltos pertenecen a Paraglide JS y cuáles son sus exportaciones. | | [Lenguajes](#languages) | Formatos de archivo que las herramientas de un framework convierten a TypeScript. | | [Configuraciones del empaquetador](#bundler-configs) | Archivos de configuración de los que se leen los alias de importación. | | [Resolvedores](#resolvers) | Funciones que resuelven una importación a un archivo y el recolector en el que se integran. | ## Destinos [#targets] Un destino indica qué archivos resueltos pertenecen a Paraglide JS y qué representa cada una de sus exportaciones. Pasa los destinos mediante la opción [`targets`](/docs/integrations/paraglide/reference/collect-context#targets). Si varios destinos coinciden con un mismo archivo, prevalece el último. ```ts type ParaglideTarget = { name: string; // etiqueta de los usos, como "message" matches(file: TargetFile): boolean; // Devuelve undefined para no hacer seguimiento de una exportación. exportSymbol(exportName: string, file: TargetFile): SymbolSpec | undefined; }; type TargetFile = { file: string; // absoluta, con barras diagonales outdir: string | undefined; // el directorio de salida que contiene el archivo outdirPath: string | undefined; // relativa a outdir, como "messages.js" }; type SymbolSpec = | { type: 'namespace'; member(name: string): SymbolSpec | undefined } // methods: métodos cuyas llamadas también cuentan, como .parts() en los mensajes | { type: 'value'; name: string; methods?: readonly string[] }; ``` | Exportación | Descripción | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultTargets` | `messagesTarget`, `runtimeTarget`, `serverTarget`, `registryTarget` y `adapterTargets`. | | `messagesTarget` | `messages.js`, con su espacio de nombres `m`, y todos los módulos de `messages/`. Su nombre es `message`. | | `runtimeTarget`, `serverTarget`, `registryTarget` | Todas las exportaciones de `runtime.js`, `server.js` y `registry.js`. | | `adapterTargets` | Los adaptadores de frameworks de Paraglide (`@inlang/paraglide-js-react`, `-solid`, `-svelte` y `-vue`) y los de Paraglide JS 1 (`@inlang/paraglide-sveltekit`, `@inlang/paraglide-next` y `@inlang/paraglide-astro`). | | `defineTarget(target)` | Devuelve el destino sin modificar, tipado como `ParaglideTarget`. | | `generatedFileTarget(name, outdirPath)` | Un archivo del directorio de salida del que se rastrean todas las exportaciones. | | `packageTarget(name, packageName)` | Un paquete instalado del que se rastrean las exportaciones con nombre. | *Nota: Solo los usos del destino `message` se escriben en los [archivos de metadatos](/docs/integrations/paraglide/reference/metadata-files). Los usos de los demás destinos se analizan, pero no tienen ninguna clave de mensaje en la que registrarse.* ## Lenguajes [#languages] Un lenguaje convierte un formato de archivo en un único módulo de JavaScript o TypeScript usando las herramientas propias del framework. Pasa los lenguajes mediante la opción [`languages`](/docs/integrations/paraglide/reference/collect-context#languages). (Consulta [Agregar formatos de archivo](/docs/integrations/paraglide/guides/adding-file-formats)). ```ts type SourceLanguage = { name: string; extensions: readonly string[]; // Obligatorio para asumir extensiones de script, como los componentes de Angular en archivos .ts. detect?(source: string, file: string): boolean; // Los paquetes que necesita en la app; se indica cuál falta cuando no está alguno. requires?: readonly string[]; // El paquete que instala uno obligatorio: { svelte2tsx: 'svelte-check' }. installedWith?: Readonly>; // Devuelve undefined cuando las herramientas no están instaladas; lanza un error cuando // rechazan el archivo. En ambos casos, el archivo se omite. generate( source: string, file: string, context: LanguageContext ): GeneratedSource | undefined | Promise; }; type LanguageContext = { // Importa un paquete instalado en la app; undefined si no está instalado. load(specifier: string): Promise; }; type ParseLang = 'js' | 'jsx' | 'ts' | 'tsx'; ``` ### Código fuente generado `generate` devuelve un `GeneratedSource`. El código sin mapeo nunca cuenta como uso. | Campo | Descripción | Tipo | Opcional | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------- | | `code` | El archivo como un único módulo. | `string` | No | | `lang` | El lenguaje de `code`. | `ParseLang` | No | | `mappings` | De qué parte del archivo proviene cada rango de `code`. | `Mapping[]` | No | | `elements` | El marcado del archivo, que etiqueta cada uso con su elemento. La etiqueta no se escribe en los archivos de metadatos. | `SourceElement[]` | Sí | | `scripts` | Módulos independientes dentro del archivo, como los scripts de cliente de una página de Astro, cada uno como un `GeneratedScript`: `{ code, lang, mappings }`. | `GeneratedScript[]` | Sí | | `componentFields` | Clases cuyos campos lee una plantilla sin declararlos, como ocurre en las plantillas de Angular. Cada una es un `ComponentFields`: `{ specifier, className?, range? }`. | `ComponentFields[]` | Sí | | `scopeObjects` | Objetos cuyos miembros se resuelven como nombres del módulo, como `__VLS_ctx` en Vue. | `string[]` | Sí | | `props` | Dónde lee el componente las props que le pasan sus puntos de llamada: `{ calls?, members?, variables?, undeclared? }`. | `object` | Sí | | `componentInstances` | Cómo renderiza el código generado los componentes importados, además de mediante JSX: `{ via: 'new' \| 'call', path }`. | `object` | Sí | ### Mapeos y elementos ```ts // El rango generado [generated, generated + length) corresponde al // rango de origen [source, source + sourceLength). Si no se indica, sourceLength es igual a length. type Mapping = { generated: number; source: number; length: number; sourceLength?: number; }; // A partir de un source map de la versión 3, como el de svelte2tsx: el mapa como objeto // (EncodedSourceMap de @jridgewell/trace-mapping) o como cadena JSON. function mappingsFromSourceMap( map: EncodedSourceMap | string, generatedCode: string, sourceCode: string ): Mapping[]; // A partir del mapeo del código virtual de Volar: // @vue/language-core, @mdx-js/language-service, Glint. // Pasa el mapeo de Volar sin modificarlo. function mappingsFromVolar( mappings: readonly { sourceOffsets: readonly number[]; generatedOffsets: readonly number[]; lengths: readonly number[]; generatedLengths?: readonly number[]; }[] ): Mapping[]; ``` Un `SourceElement` describe un elemento de marcado con sus desplazamientos en el origen: `name`, `start`, `end`, `nameStart`, `nameEnd`, `openEnd`, `component` y `attributes` (cada atributo con la forma `{ name, start, end }`, donde el rango corresponde al valor del atributo). ### Lenguajes integrados `defaultLanguages` contiene, en este orden: `vueLanguage`, `svelteLanguage`, `astroLanguage`, `mdxLanguage`, `markdownLanguage`, `angularComponentLanguage`, `angularTemplateLanguage`, `analogLanguage`, `markoLanguage` y `emberLanguage`. Cada uno también se exporta de forma individual. Para ver los archivos y las herramientas que corresponden a cada uno, consulta [Formatos de archivo compatibles](/docs/integrations/paraglide/reference/file-formats). ## Configuraciones del empaquetador [#bundler-configs] Una configuración del empaquetador lee los alias de importación de un archivo de configuración sin necesidad de ejecutar el empaquetador. Pásalas mediante la opción [`bundlerConfigs`](/docs/integrations/paraglide/reference/collect-context#bundler-configs). (Consulta [Resolución de importaciones](/docs/integrations/paraglide/guides/resolving-imports#bundler-config)). ```ts type BundlerConfig = { name: string; files: readonly string[]; // posibles nombres del archivo de configuración // file es una ruta absoluta. Si se produce un error, ya sea devuelto o lanzado, // se notifica y la configuración se omite. read( file: string, context: ConfigContext ): Promise; }; type ImportResolution = { aliases: readonly ImportAlias[]; rootDirectory?: string; // desde dónde se resuelve /src/a.js (la raíz de Vite) }; type ConfigFailure = { error: string }; type ConfigContext = { // Importa un paquete de la aplicación; undefined si no está instalado. load(specifier: string): Promise; }; type ImportAlias = { find: string | RegExp; // una cadena coincide con find y find/… replacement: string; exact?: boolean; // una cadena coincide solo con el propio find (name$ de webpack) }; type AliasOption = Readonly> | readonly ImportAlias[]; ``` | Exportación | Descripción | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultBundlerConfigs` | `viteConfig`, `webpackConfig` y `rspackConfig`, en ese orden. | | `viteConfig` | Lee `vite.config.*` con la propia instancia de Vite de la app. Devuelve los alias resueltos y la raíz de Vite. | | `webpackConfig`, `rspackConfig` | Importan `webpack.config.*` y `rspack.config.*` y leen `resolve.alias`. | | `webpackLikeConfig(name, baseName)` | Crea una configuración de empaquetador para un archivo con formato de webpack llamado `baseName` y con extensión `.js`, `.mjs`, `.ts`, `.cjs`, `.mts` o `.cts`. | Una configuración con formato de webpack puede exportar un objeto, una función o una lista de cualquiera de ellos; si es una lista, se usa la primera entrada. Las funciones se invocan con un `env` vacío y `{ mode: 'production' }`. ## Resolvedores [#resolvers] Un resolvedor devuelve el archivo al que se resuelve una importación, o `undefined`. Para usar uno propio, crea el recolector que envuelve [`collectContext`](/docs/integrations/paraglide/reference/collect-context). (Consulta [Resolución de importaciones](/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; // el proyecto o un directorio dentro de él logger: CollectorLogger; // { warn(message), info(message) } resolver: Resolver; }; ``` `ParaglideContextOptions` contiene las opciones de `collectContext` que no tienen que ver con la resolución: `include`, `exclude`, `targets`, `languages`, `inlangProjects`, `radius`, `outdirs` y `autoImports`. En el `ContextCollector` devuelto, llama a `scanAll()` para analizar el proyecto y luego a `write()` para escribir los archivos de metadatos. | Exportación | Descripción | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `nodeResolver(options?)` | Resuelve como lo haría un empaquetador, sin necesidad de usar uno: alias, `exports` e `imports` del paquete, `paths` de `tsconfig.json` tomados del `tsconfig.json` más cercano a cada archivo importador, y la conversión de `./a.js` a `./a.ts` propia de TypeScript. Recibe `NodeResolverOptions`: `{ alias?, rootDirectory?, conditions? }`. | | `ProjectResolver` | El resolvedor que usa `collectContext`: primero aplica los alias de la configuración del empaquetador de la app y después `nodeResolver`. | ```ts import { createCollector, ProjectResolver, } from '@generaltranslation/paraglide-js/compiler'; const environment = { root: process.cwd(), logger: console }; // ProjectResolverOptions: NodeResolverOptions y 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(); // enumera las importaciones que podrían ser alias no declarados ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.