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
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 a través de tu servidor de desarrollo local. Usa una [project API key](/docs/platform/dashboard/reference/api-keys#create-project-keys) con permiso de runtime translation. Una clave de acceso completo funciona, pero recomendamos permisos **Custom** con solo **Runtime translation** habilitado para minimizar riesgos. Expón la clave y el ID del Project mediante las variables de entorno públicas de tu framework únicamente en el desarrollo local.

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="gtx-api-your-runtime-key"
```

Para otros frameworks, usa su convención de variables de entorno del cliente y pasa los valores expuestos a [`initializeGT`](/docs/react/reference/config#initialize).

El ajuste `VITE_GT_DEV_API_KEY` habilita la recarga en caliente en desarrollo y acepta una clave de Project con alcance limitado que comienza con `gtx-api-`.

<Callout type="warn">
  **Advertencia:** Nunca incluyas ninguna API key en bundles de navegador o de aplicaciones móviles desplegados, ni siquiera una clave exclusiva de runtime. Excluye `VITE_GT_DEV_API_KEY` de las compilaciones de producción.
</Callout>

### 9. Despliega en Production

En Production, 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 **Production** en tu proveedor de hosting:

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  **Advertencia:** Usa una clave de Project independiente con **Files &gt; Write** y **Translation queue &gt; Enabled** para el CLI. Nunca expongas públicamente `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>
    ```

    [`<T>`](/docs/react/reference/components/t) recibe `context` como prop. Pasa la misma cadena aclaratoria en la opción `$context` cuando llames a [`useGT()`](/docs/react/reference/hooks/use-gt).
  </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.