# General Translation React SDKs (gt-react, gt-next): Configuración URL: https://generaltranslation.com/es/docs/react/nextjs/config.mdx --- title: Configuración description: Configura General Translation en una aplicación Next.js con el plugin `withGTConfig` de `gt-next/config`, sus opciones y las traducciones locales frente a las del CDN. Referencia de API de `withGTConfig`. --- `withGTConfig` es el plugin de configuración de `gt-next`. Envuelve tu configuración de Next.js con él en `next.config` para habilitar la internacionalización en tiempo de compilación. Lee tu archivo `gt.config.json`, lo combina con cualquier opción que pases y con tus variables de entorno, y configura el compilador, la carga de traducciones y el manejo de solicitudes. Esta página documenta el plugin y sus opciones. Para la configuración compartida de configuración regional y archivos de `gt.config.json`, consulta la [referencia de configuración de `gt-react`](/docs/react/reference/config); para el esquema `files` del lado del CLI, consulta la [referencia de configuración del CLI](/docs/cli/reference/config). ## Descripción general [#overview] Importa `withGTConfig` desde `gt-next/config` y envuelve la configuración de Next.js. Las opciones se pueden pasar como segundo argumento, pero en la mayoría de los proyectos la configuración regional se mantiene en `gt.config.json`. ```ts title="next.config.ts" import { withGTConfig } from 'gt-next/config'; import type { NextConfig } from 'next'; const nextConfig: NextConfig = { // tu configuración actual de Next.js }; export default withGTConfig(nextConfig, { defaultLocale: 'en', locales: ['es', 'fr', 'ja'], }); ``` `withGTConfig` debe usarse en `next.config` — es el único lugar donde la internacionalización se conecta al proceso de compilación. ## Cómo funciona [#how-it-works] * **Resolución de la configuración.** De forma predeterminada, el plugin carga `./gt.config.json` (también busca `./.gt/gt.config.json` y `./.locadex/gt.config.json`). Los valores se combinan con esta precedencia: **las opciones que pasas > las variables de entorno > `gt.config.json` > los valores predeterminados.** Si una clave definida tanto en `gt.config.json` como en las opciones entra en conflicto, la compilación genera un error, así que mantén cada valor en un solo lugar. * **Las credenciales provienen del entorno.** No puedes pasar `projectId`, `apiKey` ni `devApiKey` como opciones; debes configurarlos como variables de entorno (consulta [Credenciales](#credentials)). * **Estandarización de la configuración regional.** Cuando los servicios de General Translation están habilitados, los códigos de configuración regional se estandarizan a la forma canónica BCP 47 y las configuraciones regionales no válidas provocan un error en tiempo de compilación. * **Entrega de traducciones.** Si se resuelve un archivo [`loadTranslations`](/docs/react/reference/functions/load-translations), las traducciones se cargan desde tu bundle; de lo contrario, se obtienen desde la CDN de General Translation. Consulta [Traducciones locales vs. CDN](#translations). ## Credenciales [#credentials] Configura tu ID del proyecto y tus claves API como variables de entorno, nunca como opciones del plugin: | Variable | Descripción | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GT_PROJECT_ID` (o `NEXT_PUBLIC_GT_PROJECT_ID`) | Tu ID de proyecto de General Translation. | | `GT_API_KEY` | Clave API de producción (con prefijo `gtx-api-`), usada por la CLI y las compilaciones de producción. | | `GT_DEV_API_KEY` (o `NEXT_PUBLIC_GT_DEV_API_KEY`) | Clave API de desarrollo (con prefijo `gtx-dev-`), para traducción on-demand en desarrollo. | *Advertencia: nunca uses el prefijo `NEXT_PUBLIC_` con una clave API de producción y no incluyas una clave de desarrollo en producción; la compilación falla si `GT_DEV_API_KEY` está presente con `NODE_ENV=production`.* ## Opciones [#options] Todas las opciones son opcionales. Las opciones de configuración regional suelen definirse en `gt.config.json` en lugar de aquí. ### Opciones de configuración regional [#locale-options] | Opción | Descripción | Tipo | Opcional | Predeterminado | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | -------- | -------------- | | [`defaultLocale`](#default-locale) | Configuración regional de origen en la que está escrita tu aplicación. | `string` | Sí | `en` | | [`locales`](#locales) | Configuraciones regionales de destino a las que traducir. | `string[]` | Sí | `[]` | | [`ignoreBrowserLocales`](#ignore-browser-locales) | Ignora las configuraciones regionales preferidas del navegador durante la detección. | `boolean` | Sí | `false` | | [`disableInvalidLocaleWarning`](#disable-invalid-locale-warning) | Silencia las advertencias sobre configuraciones regionales de solicitud no válidas. | `boolean` | Sí | `false` | | [`description`](#description) | Descripción en lenguaje natural de tu aplicación, usada para orientar la traducción. | `string` | Sí | — | ### Entrega de traducciones [#delivery-options] | Opción | Descripción | Tipo | Opcional | Predeterminado | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------- | -------- | ------------------------ | | [`runtimeUrl`](#runtime-url) | URL base de la API de General Translation. Una cadena vacía desactiva la traducción en tiempo de ejecución. | `string \| null` | Sí | GT runtime | | [`cacheUrl`](#cache-url) | URL de las traducciones en caché. | `string \| null` | Sí | GT CDN | | [`cacheExpiryTime`](#cache-expiry-time) | Milisegundos antes de que caduquen las traducciones almacenadas en caché localmente. | `number` | Sí | `60000` | | [`loadTranslationsPath`](#load-translations-path) | Ruta a un archivo `loadTranslations` personalizado. | `string` | Sí | Resuelto automáticamente | | [`loadDictionaryPath`](#load-dictionary-path) | Ruta a un archivo [`loadDictionary`](/docs/react/reference/functions/load-dictionary) personalizado. | `string` | Sí | Resuelto automáticamente | | [`dictionary`](#dictionary) | Ruta a tu archivo de diccionario. | `string` | Sí | Resuelto automáticamente | | [`config`](#config-path) | Ruta al archivo `gt.config.json`. | `string` | Sí | `./gt.config.json` | ### Renderizado [#rendering-options] | Opción | Descripción | Tipo | Opcional | Predeterminado | | ------------------------------------ | ---------------------------------------------------------------------------- | -------- | -------- | -------------- | | [`renderSettings`](#render-settings) | Cómo se muestran las traducciones en tiempo de ejecución mientras se cargan. | `object` | Sí | Ver abajo | ### Rendimiento [#performance-options] | Opción | Descripción | Tipo | Opcional | Predeterminado | | --------------------------------------------------- | ------------------------------------------------------- | -------- | -------- | -------------- | | [`maxConcurrentRequests`](#max-concurrent-requests) | Número máximo de solicitudes de traducción simultáneas. | `number` | Sí | `100` | | [`maxBatchSize`](#max-batch-size) | Número máximo de traducciones por lote. | `number` | Sí | `25` | | [`batchInterval`](#batch-interval) | Milisegundos entre solicitudes en lote. | `number` | Sí | `50` | ### Compilación e integración [#build-options] | Opción | Descripción | Tipo | Opcional | Predeterminado | | -------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------- | -------- | -------------- | | [`experimentalCompilerOptions`](#compiler-options) | Configuración del plugin del compilador. | `object` | Sí | Ver abajo | | [`headersAndCookies`](#headers-and-cookies) | Nombres personalizados de la cabecera y la cookie de configuración regional. | `object` | Sí | Ver abajo | | [`getLocalePath`](#request-function-paths) | Ruta a una función [`getLocale`](/docs/node/reference/functions/get-locale) personalizada. | `string` | Sí | — | | [`getRegionPath`](#request-function-paths) | Ruta a una función `getRegion` personalizada. | `string` | Sí | — | | [`pathRegex`](#path-regex) | Restringe el middleware de i18n a los nombres de ruta que coincidan. | `string` | Sí | — | | [`eslint`](#eslint-options) | Genera la configuración de ESLint de General Translation. | `boolean` | Sí | `true` | | [`eslintSeverity`](#eslint-options) | Nivel de severidad de las reglas de ESLint generadas. | `'error' \| 'warn'` | Sí | `'warn'` | | [`overwriteESLintConfig`](#eslint-options) | Sobrescribe un archivo `eslint.config.mjs` existente. | `boolean` | Sí | `false` | ### `defaultLocale` [#default-locale] **Tipo** `string` · **Opcional** · **Predeterminado** `en` La configuración regional de origen de tu aplicación. Se usa como contenido alternativo si falta una traducción. ### `locales` [#locales] **Tipo** `string[]` · **Opcional** · **Predeterminado** `[]` Las configuraciones regionales de destino a las que se traducirá. Las solicitudes de una configuración regional no compatible recurren primero a la coincidencia más cercana y luego a `defaultLocale`. Elige entre las [configuraciones regionales compatibles](/docs/platform/dashboard/reference/supported-locales). ### `ignoreBrowserLocales` [#ignore-browser-locales] **Type** `boolean` · **Opcional** · **Predeterminado** `false` Cuando es `true`, se ignoran las preferencias `Accept-Language` del navegador al detectar la configuración regional. ### `disableInvalidLocaleWarning` [#disable-invalid-locale-warning] **Tipo** `boolean` · **Opcional** · **Predeterminado** `false` Cuando es `true`, se suprimen las advertencias sobre configuraciones regionales no válidas en la solicitud. ### `description` [#description] **Tipo** `string` · **Opcional** Una descripción en lenguaje natural de tu aplicación. Se envía como contexto para mejorar la calidad de las traducciones. ### `runtimeUrl` [#runtime-url] **Tipo** `string | null` · **Opcional** · **Predeterminado** runtime de General Translation URL base de la API de General Translation que se usa para la traducción on-demand. Configúrala como una cadena vacía para desactivar por completo la traducción en tiempo de ejecución. ### `cacheUrl` [#cache-url] **Tipo** `string | null` · **Opcional** · **Predeterminado** CDN de General Translation URL desde la que se sirven las traducciones almacenadas en caché. Haz que apunte a un servidor de caché personalizado o establécela en `null` para desactivar la carga remota. ### `cacheExpiryTime` [#cache-expiry-time] **Tipo** `number` · **Opcional** · **Predeterminado** `60000` Milisegundos que deben transcurrir antes de que caduquen las traducciones almacenadas en caché localmente. Este valor predeterminado se aplica a la carga remota en Production sin una clave de desarrollo. ### `loadTranslationsPath` [#load-translations-path] **Tipo** `string` · **Opcional** Ruta a un archivo `loadTranslations` personalizado para [traducciones locales](#translations). De forma predeterminada, el plugin localiza automáticamente un archivo `loadTranslations.[js|ts]` en la raíz de tu proyecto o en `src/`. ### `loadDictionaryPath` [#load-dictionary-path] **Tipo** `string` · **Opcional** Ruta a un archivo `loadDictionary` personalizado. De forma predeterminada, el plugin localiza automáticamente un archivo `loadDictionary.[js|ts]` en la raíz de tu proyecto o en `src/`. ### `dictionary` [#dictionary] **Tipo** `string` · **Opcional** Ruta a tu archivo de diccionario. Los archivos llamados `dictionary.[js|ts|json]` en la raíz del proyecto o en `src/` se reconocen automáticamente. ### `config` [#config-path] **Tipo** `string` · **Opcional** · **Predeterminado** `./gt.config.json` Ruta del archivo `gt.config.json` que se va a cargar. ### `renderSettings` [#render-settings] **Tipo** `{ method: 'skeleton' | 'replace' | 'default'; timeout?: number }` · **Opcional** Controla cómo se renderiza el contenido mientras se carga una traducción en tiempo de ejecución. Esto solo se aplica a las traducciones realizadas a demanda; las traducciones en caché se renderizan de inmediato. * `method` — uno de: * `skeleton` — no renderiza nada (un fragmento) mientras espera. * `replace` — renderiza el contenido del idioma predeterminado mientras espera. * `default` — se comporta como `replace` para configuraciones regionales del mismo idioma (como `en-US` y `en-GB`) y como `skeleton` para idiomas diferentes. * `timeout` — milisegundos antes de que el método de renderizado agote el tiempo de espera y vuelva al contenido original. El valor predeterminado es `8000` en desarrollo y `12000` en producción. ```ts title="next.config.ts" export default withGTConfig(nextConfig, { renderSettings: { method: 'skeleton', timeout: 10000, }, }); ``` ### `maxConcurrentRequests` [#max-concurrent-requests] **Tipo** `number` · **Opcional** · **Predeterminado** `100` Número máximo de solicitudes de traducción simultáneas a la API de General Translation. ### `maxBatchSize` [#max-batch-size] **Tipo** `number` · **Opcional** · **Predeterminado** `25` Número máximo de traducciones agrupadas en una sola solicitud en lote. ### `batchInterval` [#batch-interval] **Tipo** `number` · **Opcional** · **Predeterminado** `50` Milisegundos de espera entre solicitudes de traducción en lote para controlar la frecuencia de las solicitudes. ### `experimentalCompilerOptions` [#compiler-options] **Tipo** `object` · **Opcional** Configuración del plugin del compilador que analiza tu código fuente durante la compilación. Campos: | Campo | Descripción | Tipo | Predeterminado | | -------------------- | ------------------------------------------------------------------ | ---------------------------------------------------- | -------------- | | `type` | Qué plugin del compilador usar. | `'babel' \| 'swc' \| 'none'` | `'none'` | | `logLevel` | Nivel de detalle de los registros del compilador. | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | | `compileTimeHash` | Precalcula los hashes de traducción durante la compilación. | `boolean` | `true` | | `disableBuildChecks` | Desactiva las comprobaciones de validación durante la compilación. | `boolean` | `false` | ### `headersAndCookies` [#headers-and-cookies] **Tipo** `object` · **Opcional** Sobrescribe los nombres de la cabecera y la cookie que `gt-next` usa para transportar la configuración regional y el estado relacionado de la solicitud. Campos: `localeHeaderName`, `localeCookieName`, `enableI18nCookieName`, `referrerLocaleCookieName`, `localeRoutingEnabledCookieName` y `resetLocaleCookieName`. Cada uno usa de forma predeterminada el nombre estándar de la biblioteca. ### Rutas de las funciones de solicitud [#request-function-paths] **Tipo** `string` · **Opcional** `getLocalePath` y `getRegionPath` apuntan a implementaciones personalizadas de `getLocale` y `getRegion`, lo que te permite redefinir cómo se determinan la configuración regional y la región de la solicitud. ### `pathRegex` [#path-regex] **Tipo** `string` · **Opcional** Una cadena con el patrón de una expresión regular de JavaScript. Cuando se configura, el middleware de i18n y el límite de enrutamiento de configuración regional del cliente solo se ejecutan en las rutas que coinciden con ella; por ejemplo, `^/(?!uk(?:/|$)).*` para omitir todo lo que esté bajo `/uk`. Una expresión no válida genera un error en tiempo de compilación. Esto se configura aquí, en `withGTConfig`, no en [`createNextMiddleware`](/docs/react/nextjs/reference/functions/create-next-middleware); el plugin se lo pasa al middleware en tiempo de compilación. **Gestiona manualmente los aliases de configuración regional:** Las rutas filtradas omiten la normalización de la configuración regional. Si las configuraciones regionales que tienes configuradas son `en`, `en-GB` y `fr`, el segmento de ruta `uk` no se reconoce como `en-GB`. Una función `getLocale()` personalizada debe devolver `en-GB` para `uk`: ```ts title="getLocale.ts" import { locale } from 'next/root-params'; export default async function getLocale() { const pathnameLocale = await locale(); if (pathnameLocale === 'uk') return 'en-GB'; return pathnameLocale; } ``` Aplica el mismo mapping antes de llamar a `registerLocale()`: ```ts registerLocale(locale === 'uk' ? 'en-GB' : locale); ``` Si `getLocale()` o `registerLocale()` recibe una configuración regional desconocida, `gt-next` muestra una advertencia y usa `defaultLocale` como valor predeterminado. ### Opciones de ESLint [#eslint-options] * `eslint` (`boolean`, default `true`) — genera la configuración de ESLint de General Translation durante la configuración inicial. * `eslintSeverity` (`'error' | 'warn'`, default `'warn'`) — nivel de severidad de las reglas generadas. * `overwriteESLintConfig` (`boolean`, default `false`) — permite sobrescribir un archivo `eslint.config.mjs` existente. Consulta [Linting your code](/docs/react/guides/linting-your-code) para conocer las reglas. ## Traducciones locales vs. traducciones desde el CDN [#translations] De forma predeterminada, `gt-next` obtiene las traducciones desde el CDN de General Translation en tiempo de ejecución; el contenido traducido se sube allí automáticamente cuando ejecutas `npx gt translate`. Como alternativa, puedes incluir las traducciones en el bundle de tu aplicación y cargarlas localmente. Las traducciones locales cargan más rápido y funcionan sin conexión, a costa de un bundle más grande y de tener que volver a desplegar la aplicación con cada cambio de contenido. Para usarlas, agrega un archivo `loadTranslations` que devuelva las traducciones de una configuración regional: ```ts title="src/loadTranslations.ts" export default async function loadTranslations(locale: string) { const translations = await import(`../public/_gt/${locale}.json`); return translations.default; } ``` `withGTConfig` detecta automáticamente un archivo `loadTranslations.[js|ts]` en la raíz de tu proyecto o en el directorio `src/` (o define [`loadTranslationsPath`](#load-translations-path) explícitamente). Luego, haz que la CLI apunte al mismo directorio para que `npx gt translate` escriba los archivos allí. Consulta [Storing translations locally](/docs/react/guides/storing-translations) para ver el workflow completo. ## Devuelve [#returns] `withGTConfig` devuelve un objeto `NextConfig` mejorado con la configuración de General Translation. Lanza un error en tiempo de compilación si hay conflictos en la configuración, si falta una clave API obligatoria, si se usa una configuración regional no válida con los servicios de General Translation o si hay una clave de desarrollo presente en producción.