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

title: Inicio rápido de Pages Router en Next.js
description: Agrega varios idiomas a una aplicación de Next.js con Pages Router usando 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 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>`](/docs/react/reference/components/gt-provider) 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. 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": ["en", "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`** — todas las configuraciones regionales disponibles en tu aplicación. Incluye `defaultLocale` porque el enrutamiento internacionalizado de Next.js lo requiere y, luego, agrega los idiomas a los que quieres traducir. Elige cualquiera de la [lista de configuraciones regionales 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/
```

### 3. Configura el enrutamiento internacionalizado de Next.js

El Pages Router usa el [enrutamiento internacionalizado de Next.js](https://nextjs.org/docs/pages/guides/internationalization) para las URL con prefijo de configuración regional y detectar la configuración regional de la solicitud. Importa la configuración regional en `next.config.ts` y, a continuación, envuelve la configuración con `withGTConfig`:

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

const nextConfig: NextConfig = {
  i18n: {
    locales: gtConfig.locales,
    defaultLocale: gtConfig.defaultLocale,
  },
};

export default withGTConfig(nextConfig);
```

Next.js mantiene la configuración regional predeterminada en `/` y añade prefijos a las demás, como `/es` y `/fr`. No necesitas el middleware de `gt-next` ni un segmento de ruta `pages/[locale]`. Consulta [enrutamiento de configuraciones regionales en Pages Router](/docs/react/nextjs/pages-router-middleware) para obtener información sobre la detección y la migración.

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

Crea un archivo **[`loadTranslations`](/docs/react/reference/functions/load-translations)** 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 {};
  }
}
```

<Callout type="info">
  **Nota:** Estos archivos de traducción no existen hasta que los crees con [`npx gt generate`](/docs/cli/reference/commands/generate) (no se necesita ninguna API Key) o [`npx gt translate`](/docs/cli/reference/commands/translate) (con credenciales). Hasta entonces, el empaquetador advertirá que falta el directorio `public/_gt`, y el `try`/`catch` de arriba devolverá `{}` para que la app siga ejecutándose con contenido sin traducir.
</Callout>

`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, lee la configuración regional que Next.js resolvió en `context.locale`, carga una instantánea de traducciones 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`](/docs/react/reference/components/gt-provider)** 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 Router from 'next/router';
import { GTProvider, type WithGTServerSideProps } from 'gt-next';

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

  return (
    <GTProvider
      locale={locale}
      translations={translations}
      _reload={({ locale: nextLocale }) => {
        void Router.push(Router.pathname, Router.asPath, {
          locale: nextLocale,
        });
      }}
    >
      <Component {...pageProps} />
    </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. El callback `_reload` notifica los cambios de configuración regional al enrutador de Next.js para que cargue los props de página de la configuración regional seleccionada.

### 7. Marca el contenido para traducir

Ahora, envuelve el 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="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>`](/docs/react/reference/components/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>`](/docs/react/reference/components/locale-selector)** 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`](/docs/react/reference/components/locale-selector) renderiza un menú desplegable con los idiomas de tu `gt.config.json`. Cuando el usuario elige un idioma, el callback en `_app.tsx` navega a la URL localizada y Next.js guarda la selección en la cookie `NEXT_LOCALE`. Luego, el servidor renderiza la configuración regional seleccionada.

### 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/en-US/signin) 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`](/docs/react/reference/hooks/use-gt)**:

```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>`](/docs/react/reference/components/gt-provider) 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`](/docs/react/reference/components/gt-provider) 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">
    Confirma que `_reload` llame a `Router.push` con la opción `locale` seleccionada, como se muestra arriba. Tras seleccionar una opción, la URL debe incluir el prefijo de configuración regional y la cookie `NEXT_LOCALE` debe contener esa configuración regional.
  </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 pregeneran con [`npx gt translate`](/docs/cli/reference/commands/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