# General Translation React SDKs (gt-react, gt-next): Quickstart de React
URL: https://generaltranslation.com/es/docs/react/react-quickstart.mdx
---
title: Quickstart de React
description: Añade varios idiomas a una aplicación de React renderizada en el servidor con General Translation en menos de 10 minutos.
related:
links:
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
---
# Quickstart de React
Al final de esta guía, tu app de React renderizada en el servidor mostrará contenido en varios idiomas, con un selector de idioma con el que los usuarios podrán interactuar.
**Requisitos previos:**
* Una app de React renderizada en el servidor (React Router o una configuración SSR personalizada)
* Node.js 18+
**Nota:** Si tu app se renderiza por completo en el navegador con Vite, sigue el [React SPA Quickstart](/docs/react/react-spa-quickstart). Omite por completo el proveedor.
## Quickstart [#quickstart]
### 1. Instala los paquetes
`gt-react` es la biblioteca que gestiona las traducciones en tu aplicación. `gt` es la herramienta de CLI que prepara las traducciones para Production.
```bash
npm i gt-react
npm i -D gt
```
```bash
yarn add gt-react
yarn add --dev gt
```
```bash
bun add gt-react
bun add --dev gt
```
```bash
pnpm add gt-react
pnpm add --save-dev gt
```
### 2. Crea un archivo de configuración de traducción
Crea un archivo **`gt.config.json`** en la raíz de tu proyecto. Esto le indica a la biblioteca qué idiomas admites:
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "src/_gt/[locale].json"
}
}
}
```
* **`defaultLocale`** — el idioma en el que está escrita tu aplicación (tu idioma de origen).
* **`locales`** — los idiomas a los que quieres traducir. Elige cualquiera de la [lista de locales compatibles](/docs/platform/dashboard/reference/supported-locales).
* **`files`** — le indica al CLI dónde guardar los archivos de traducción. La ruta `output` debe coincidir con la ruta de importación de tu función `loadTranslations` (Paso 3).
### 3. Crear un loader de traducciones
Crea una función `loadTranslations` que cargue el archivo de traducción de la configuración regional. En el servidor, se ejecuta durante el renderizado; la CLI genera los archivos al ejecutar `npx gt translate`:
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
try {
const translations = await import(`./_gt/${locale}.json`);
return translations.default;
} catch (error) {
return {};
}
}
```
### 4. Inicializa la biblioteca
Llama a **`initializeGT`** a nivel de módulo en un archivo que se cargue tanto en el servidor como en el cliente; tu ruta raíz o layout es el lugar más natural. Registra tu configuración y el cargador de traducciones una sola vez; la configuración es inmutable durante todo el ciclo de vida de la aplicación:
```tsx title="src/routes/root.tsx"
import { initializeGT } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from '../loadTranslations';
initializeGT({
defaultLocale: gtConfig.defaultLocale,
locales: gtConfig.locales,
loadTranslations,
});
```
### 5. Carga las traducciones en el servidor
En el `loader` de tu ruta raíz (o en el manejador de solicitud equivalente del servidor), determina la configuración regional de la solicitud y obtén una instantánea de las traducciones con **`getTranslationsSnapshot`**; luego pasa ambas a **``**:
```tsx title="src/routes/root.tsx"
import {
GTProvider,
getTranslationsSnapshot,
parseLocale,
} from 'gt-react';
// En el loader de tu ruta (la API exacta depende de tu framework)
export async function loader({ request }) {
const locale = parseLocale(request); // [!code highlight]
return {
locale,
translations: await getTranslationsSnapshot(locale), // [!code highlight]
};
}
export default function Root({ children }) {
const { locale, translations } = useLoaderData();
return (
{children}
);
}
```
### 6. Marca el contenido para traducir
Envuelve cualquier texto que quieras traducir con el componente **``**. `` significa "traducir":
```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';
export default function Welcome() {
return (
Welcome to my app
This content will be translated automatically.
);
}
```
Para cadenas simples — como los atributos `placeholder` o los valores de `aria-label` — usa el hook **`useGT`**:
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Añade un selector de idioma
Inserta un **``** para que los usuarios puedan cambiar de idioma:
```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';
export default function Header() {
return ;
}
```
Cuando el usuario elige un idioma, `gt-react` guarda la elección en la cookie `generaltranslation.locale` y recarga la página para que el servidor vuelva a renderizarlo todo con la nueva configuración regional.
### 8. Configura las variables de entorno (opcional)
Las traducciones de desarrollo on-demand se ejecutan en el navegador. Expón el project ID y la development API key al código del cliente mediante las variables de entorno públicas de tu framework. Nunca expongas una production API key.
Con Vite, `gt-react` lee estas variables automáticamente:
```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```
Para otros frameworks, usa la convención de variables de entorno del cliente correspondiente y pasa los valores expuestos a `initializeGT`.
Obtén tus claves gratuitas en [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) o ejecutando:
```bash
npx gt auth
```
**Advertencia:** Para desarrollo, usa una clave que empiece por `gtx-dev-`. Las claves de producción (`gtx-api-`) son solo para CI/CD.
### 9. Despliega en producción
En producción, las traducciones se pregeneran durante la compilación (sin llamadas a la API en tiempo real). Agrega el comando translate a tu script de compilación:
```json title="package.json"
{
"scripts": {
"build": "npx gt translate && "
}
}
```
Configura las variables de entorno de **producción** en tu proveedor de hosting:
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
**Advertencia:** Las claves de Production empiezan por `gtx-api-` (no por `gtx-dev-`). Obtén una en [dash.generaltranslation.com](https://dash.generaltranslation.com). Nunca expongas públicamente tu `GT_API_KEY`.
Eso es todo: tu aplicación ahora es multilingüe. 🎉
## Solución de problemas [#troubleshooting]
`gt-react` guarda la preferencia de idioma del usuario en una cookie llamada `generaltranslation.locale`. Si antes hiciste pruebas con otro idioma, esta cookie puede anular tu selección. Borra las cookies y vuelve a intentarlo.
* [Chrome](https://support.google.com/chrome/answer/95647)
* [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
* [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
Esto es normal. En desarrollo, las traducciones se hacen on-demand (tu contenido se traduce en tiempo real a través de la API). Esta demora **no existe en producción**: todas las traducciones se pregeneran con `npx gt translate`.
Un texto ambiguo puede dar lugar a traducciones inexactas. Por ejemplo, "apple" podría referirse a la fruta o a la empresa. Agrega una prop `$context` para ayudar:
```jsx
Apple
```
Tanto `` como `useGT()` admiten la opción `$context`.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables