# General Translation React SDKs (gt-react, gt-next, gt-react-native): Quickstart de React
URL: https://generaltranslation.com/es/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Añade varios idiomas a una app de React renderizada en el servidor con General Translation en menos de 10 minutos.

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+

<Callout type="info">
  **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.
</Callout>

## 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.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 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`](/docs/react/reference/functions/load-translations) (Paso 3).

### 3. Crear un cargador de traducciones

Crea una función [`loadTranslations`](/docs/react/reference/functions/load-translations) 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`](/docs/cli/reference/commands/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`](/docs/react/reference/config#initialize)** 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`](/docs/react/reference/functions/get-translations-snapshot)**; luego pasa ambas a **[`<GTProvider>`](/docs/react/reference/components/gt-provider)**:

```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 (
    <GTProvider locale={locale} translations={translations}>
      {children}
    </GTProvider>
  );
}
```

### 6. Marca el contenido para traducir

Envuelve cualquier texto que quieras traducir con el componente **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) significa &quot;traducir&quot;:

```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';

export default function Welcome() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

Para cadenas simples — como los atributos `placeholder` o los valores de `aria-label` — usa el hook **[`useGT`](/docs/react/reference/hooks/use-gt)**:

```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';

export default function ContactForm() {
  const gt = useGT();
  return <input placeholder={gt('Enter your email')} />;
}
```

### 7. Añade un selector de idioma

Inserta un **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)** para que los usuarios puedan cambiar de idioma:

```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';

export default function Header() {
  return <LocaleSelector />;
}
```

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`](/docs/react/reference/config#initialize).

Obtén tus claves gratuitas en [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) o ejecutando:

```bash
npx gt auth
```

<Callout type="warn">
  **Advertencia:** Para desarrollo, usa una clave que empiece por `gtx-dev-`. Las claves de producción (`gtx-api-`) son solo para CI/CD.
</Callout>

### 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 && <YOUR_BUILD_COMMAND>"
  }
}
```

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
```

<Callout type="warn">
  **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`.
</Callout>

Eso es todo: tu aplicación ahora es multilingüe. 🎉

## Solución de problemas [#troubleshooting]

<Accordions>
  <Accordion title="El idioma no cambia cuando uso el menú desplegable">
    Confirma que las cookies del navegador estén habilitadas, que la configuración regional seleccionada aparezca en `gt.config.json` y que el selector se renderice bajo [`<GTProvider>`](/docs/react/reference/components/gt-provider). Si proporcionas un callback personalizado de [`_reload`](/docs/react/reference/components/gt-provider#reload), verifica que recargue o navegue después de la selección.
  </Accordion>

  <Accordion title="Las traducciones son lentas en desarrollo">
    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`](/docs/cli/reference/commands/translate).
  </Accordion>

  <Accordion title="Algunas traducciones son inexactas">
    Un texto ambiguo puede dar lugar a traducciones inexactas. Por ejemplo, &quot;apple&quot; podría referirse a la fruta o a la empresa. Agrega una prop `$context` para ayudar:

    ```jsx
    <T $context="the technology company">Apple</T>
    ```

    Tanto [`<T>`](/docs/react/reference/components/t) como [`useGT()`](/docs/react/reference/hooks/use-gt) admiten la opción `$context`.
  </Accordion>
</Accordions>

## Next steps

- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.