# General Translation React SDKs (gt-react, gt-next): Guía de inicio rápido de Next.js Pages Router
URL: https://generaltranslation.com/es/docs/react/nextjs-pages-router-quickstart.mdx
---

title: Guía de inicio rápido de Next.js Pages Router
description: Añade varios idiomas a una aplicación de Next.js Pages Router 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

---

# Inicio rápido de Pages Router en Next.js

Al final de esta guía, tu aplicación de Next.js con Pages Router mostrará contenido en varios idiomas, con un selector de idioma con el que tus usuarios podrán interactuar.

En Pages Router, `gt-next` funciona mediante `getServerSideProps`: en cada solicitud, el servidor resuelve la configuración regional del usuario, carga una instantánea de traducciones y pasa ambos a un `<GTProvider>` en `_app.tsx` para que el primer renderizado ya esté traducido.

La entrada `gt-next/server` es exclusiva de App Router y no funciona con Pages Router.

**Requisitos previos:**

* Una aplicación de Next.js que use **Pages Router**
* Node.js 18+

<Callout type="info">
  **Nota:** Si usas App Router, sigue la [guía de inicio rápido de Next.js App Router](/docs/react/nextjs-quickstart). Usa componentes de servidor y no requiere configurar `getServerSideProps`.
</Callout>

## Inicio rápido [#quickstart]

### 1. Instala los paquetes

`gt-next` es la biblioteca que habilita 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-next
    npm i -D gt
    ```
  </Tab>

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

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

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

### 2. Configura tu archivo de configuración de Next.js

`gt-next` usa un plugin de Next.js llamado **`withGTConfig`** para configurar la internacionalización durante la compilación. Envuelve con él tu configuración actual de Next.js:

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

const nextConfig = {};

export default withGTConfig(nextConfig);
```

Este plugin lee tu configuración de traducción y deja todo funcionando entre bastidores. Para las URL con prefijo de configuración regional, sigue la [guía de middleware de Pages Router](/docs/react/nextjs/pages-router-middleware).

### 3. 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 admite tu aplicación:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "public/_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.gt.output`** — donde el CLI guarda los archivos de traducción. `[locale]` se sustituye por cada código de idioma (p. ej., `public/_gt/es.json`).

Agrega `public/_gt/` a tu **`.gitignore`** — estos archivos se generan, no se escriben manualmente:

```txt title=".gitignore"
public/_gt/
```

### 4. Añade una función de carga para las traducciones locales

Crea un archivo **`loadTranslations`** en la raíz del proyecto (o en el directorio `src/`). Esto le indica a `gt-next` cómo cargar los archivos de traducción generados por la CLI:

```ts title="loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  try {
    const translations = await import(`./public/_gt/${locale}.json`);
    return translations.default;
  } catch {
    return {};
  }
}
```

`withGTConfig` detecta automáticamente un archivo `loadTranslations.[js|ts]` en la raíz de tu proyecto o en el directorio `src/`; no hace falta ninguna configuración adicional.

<Callout type="info">
  **Nota:** Las traducciones locales se empaquetan con tu app, por lo que se cargan al instante sin depender de servicios externos. Consulta [Almacenar traducciones](/docs/react/guides/storing-translations) para conocer los detalles y las consideraciones.
</Callout>

### 5. Envuelve getServerSideProps en tus páginas

Envuelve el `getServerSideProps` de cada página con **`withGTServerSideProps`**. En cada solicitud, determina la configuración regional del usuario — a partir de la cookie `generaltranslation.locale` si existe o, de lo contrario, de la cabecera `Accept-Language`—, carga una instantánea de translations para esa configuración regional e inyecta ambas en las props de tu página:

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // tus propios props
      },
    };
  }
);
```

Si una página no necesita sus propias props del lado del servidor, llámala sin argumentos:

```tsx title="pages/about.tsx"
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` agrega `configuración regional` y `translations` a tus props (además de una marca interna `enableI18n`). Si tu función interna devuelve un `redirect` o `notFound`, devuelve el resultado tal cual, sin cargar traducciones.

### 6. Añade el GTProvider a tu app

El componente **`GTProvider`** permite que toda tu app acceda a las traducciones. En `_app.tsx`, extrae de `pageProps` los props inyectados y pásalos al proveedor. El tipo **`WithGTServerSideProps`** describe la estructura inyectada:

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import { GTProvider, WithGTServerSideProps } from 'gt-next';

export default function App({
  Component,
  pageProps,
}: AppProps<WithGTServerSideProps>) {
  const { locale, translations, ...restPageProps } = pageProps;

  return (
    <GTProvider locale={locale} translations={translations}>
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

Como la configuración regional y las traducciones llegan con la respuesta del servidor, el primer renderizado ya se muestra en el idioma del usuario — sin estado de carga en el cliente.

### 7. Marca el contenido para traducir

Ahora, envuelve el texto que quieras traducir con el componente **`<T>`**. `<T>` significa &quot;traducir&quot;:

```tsx title="pages/index.tsx"
import { T } from 'gt-next';

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

Puedes envolver dentro de `<T>` tanto o tan poco JSX como quieras. Todo lo que contiene —texto, elementos anidados e incluso el formato— se traduce como una unidad.

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

Inserta un **`<LocaleSelector>`** para que los usuarios puedan cambiar de idioma:

```tsx title="pages/index.tsx"
import { T, LocaleSelector } from 'gt-next';

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

`LocaleSelector` renderiza un menú desplegable con los idiomas de tu `gt.config.json`. Cuando el usuario elige un idioma, `gt-next` guarda la selección en la cookie `generaltranslation.locale` y vuelve a cargar la página para que el servidor vuelva a renderizar todo con la nueva configuración regional.

### 9. Configura las variables de entorno (opcional)

Para ver las traducciones durante el desarrollo, necesitas API keys de General Translation. Estas permiten la **traducción on-demand**: tu aplicación traduce el contenido en tiempo real a medida que desarrollas.

Crea un archivo **`.env.local`**:

```bash title=".env.local"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

Obtén tus claves gratis en [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) o ejecuta:

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

  Nunca expongas `GT_API_KEY` en el navegador ni la subas al control de versiones.
</Callout>

### 10. Míralo en acción

Inicia tu servidor de desarrollo:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

Abre [http://localhost:3000](http://localhost:3000) y usa el menú desplegable de idioma para cambiar de idioma. Deberías ver tu contenido traducido.

<Callout type="info">
  **Nota:** En desarrollo, las traducciones se realizan bajo demanda, así que es posible que veas brevemente un estado de carga la primera vez que cambies a un idioma nuevo. En producción, las traducciones se pregeneran y se cargan al instante.
</Callout>

### 11. Traduce cadenas (no solo JSX)

Para cadenas de texto sin formato, como los atributos `placeholder`, los valores de `aria-label` o el texto `alt`, usa el hook **`useGT`**:

```tsx title="pages/contact.tsx"
import { useGT } from 'gt-next';

export default function ContactPage() {
  const gt = useGT();

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

### 12. Despliega en producción

En producción, las traducciones se generan previamente en tiempo de 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 && next build"
  }
}
```

Configura las variables de entorno de **producción** en tu proveedor de hosting (Vercel, Netlify, etc.):

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

<Callout type="warn">
  **Advertencia:** Las claves de producción empiezan por `gtx-api-` (no por `gtx-dev-`). Consigue una en [dash.generaltranslation.com](https://dash.generaltranslation.com). Nunca le pongas el prefijo `NEXT_PUBLIC_`.
</Callout>

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

## Solución de problemas [#troubleshooting]

<Accordions>
  <Accordion title="¿Necesito withGTServerSideProps en cada página?">
    Sí — `<GTProvider>` requiere las props `locale` y `translations`, y solo existen en las páginas cuyo `getServerSideProps` se ha envuelto. Para las páginas que no obtienen sus propios datos, exporta la versión sin argumentos:

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="¿Puedo usar getStaticProps en su lugar?">
    Sí. Envuelve la página con `withGTStaticProps` y sigue pasando las props generadas a `GTProvider` en `_app.tsx`. Consulta la [guía de generación estática de sitios con Pages Router](/docs/react/nextjs/pages-router-static-site-generation) para ver la configuración completa.
  </Accordion>

  <Accordion title="El idioma no cambia cuando uso el menú desplegable">
    `gt-next` almacena 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 bajo demanda (tu contenido se traduce en tiempo real mediante la API). Esta demora **no existe en producción** — todas las traducciones se generan previamente con `npx gt translate`.
  </Accordion>
</Accordions>
## Next steps

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