# gt-node: General Translation Node.js SDK: Configuración
URL: https://generaltranslation.com/es/docs/node/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Configura la biblioteca gt-node de General Translation con initializeGT. Referencia de la API para la configuración de gt-node.

La biblioteca `gt-node` se configura mediante una única llamada a [`initializeGT`](/docs/node/reference/functions/initialize-gt) al iniciarse. No lee `gt.config.json` automáticamente, pero sí usa variables de entorno como alternativa para las credenciales. Esta página documenta las claves que acepta esa llamada.

## Descripción general [#overview]

Llama a [`initializeGT`](/docs/node/reference/functions/initialize-gt) una vez, antes de procesar solicitudes, con un objeto de configuración. Se ejecuta de forma síncrona y no devuelve nada.

```ts
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'],
});
```

Las claves reflejan las que lee la [`gt` CLI](/docs/cli/quickstart) de `gt.config.json`. Para mantener ambas sincronizadas, importa tu `gt.config.json` y propaga sus campos en la llamada:

```ts
import { initializeGT } from 'gt-node';
import gtConfig from './gt.config.json' with { type: 'json' };

initializeGT(gtConfig);
```

El tipo de configuración es `InitializeGTParams`, una combinación de las opciones de resolución de la configuración regional y las opciones de caché de traducción.

## Variables de entorno [#env]

Los valores explícitos que se pasan a [`initializeGT`](/docs/node/reference/functions/initialize-gt) tienen prioridad sobre las variables de entorno.

| Variable         | Descripción                                                    |
| ---------------- | -------------------------------------------------------------- |
| `GT_PROJECT_ID`  | ID del Project que se usa si se omite `projectId`.             |
| `GT_DEV_API_KEY` | Clave de API de desarrollo que se usa si se omite `devApiKey`. |
| `GT_API_KEY`     | Clave de API de producción que se usa si se omite `apiKey`.    |

## Opciones [#options]

| Opción                                       | Descripción                                                                                                     | Tipo                                                                  | Opcional | Predeterminado                       |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------ |
| [`defaultLocale`](#default-locale)           | Configuración regional de origen y de contenido alternativo.                                                    | `string`                                                              | Sí       | `'en'`                               |
| [`locales`](#locales)                        | Configuraciones regionales de destino compatibles.                                                              | `string[]`                                                            | Sí       | `[defaultLocale]`                    |
| [`projectId`](#project-id)                   | ID del proyecto; habilita el loader de la CDN de General Translation cuando se configura.                       | `string`                                                              | Sí       | `GT_PROJECT_ID` si está configurado  |
| [`devApiKey`](#dev-api-key)                  | Clave de API de desarrollo para traducción on-demand.                                                           | `string`                                                              | Sí       | `GT_DEV_API_KEY` si está configurado |
| [`apiKey`](#api-key)                         | Clave de API de producción.                                                                                     | `string`                                                              | Sí       | `GT_API_KEY` si está configurado     |
| [`cacheUrl`](#cache-url)                     | Host de la caché de traducciones. `null` desactiva la carga remota.                                             | `string \| null`                                                      | Sí       | GT CDN                               |
| [`runtimeUrl`](#runtime-url)                 | Host de traducción en tiempo de ejecución. `null` la desactiva.                                                 | `string \| null`                                                      | Sí       | GT runtime                           |
| [`loadTranslations`](#load-translations)     | Loader personalizado que devuelve traducciones para una configuración regional.                                 | `TranslationsLoader`                                                  | Sí       | —                                    |
| [`customMapping`](#custom-mapping)           | aliases de configuración regional y anulaciones de propiedades.                                                 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Sí       | —                                    |
| [`cacheExpiryTime`](#cache-expiry)           | Duración de la caché de la configuración regional en milisegundos. `null` desactiva el vencimiento.             | `number \| null`                                                      | Sí       | —                                    |
| [`dictionary`](#dictionary)                  | Diccionario en el idioma fuente leído por [`getTranslations`](/docs/node/reference/functions/get-translations). | `Dictionary`                                                          | Sí       | —                                    |
| [`loadDictionary`](#load-dictionary)         | Loader que devuelve un diccionario para una configuración regional.                                             | `DictionaryLoader`                                                    | Sí       | —                                    |
| [`runtimeTranslation`](#runtime-translation) | `timeout` y `metadata` de la traducción en tiempo de ejecución.                                                 | `object`                                                              | Sí       | `timeout` 12000                      |
| [`batchConfig`](#batch-config)               | Límites de procesamiento por lotes de la traducción en tiempo de ejecución.                                     | `object`                                                              | Sí       | —                                    |
| [`modelProvider`](#model-provider)           | Clave del proveedor de modelos reflejada desde `gt.config.json`. El runtime no la consume.                      | `string`                                                              | Sí       | —                                    |

*Nota: [`initializeGT`](/docs/node/reference/functions/initialize-gt) también acepta claves internas con prefijo de guion bajo (`_versionId`, `_branchId`, `_disableDevHotReload`) y un objeto `files` usado por el compilador de la CLI. Estas no forman parte de la superficie pública estable y se omiten aquí.*

## Credenciales del entorno [#environment]

Cuando se omite una credencial del objeto de configuración, [`initializeGT`](/docs/node/reference/functions/initialize-gt) lee la variable de entorno correspondiente:

| Opción      | Variable de entorno | Precedencia                               |
| ----------- | ------------------- | ----------------------------------------- |
| `projectId` | `GT_PROJECT_ID`     | Opción explícita no vacía; luego, entorno |
| `devApiKey` | `GT_DEV_API_KEY`    | Opción explícita no vacía; luego, entorno |
| `apiKey`    | `GT_API_KEY`        | Opción explícita no vacía; luego, entorno |

Una cadena explícita vacía se considera ausente y usa el valor del entorno. Otros campos de configuración, incluidos `locales` y los loaders de traducción, no se leen del entorno.

## `defaultLocale` [#default-locale]

**Tipo** `string` · **Opcional** · **Predeterminado** `'en'`

La configuración regional predeterminada de tu aplicación. Es la configuración regional en la que está escrito tu contenido de origen y la que se usa como contenido alternativo cuando no se encuentra ninguna traducción. Si se omite, se usará la configuración regional predeterminada de la biblioteca, `'en'`.

```ts
initializeGT({ defaultLocale: 'en-US' });
```

## `locales` [#locales]

**tipo** `string[]` · **Opcional** · **Predeterminado** `[defaultLocale]`

Una lista de [códigos de configuración regional](/docs/platform/core/reference/utility-functions/locales/is-valid-locale) compatibles con tu aplicación. `defaultLocale` siempre se incluye entre las configuraciones regionales admitidas, aunque lo omitas aquí.

```ts
initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr', 'ja'] });
```

## `projectId` [#project-id]

**Tipo** `string` · **Opcional** · **Predeterminado** `GT_PROJECT_ID` si está configurado

Tu ID de proyecto de General Translation, obligatorio para los servicios en la nube de General Translation. Cuando se omite, usa `GT_PROJECT_ID` como contenido alternativo. Cuando se configura sin un `loadTranslations` personalizado, habilita el loader de CDN que obtiene las traducciones en tiempo de ejecución.

## `devApiKey` [#dev-api-key]

**Tipo** `string` · **Opcional** · **Predeterminado** `GT_DEV_API_KEY` si está configurado

Una clave de API para desarrollo. Cuando se omite, usa `GT_DEV_API_KEY` como contenido alternativo. Junto con un `projectId`, habilita la traducción bajo demanda en tiempo de ejecución y la recarga en caliente durante el desarrollo, para que [`getGT`](/docs/node/reference/functions/get-gt), [`getMessages`](/docs/node/reference/functions/get-messages) y [`tx`](/docs/node/reference/functions/tx) puedan traducir contenido nuevo mientras desarrollas. La recarga en caliente solo se ejecuta en un entorno de desarrollo, lo que significa que `NODE_ENV` es exactamente `'development'`, o que `import.meta.env.MODE` es `'development'`, o que `import.meta.env.DEV` es `true`. Cualquier otro valor se considera producción, incluido un `NODE_ENV` sin configurar, así que establece `NODE_ENV=development` para la recarga en caliente.

## `apiKey` [#api-key]

**Tipo** `string` · **Opcional** · **Predeterminado** `GT_API_KEY` si está configurado

Una clave de API de producción. Cuando se omite, se usa `GT_API_KEY` como contenido alternativo. Configúrala cuando necesites traducción en tiempo de ejecución en producción. Para la mayoría de los despliegues, en su lugar genera las traducciones con antelación usando la [`gt` CLI](/docs/cli/quickstart).

## `cacheUrl` [#cache-url]

**tipo** `string | null` · **Opcional** · **predeterminado** GT CDN

La URL del servicio de caché de traducciones. Configúrala con un host personalizado para cargar las traducciones desde tu propia CDN, o en `null` para desactivar la carga remota de caché.

## `runtimeUrl` [#runtime-url]

**Tipo** `string | null` · **Opcional** · **predeterminado** Runtime de GT

La URL del servicio de traducción en tiempo de ejecución que usan [`tx`](/docs/node/reference/functions/tx) y la traducción de desarrollo bajo demanda. Establécela en `null` o `''` para desactivar la traducción en tiempo de ejecución.

## `loadTranslations` [#load-translations]

**Tipo** `TranslationsLoader` · **Opcional**

Una función personalizada que carga traducciones desde tu propia fuente en lugar de la CDN de General Translation. Recibe un código de configuración regional y devuelve las traducciones de esa configuración regional:

```ts
type TranslationsLoader = (locale: string) => Promise<unknown>;
```

```ts
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  loadTranslations: async (locale) => {
    const res = await fetch(`https://my-api.com/translations/${locale}`);
    return res.json();
  },
});
```

## `customMapping` [#custom-mapping]

**tipo** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Opcional**

Una asignación de códigos de configuración regional personalizados a códigos de configuración regional estándar o a anulaciones de [propiedades de configuración regional](/docs/node/reference/functions/get-locale-properties). Úsalo para definir un alias para un código (por ejemplo, `cn` a `zh`) o para anular las propiedades de visualización.

## `cacheExpiryTime` [#cache-expiry]

**tipo** `number | null` · **Opcional**

Duración de la caché de la configuración regional en milisegundos. Déjalo sin definir para usar el TTL predeterminado, especifica un número para definir un TTL explícito o establece `null` para desactivar su vencimiento.

## `dictionary` [#dictionary]

**Tipo** `Dictionary` · **Opcional**

Un diccionario en el idioma fuente con entradas de traducción indexadas por id. Las entradas se resuelven en cada solicitud con [`getTranslations`](/docs/node/reference/functions/get-translations).

## `loadDictionary` [#load-dictionary]

**Tipo** `DictionaryLoader` · **Opcional**

Un loader que devuelve un diccionario para una configuración regional determinada:

```ts
type DictionaryLoader = (locale: string) => Promise<Dictionary>;
```

## `runtimeTranslation` [#runtime-translation]

**Tipo** `object` · **Opcional** · **Predeterminado** `timeout` 12000 ms

Configuración de traducción en tiempo de ejecución aplicada por [`tx`](/docs/node/reference/functions/tx) y la traducción de desarrollo on-demand:

* `timeout?: number` — tiempo de espera de la solicitud en milisegundos (predeterminado: `12000`).
* `metadata?: object` — metadatos incorporados en cada solicitud de traducción en tiempo de ejecución. Aquí van las indicaciones de traducción exclusivas de runtime, como `modelProvider` (consulta [`modelProvider`](#model-provider) más abajo) y `sourceLocale`.

## `batchConfig` [#batch-config]

**Tipo** `object` · **Opcional**

Controla cómo [`tx`](/docs/node/reference/functions/tx) y la traducción de desarrollo on-demand agrupan en lotes las solicitudes de traducción en runtime. Déjalo sin definir para usar la configuración predeterminada.

* `maxConcurrentRequests?: number` — número máximo de solicitudes por lotes en curso.
* `maxBatchSize?: number` — número máximo de entradas por solicitud por lotes.
* `batchInterval?: number` — retraso en milisegundos antes de que se envíe un lote.

## `modelProvider` [#model-provider]

**Tipo** `string` · **Opcional**

Refleja la clave `modelProvider` de `gt.config.json`, que la [`gt` CLI](/docs/cli/quickstart) usa para seleccionar un modelo de traducción. El Runtime de `gt-node` **no** utiliza esta clave de nivel superior; se acepta únicamente para que expandir `gt.config.json` no provoque un error. Para elegir el modelo que usa la traducción en tiempo de ejecución ([`tx`](/docs/node/reference/functions/tx)), configura `modelProvider` dentro de `metadata` de [`runtimeTranslation`](#runtime-translation).

## Ejemplo [#example]

```ts title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  // Las credenciales se leen de GT_PROJECT_ID, GT_API_KEY y GT_DEV_API_KEY.
});
```

## Sitemap

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