# gt-node: General Translation Node.js SDK: Configuración
URL: https://generaltranslation.com/es/docs/node/reference/config.mdx
---

title: Configuración
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.

## 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 configura (sin un `loadTranslations` personalizado), habilita el loader de CDN que obtiene las traducciones en Runtime.

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

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

Una clave de API para desarrollo. 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 cuando `NODE_ENV` no es `'production'`.

## `apiKey` [#api-key]

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

Una clave API de producción. 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'],
});
```