# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuración URL: https://generaltranslation.com/es/docs/react/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt Description: Configura el ecosistema de React con el archivo compartido gt.config.json y la inicialización en Runtime. Referencia 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 render. 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 estos campos compartidos: | 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]` | | [`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`](/docs/react/reference/functions/load-dictionary). | `object` | Sí | — | | `projectId` | ID del proyecto de General Translation para la CDN y la traducción de 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 de desarrollo. | `string \| null` | Sí | GT runtime | | `customMapping` | aliases de configuración regional y sobrescrituras de propiedades. | `object` | Sí | — | | [`_tagIds`](#tag-ids) | Expone cada hash de traducción de [``](/docs/react/reference/components/t) como un atributo DOM `data-_gt-hash`. | `boolean` | Sí | `false` | ### `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 traducciones, 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. También acepta estos campos exclusivos del navegador: | Opción | Descripción | Tipo | Opcional | Predeterminado | | ----------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------- | -------------- | | `locale` | Configuración regional inicial explícita. Omite la detección cuando se establece. | `string` | Sí | Detectada | | `region` | Código de región inicial para el formateo según la región. | `string` | Sí | — | | `enableI18n` | Traduce el contenido. Cuando es `false`, renderiza la configuración regional de origen. | `boolean` | Sí | `true` | | [`htmlTagOptions`](#htmltagoptions) | Campo de compatibilidad que no actualiza automáticamente el elemento HTML. | `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` | Sí | — | ```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. Actualiza los atributos `lang` y `dir` del elemento `` en tu aplicación cuando cambie la configuración regional. #### `htmlTagOptions` **Tipo** `{ updateHtmlLangTag?: boolean; updateHtmlDirTag?: boolean }` · **Opcional** Campo de compatibilidad exclusivo para navegadores aceptado por `initializeGTSPA`. Pasarlo no actualiza automáticamente los atributos `lang` ni `dir` del elemento `` cuando cambia la configuración regional; actualiza esos atributos en tu aplicación. ## `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í | — | | [`localeRouting`](#locale-routing) | Mantén la configuración regional activa en el nombre de ruta. | `boolean` | Sí | Específico del framework | | [`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 producción. | `boolean` | Sí | `false` | | [`files`](#files) | Rutas de archivos de traducción local e indicadores de análisis. | `object` | Sí | — | | [`_tagIds`](#tag-ids) | Expone cada hash de traducción de [``](/docs/react/reference/components/t) como un atributo DOM `data-_gt-hash`. | `boolean` | Sí | `false` | | [`_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']`. ### `localeRouting` [#locale-routing] **Tipo** `boolean` · **Opcional** · **Predeterminado** específico del framework Controla las URL con prefijo de configuración regional en TanStack Start. Es una opción de activación explícita y su valor predeterminado es `false`. Esta opción no define rutas: configura parámetros de path opcionales `/{-$locale}` o reescrituras de URL para que TanStack Router acepte tanto URL sin prefijo como URL con prefijo de configuración regional. Consulta la [guía de configuración de TanStack Start](/docs/react/tanstack-start/setup#locale-routing). Una vez habilitada, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) prioriza el primer segmento de path compatible, la configuración regional predeterminada permanece sin prefijo y los cambios de configuración regional en el cliente recargan la ruta correspondiente. Next.js configura el enrutamiento por separado mediante [`createNextMiddleware({ localeRouting })`](/docs/react/nextjs/reference/functions/create-next-middleware), cuyo valor predeterminado es `true`. Esta opción no afecta a las SPAs de React simples ni a React Native. ### `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`. ## `_tagIds` [#tag-ids] **Tipo** `boolean` · **Opcional** · **Predeterminado** `false` Habilita el etiquetado de identificadores del DOM para la salida renderizada de [``](/docs/react/reference/components/t) y [``](/docs/react/nextjs/reference/components/tx) en `gt-react`, `gt-next` y `gt-tanstack-start`. Herramientas como la reproducción localizada y el control de calidad en contexto usan el atributo `data-_gt-hash` para asociar un nodo renderizado con su traducción. Configura `_tagIds` en el archivo de configuración compartido y, a continuación, pasa esa configuración a [`initializeGT`](#initialize) o [`initializeGTSPA`](#initialize-spa). El plugin `withGTConfig` lee el mismo archivo en Next.js: ```json title="gt.config.json" { "_tagIds": true } ``` El valor debe ser literalmente `true`. Cualquier otro valor, incluido un valor veraz que no sea booleano, mantiene el etiquetado desactivado. React Native acepta el campo de configuración compartido, pero omite el etiquetado del DOM. **Activar esta opción puede añadir elementos contenedores.** La inyección de `span` se reduce al mínimo აუცილario: * **Un único elemento anfitrión** (por ejemplo, `…`) se anota en el mismo documento. No se añade ningún contenedor, por lo que el marcado sigue siendo válido dentro de elementos padre restringidos como ``, `