# General Translation React SDKs (gt-react, gt-next): Configuración URL: https://generaltranslation.com/es/docs/react/reference/config.mdx --- title: Configuración description: Configura General Translation en todo el ecosistema de React con el archivo compartido gt.config.json y la inicialización en Runtime. Referencia de la API para gt.config.json. --- General Translation se configura en dos partes: un archivo `gt.config.json` que contiene la configuración regional y los ajustes de archivos que compartes con la [CLI](/docs/cli/reference/config), y un paso de configuración en Runtime que carga esa configuración antes del primer renderizado. El archivo `gt.config.json` es el mismo en todo el ecosistema de React; la configuración en Runtime varía según el framework. *La referencia de `gt.config.json` en esta página es compartida por `gt-react`, `gt-next`, `gt-tanstack-start` y `gt-react-native`. Las funciones de inicialización ([`initializeGT`](#initialize), [`initializeGTSPA`](#initialize-spa)) son para `gt-react`; `gt-tanstack-start` y `gt-react-native` también usan `initializeGT`.* *Nota: `gt-next` no usa estas funciones de inicialización, sino que lee la configuración mediante el plugin `withGTConfig`, documentado en la sección de Next.js.* ## Descripción general [#overview] Una aplicación `gt-react` renderizada en el servidor se configura en tres pasos: inicializar la biblioteca, cargar las traducciones de la configuración regional activa y envolver el árbol con [``](/docs/react/reference/components/gt-provider). * **Inicializa** con [`initializeGT`](#initialize) las aplicaciones renderizadas en el servidor. Las aplicaciones de una sola página usan [`initializeGTSPA`](#initialize-spa), que también determina la configuración regional activa a partir de las cookies y del navegador. * **Carga las traducciones** de la configuración regional activa con [`getTranslationsSnapshot`](/docs/react/reference/functions/get-translations-snapshot). * **Proporciona** la configuración regional y las traducciones a tus componentes con [``](/docs/react/reference/components/gt-provider). ```tsx title="src/routes/root.tsx" import { initializeGT, getTranslationsSnapshot, parseLocale } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } ``` El archivo `gt.config.json` contiene la configuración compartida de la configuración regional y de los archivos. Tanto la llamada de inicialización como la CLI leen los mismos valores, así que consérvalos en un solo lugar. ## Inicialización [#initialization] | Función | Descripción | Tipo | Opcional | Predeterminado | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ---------- | -------- | -------------- | | [`initializeGT`](#initialize) | Inicializa sin detección de configuración regional del navegador, para apps renderizadas en el servidor. | `function` | No | — | | [`initializeGTSPA`](#initialize-spa) | Inicializa una aplicación de una sola página, incluida la detección de configuración regional del navegador. | `function` | No | — | Ambas funciones aceptan los campos siguientes. Comparten las mismas opciones, excepto que solo `initializeGTSPA` realiza la detección de configuración regional del navegador. | Opción | Descripción | Tipo | Opcional | Predeterminado | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ----------------- | | `defaultLocale` | Configuración regional de origen desde la que se traduce. | `string` | Sí | `en` | | `locales` | Configuraciones regionales de destino compatibles. | `string[]` | Sí | `[defaultLocale]` | | `locale` | Configuración regional inicial explícita. Omite la detección cuando se establece. | `string` | Sí | Detectada | | [`loadTranslations`](/docs/react/reference/functions/load-translations) | Loader que devuelve las traducciones de una configuración regional. Documento: [`loadTranslations`](/docs/react/reference/functions/load-translations). | `(locale: string) => Promise` | Sí | GT CDN | | [`loadDictionary`](/docs/react/reference/functions/load-dictionary) | Loader que devuelve un diccionario para una configuración regional. Documento: [`loadDictionary`](/docs/react/reference/functions/load-dictionary). | `(locale: string) => Promise` | Sí | — | | `dictionary` | Diccionario inline, como alternativa a `loadDictionary`. | `object` | Sí | — | | `projectId` | ID del proyecto de General Translation para la CDN y la traducción en desarrollo. | `string` | Sí | — | | `devApiKey` | Development API key para traducción on-demand y hot reload. | `string` | Sí | — | | `apiKey` | Production API key. En el navegador, se prefiere `devApiKey`. | `string` | Sí | — | | `cacheUrl` | Host personalizado para las traducciones. `null` desactiva la carga remota. | `string \| null` | Sí | GT CDN | | `runtimeUrl` | Host de traducción runtime, usado para la traducción en desarrollo. | `string \| null` | Sí | GT runtime | | `customMapping` | aliases de configuración regional y sobrescrituras de propiedades. | `object` | Sí | — | | `region` | Código de región inicial para formatos dependientes de la región. | `string` | Sí | — | | `enableI18n` | Traduce el contenido. Cuando es `false`, renderiza la configuración regional de origen. | `boolean` | Sí | `true` | | `htmlTagOptions` | Si se deben sincronizar los atributos `lang` y `dir` de `` cuando cambia la configuración regional. | `object` | Sí | — | ### `initializeGT` [#initialize] **Type** `(config) => void` · **Obligatorio** Inicializa la configuración y la caché de traducciones sin detección de la configuración regional del navegador. Úsalo en entornos renderizados en el servidor donde tu framework proporciona la configuración regional de la solicitud y las traducciones. ```tsx initializeGT({ ...gtConfig, loadTranslations, }); ``` ### `initializeGTSPA` [#initialize-spa] **Tipo** `(config) => Promise` · **Obligatorio** Inicializa `gt-react` en una aplicación de una sola página. Llámalo una sola vez, antes del primer render. Crea la caché de traducción, detecta la configuración regional activa a partir de las cookies y del navegador, y precarga las traducciones. Disponible solo en el punto de entrada del navegador. ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, locale: gtConfig.defaultLocale, }); ``` Como obtiene la configuración regional del entorno, `initializeGTSPA` devuelve una promesa: espérala con `await` antes de renderizar. Usa `htmlTagOptions` para controlar si los atributos `lang` y `dir` del elemento `` se actualizan cuando cambia la configuración regional: ```tsx await initializeGTSPA({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // predeterminado: true updateHtmlDirTag: true, // predeterminado: true }, }); ``` ## `gt.config.json` [#config-file] `gt.config.json` está en la raíz de tu proyecto y contiene la configuración regional y los ajustes de archivos que se comparten con la CLI. Impórtalo y pasa sus campos a la inicialización. | Clave | Descripción | Tipo | Opcional | Predeterminado | | ------------------------------------------ | ------------------------------------------------------------------- | ---------- | -------- | -------------- | | [`projectId`](#project-id) | ID del proyecto de General Translation. | `string` | Sí | — | | [`defaultLocale`](#default-locale) | Configuración regional de origen. | `string` | Sí | `en` | | [`locales`](#locales) | Configuraciones regionales de destino. | `string[]` | Sí | — | | [`customMapping`](#custom-mapping) | Alias de configuración regional y sobrescrituras de propiedades. | `object` | Sí | — | | [`cacheUrl`](#cache-url) | URL base de las traducciones en caché. | `string` | Sí | GT CDN | | [`runtimeUrl`](#runtime-url) | URL base de las traducciones de Runtime (desarrollo). | `string` | Sí | GT runtime | | [`stageTranslations`](#stage-translations) | Requiere revisión antes de que las traducciones pasen a Production. | `boolean` | Sí | `false` | | [`files`](#files) | Rutas de archivos de traducción local e indicadores de análisis. | `object` | Sí | — | | [`_versionId`](#version-id) | Identificador interno de la versión de traducción. No lo edites. | `string` | Sí | — | ### `projectId` [#project-id] **Tipo** `string` · **Opcional** Identificador único de tu proyecto en General Translation. Necesario para la entrega mediante CDN y la traducción de desarrollo bajo demanda. ### `defaultLocale` [#default-locale] **Tipo** `string` · **Opcional** · **Predeterminado** `en` La configuración regional de origen en la que está escrita tu interfaz de usuario. Se usa como contenido alternativo cuando falta una traducción. ### `locales` [#locales] **Tipo** `string[]` · **Opcional** Las configuraciones regionales de destino que admite tu proyecto, en códigos BCP 47 como `['es', 'fr']`. ### `customMapping` [#custom-mapping] **Tipo** `object` · **Opcional** Alias de configuraciones regionales y sobrescrituras de propiedades, para renombrar o personalizar cómo se resuelven y se muestran las configuraciones regionales. ### `cacheUrl` [#cache-url] **Type** `string` · **Opcional** · **Predeterminado** GT CDN URL base desde la que se obtienen traducciones en caché. Configúrala para que apunte a tu propio host o pasa `null` en la llamada de inicialización para desactivar la carga remota. ### `runtimeUrl` [#runtime-url] **Tipo** `string` · **Opcional** · **Predeterminado** GT runtime URL base del servicio de traducción en runtime. Esto solo se aplica a las traducciones de desarrollo. ### `stageTranslations` [#stage-translations] **Tipo** `boolean` · **Opcional** · **Predeterminado** `false` Cuando es `true`, la herramienta `gt` marca las traducciones para revisión. Deben aprobarse antes de poder desplegarse en producción mediante [`gt translate`](/docs/cli/reference/commands/translate). ### `files` [#files] **Tipo** `object` · **Opcional** Indica dónde se escriben las traducciones almacenadas localmente, como alternativa a almacenarlas en la nube. `files.gt.output` es una plantilla de ruta que contiene `[locale]`, y `files.gt.parsingFlags` controla cómo el compilador analiza tu código fuente. ```json title="gt.config.json" { "files": { "gt": { "output": "src/_gt/[locale].json", "parsingFlags": { "enableAutoJsxInjection": true, "autoderive": true } } } } ``` * `enableAutoJsxInjection` (`boolean`, default `false`) — envuelve automáticamente el texto JSX traducible en componentes de traducción en tiempo de compilación. Consulta [auto JSX injection](/docs/cli/guides/using-auto-jsx). * `autoderive` (`boolean`, default `false`) — trata automáticamente los valores interpolados en las llamadas a [`t()`](/docs/react/reference/functions/t-function), `gt()` y [`msg()`](/docs/react/reference/functions/msg) como llamadas a [`derive()`](/docs/react/reference/functions/derive). Consulta [autoderive](/docs/cli/guides/using-autoderive). Consulta la [referencia de configuración de la CLI](/docs/cli/reference/config) para ver el esquema completo de `files`. ### `_versionId` [#version-id] **Tipo** `string` · **Opcional** Identificador interno que usa el CLI para llevar el seguimiento de la versión de la traducción, lo que permite volver a traducciones anteriores. Se genera automáticamente; no lo edites. Las claves con prefijo de guion bajo son internas. ## Ejemplos [#examples] ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "gt": { "output": "src/_gt/[locale].json" } } } ``` ```tsx title="src/routes/root.tsx" import { GTProvider, initializeGT, getTranslationsSnapshot, parseLocale, } from 'gt-react'; import gtConfig from '../../gt.config.json'; const loadTranslations = (locale: string) => import(`../_gt/${locale}.json`).then((m) => m.default); initializeGT({ ...gtConfig, loadTranslations }); export async function loadRoot(request: Request) { const locale = parseLocale(request); return { locale, translations: await getTranslationsSnapshot(locale), }; } export function Root({ locale, translations, children }) { return ( {children} ); } ```