Welcome to my app

# General Translation React SDKs (gt-react, gt-next, gt-react-native): Quickstart de React
URL: https://generaltranslation.com/es/docs/react/react-quickstart.mdx
---
title: Quickstart de React
description: Añade varios idiomas a una app 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

---

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">
    `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)
  </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