# gt-next: General Translation Next.js SDK: Inicio rápido de Pages Router
URL: https://generaltranslation.com/es/docs/next/tutorials/quickstart-pages-router.mdx
---
title: Inicio rápido de Pages Router
description: Agrega varios idiomas a tu aplicación Next.js con Pages Router en menos de 10 minutos
---

Al final de esta guía, tu aplicación 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 determina la configuración regional del usuario, carga una instantánea de traducciones y pasa ambas a un `<GTProvider>` en `_app.tsx` para que el primer renderizado ya aparezca traducido.

**Requisitos previos:**

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

<Callout type="info">
  **¿Usas App Router?** Sigue la [guía de inicio rápido de Next.js](/docs/next) en su lugar: usa componentes de servidor y no requiere configuración de `getServerSideProps`.
</Callout>

***

## Paso 1: Instala los paquetes

`gt-next` es la biblioteca que potencia las traducciones en tu aplicación. `gt` es la CLI que prepara las traducciones para producción.

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

***

## Paso 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 en tiempo de compilación. Úsalo para envolver 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 lo conecta todo en segundo plano. La configuración es idéntica para App Router y Pages Router; no se necesitan flags específicas del router.

***

## Paso 3: Crea un archivo de configuración de traducción

Crea el archivo **`gt.config.json`** en la raíz de tu proyecto. Esto le indica a la biblioteca qué idiomas son compatibles:

```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 app (tu idioma de origen).
* **`locales`** — los idiomas a los que quieres traducir. Elige cualquiera de la [lista de locales compatibles](/docs/platform/supported-locales).
* **`files.gt.output`** — dónde guarda el CLI los archivos de traducción. `[locale]` se reemplaza con 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/
```

***

## Paso 4: Añade una función `load` para las traducciones locales

Crea un archivo **`loadTranslations`** en la raíz de tu 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/`, sin necesidad de configuración adicional.

<Callout type="info">
  **¿Por qué traducciones locales?** Las traducciones locales se incluyen con tu app, por lo que se cargan al instante sin depender de servicios externos. Consulta la [guía de almacenamiento local de traducciones](/docs/next/guides/local-tx) para más detalles y conocer sus ventajas e inconvenientes.
</Callout>

***

## Paso 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 está definida, o, en caso contrario, de la cabecera `Accept-Language` —, 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` añade `locale` y `translations` a tus props (además de un indicador interno `enableI18n`). Si tu función interna devuelve un `redirect` o `notFound`, devuelve el resultado sin modificar, sin cargar traducciones.

***

## Paso 6: Añade GTProvider a tu aplicación

El componente **`GTProvider`** da acceso a las traducciones a toda tu aplicación. En `_app.tsx`, extrae las `props` inyectadas de `pageProps` y pásalas 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 aparece en el idioma del usuario, sin estado de carga del lado del cliente.

***

## Paso 7: Marca el contenido para traducir

Ahora, envuelve cualquier 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 hay dentro —texto, elementos anidados e incluso el formato— se traduce como una sola unidad.

***

## Paso 8: Añade un selector de idioma

Añade 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 recarga la página para que el servidor vuelva a renderizar todo en la nueva configuración regional.

***

## Paso 9: Configura las variables de entorno (opcional)

Para ver las traducciones durante el desarrollo, necesitas API keys de General Translation. Estas habilitan la **traducción on-demand**: tu app traduce el contenido en tiempo real mientras 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">
  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>

***

## Paso 10: Comprueba que funciona

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">
  En desarrollo, las traducciones se realizan bajo demanda; puede que veas un breve indicador de carga la primera vez que cambies a un idioma nuevo. En producción, las traducciones se generan de antemano y se cargan al instante.
</Callout>

***

## Paso 11: Traducir cadenas (no solo JSX)

Para cadenas de texto simples —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>
  );
}
```

***

## Paso 12: Despliega en producción

En producción, las traducciones se generan de antemano 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 && 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">
  Las claves de producción comienzan con `gtx-api-` (no `gtx-dev-`). Obtén 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

<Accordions>
  <Accordion title="¿Necesito withGTServerSideProps en cada página?">
    Sí: `<GTProvider>` requiere las props `locale` y `translations`, y solo están disponibles en las páginas donde `getServerSideProps` está envuelto. En las páginas que no cargan sus propios datos, exporta la versión sin argumentos:

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

  <Accordion title="¿Puedo usar getStaticProps en su lugar?">
    No. Para resolver la configuración regional se necesitan datos por solicitud (la cookie de configuración regional y la cabecera `Accept-Language`), que no están disponibles durante la generación estática. `gt-next` no ofrece ningún helper para `getStaticProps` en el Pages Router.
  </Accordion>

  <Accordion title="El idioma no cambia cuando uso el menú desplegable">
    `gt-next` guarda la preferencia de idioma del usuario en una cookie llamada `generaltranslation.locale`. Si antes probaste con otro idioma, es posible que esta cookie anule 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 a través de la API). Esta demora **no existe en producción**: todas las traducciones se generan previamente con `npx gt translate`.
  </Accordion>
</Accordions>

***

## Siguientes pasos

* [**Guía del componente `<T>`**](/docs/next/guides/t) — Aprende sobre variables, plurales y patrones avanzados de traducción
* [**Guía de traducción de cadenas**](/docs/next/guides/strings) — Profundiza en `useGT`
* [**Componentes variables**](/docs/next/guides/variables) — Gestiona contenido dinámico con `<Var>`, `<Num>`, `<Currency>` y `<DateTime>`
* [**Pluralización**](/docs/next/api/components/plural) — Gestiona las formas plurales con el componente `<Plural>`
* [**Despliegue en producción**](/docs/next/tutorials/quickdeploy) — Configuración de CI/CD, caché y optimización del rendimiento
* [**Cadenas compartidas**](/docs/next/guides/shared-strings) — Traduce texto en arrays, objetos de configuración y datos compartidos con `msg()`