# General Translation Knowledge Base: ¿Cómo agrego i18n a una aplicación de Next.js con App Router?
URL: https://generaltranslation.com/es/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Empieza con gt init para configurar General Translation en un proyecto compatible con App Router; luego marca el contenido de origen, genera las traducciones y verifica el cambio de idioma. gt-next mantiene el texto en JSX junto con el contexto de traducción; la CLI, el editor del panel de control y Locadex se encargan de la generación, la revisión y las actualizaciones continuas. Esta guía también muestra la configuración inicial explícita con archivos locales.
Category: Internacionalización
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

En este tutorial se añaden inglés, español y francés a una pequeña página de proyecto. Incluye un Componente de servidor, un Componente de cliente y un selector de idioma. La selección de idioma se basa en cookies; las URL con prefijo de configuración regional y el SEO multilingüe se tratan por separado.

`gt-next` de General Translation está diseñado para el App Router de Next.js. Mantiene el texto de origen en el JSX que le da sentido y conecta ese contenido con la generación de traducciones. Usa la [prop `context`](/docs/react/reference/components/t#context) para aclarar expresiones ambiguas y asigna [términos del glosario y prompts personalizados](/docs/platform/dashboard/guides/defining-context-for-translations) para controlar la terminología y el tono. Después, el flujo de trabajo de compilación que se describe a continuación actualiza las traducciones a medida que cambia el contenido de origen.

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51 s)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## Antes de empezar

Usa un proyecto existente de TypeScript con App Router que tenga un directorio `src/app`. Los ejemplos están pensados para Next.js 16 y usan npm. Next.js 16 requiere Node.js 20.9 o posterior. Si empiezas desde cero, sigue primero la [guía de instalación de Next.js](https://nextjs.org/docs/app/getting-started/installation). Para aplicaciones con Pages Router, consulta el [inicio rápido de Pages Router](/docs/react/nextjs-pages-router-quickstart).

El ejemplo explícito usa `gt-next@11.4.12` y `gt@2.26.5`. La biblioteca, con licencia MIT, puede renderizar las traducciones que tú proporciones sin necesidad de una cuenta. Para usar traducciones generadas por el servicio, necesitas un proyecto de GT y [iniciar sesión en la CLI o una clave de herramientas con ámbito limitado](/docs/cli/guides/configuring#credentials). En compilaciones automatizadas, usa una clave guardada en el almacén de secretos de tu CI.

## Empieza con el comando de configuración inicial

Ejecuta el asistente de configuración inicial en el directorio de la app:

```bash
npx gt@2.26.5 init
```

Elige la configuración inicial del framework React para tu app con App Router, los idiomas de origen y de destino, y la entrega local o mediante CDN. El asistente instala `gt-next`, añade [`GTProvider`](/docs/react/reference/components/gt-provider) y [`withGTConfig`](/docs/react/nextjs/config), y crea `gt.config.json`. Si eliges la entrega local, también crea un cargador de traducciones. La reescritura del framework es experimental; revisa el diff generado, sobre todo en lo relativo a los proveedores y envoltorios de configuración que ya tengas. [Referencia de configuración inicial](/docs/cli/reference/commands/init).

Después, tendrás que marcar el contenido de la aplicación y generar sus traducciones. Si prefieres que un agente de programación complete la tarea hasta la verificación, usa [Configuración inicial para agentes](https://generaltranslation.com/agent-prompt.md).

La configuración inicial explícita que se describe a continuación usa `src/_gt/[locale].json`. La salida local predeterminada del asistente es `public/_gt/[locale].json`; mantén el cargador generado junto con su ruta de salida, o sigue la configuración inicial explícita como alternativa completa.

## Configura la biblioteca de forma explícita y escribe la página

### 1. Instala el SDK y la CLI

Ejecuta estos comandos en el directorio de la aplicación:

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` renderiza las traducciones en la aplicación. `gt` es la herramienta de línea de comandos que se usa para recopilar y traducir el contenido de origen. [Inicio rápido oficial de Next.js](/docs/react/nextjs-quickstart).

### 2. Configura Next.js y tus idiomas

Envuelve tu configuración actual de Next.js con [`withGTConfig`](/docs/react/nextjs/config). Mantén los ajustes que ya tengas e intégralo con cualquier otro envoltorio de configuración que ya utilices.

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

export default withGTConfig({});
```

Crea este archivo en la raíz del proyecto:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

El inglés es el idioma de origen. El español y el francés son los idiomas de destino. La ruta de salida indica a la CLI dónde escribir las traducciones generadas.

### 3. Agrega un cargador de traducciones local

Crea `src/loadTranslations.ts`. El plugin de configuración detecta este archivo y lo utiliza para cargar los archivos de configuración regional generados:

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

Esta configuración inicial incluye las traducciones en el paquete de la aplicación, por lo que en producción no se necesitan llamadas en tiempo de ejecución a General Translation para este contenido. Las actualizaciones de las traducciones se publican con cada compilación. [Almacenamiento local de traducciones](/docs/react/guides/storing-translations).

Los archivos aún no existen. Completa la página y genéralos en el paso 6 antes de iniciar el servidor de desarrollo; de lo contrario, la importación del cargador podría fallar.

### 4. Añade el proveedor a tu layout raíz

Adapta `src/app/layout.tsx` como se muestra a continuación. Conserva los estilos, las fuentes, los metadatos y los demás proveedores que ya tengas.

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) resuelve el idioma actual en el servidor. [`GTProvider`](/docs/react/reference/components/gt-provider) proporciona el contexto de traducción a toda la aplicación, incluidos sus componentes interactivos.

### 5. Traduce JSX y atributos de entrada

Agrega la siguiente página. Sigue siendo un Componente de servidor. [`T`](/docs/react/reference/components/t) marca el encabezado y el párrafo estáticos para traducirlos; [`LocaleSelector`](/docs/react/reference/components/locale-selector) proporciona el menú desplegable de idiomas.

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

Crea el campo de búsqueda como un Componente de cliente. Usa [`useGT`](/docs/react/reference/hooks/use-gt) para los atributos cuyo valor es una cadena, como los marcadores de posición y las etiquetas de accesibilidad:

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

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

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) devuelve directamente la función de traducción. En un Componente de servidor asíncrono, usa [`getGT`](/docs/react/nextjs/reference/functions/get-gt) de `gt-next/server` en su lugar.

No incluyas valores dinámicos en expresiones sin procesar dentro de [`T`](/docs/react/reference/components/t). Para agregar nombres, cantidades o ramas, usa los [componentes de variables y formato](/docs/react/guides/formatting-variables) correspondientes.

## Generar traducciones y verificar el resultado

### 6. Genera la salida traducida

Para usar la traducción automática, inicia sesión con [`gt login`](/docs/cli/reference/commands/login) y configura el ID del proyecto, o añade una clave de API del proyecto y el ID del proyecto en `.env.local`:

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

Mantén la clave en privado y el archivo fuera del control de versiones. No expongas `GT_API_KEY` mediante una variable `NEXT_PUBLIC_`. La clave de herramientas necesita permisos de lectura/escritura de archivos y de acceso a la cola de traducción, además de acceso al contexto si se utiliza. Consulta la [documentación sobre claves de API](/docs/platform/dashboard/reference/api-keys).

Genera las traducciones:

```bash
npx gt translate
```

El comando envía el trabajo de traducción a General Translation y escribe los archivos de configuración regional en la ruta de salida configurada. Revisa el texto generado en el [Editor de Traducciones del panel de control](/docs/platform/dashboard/guides/reviewing-translations). Si editas localmente las traducciones descargadas, [`gt save-local`](/docs/cli/reference/commands/save-local) sincroniza esas correcciones con la plataforma. La generación a través del servicio se factura según el [precio basado en el uso](https://generaltranslation.com/pricing).

Si quieres probar la biblioteca sin llamar al servicio de traducción, ejecuta este comando en su lugar:

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) crea plantillas que contienen el texto de origen; **no traduce ese texto**. Edita los valores de texto en `src/_gt/es.json` y `src/_gt/fr.json` sin modificar las claves generadas ni la estructura JSX. Por ejemplo, traduce el encabezado en español como «Encuentra tu próximo proyecto» y la etiqueta de búsqueda como «Buscar proyectos». Traduce el resto del texto antes de dar esos archivos por terminados.

Después de modificar el contenido de origen, vuelve a ejecutar [`gt generate`](/docs/cli/reference/commands/generate) y revisa los archivos de destino. El comando conserva los valores de destino existentes, agrega las nuevas entradas con el texto de origen y elimina las que ya no están presentes en el origen.

### 7. Inicia la app y cambia de idioma

```bash
npm run dev
```

Abre la dirección que muestra Next.js. Selecciona español y francés en el menú desplegable. Comprueba que cambian el encabezado, el párrafo, el marcador de posición y la etiqueta accesible del campo de entrada. Recarga la página para verificar que se conserva el idioma seleccionado y, después, vuelve a cambiar a inglés.

Si el selector cambia pero el texto sigue en inglés, revisa los archivos del idioma de destino. Las plantillas de origen generadas por [`gt generate`](/docs/cli/reference/commands/generate) seguirán en inglés hasta que las traduzcas. Si la página no compila porque falta un archivo de configuración regional, vuelve a ejecutar el comando de generación correspondiente antes de reiniciar el entorno de desarrollo.

## Compilación para producción

Ejecuta [`gt validate`](/docs/cli/reference/commands/validate) para detectar errores de sintaxis de traducción antes de enviar una solicitud de traducción alojada. Las [reglas de ESLint](/docs/react/guides/linting-your-code) de GT ofrecen comprobaciones adicionales durante el desarrollo. Si tienes [configurada la traducción en desarrollo](/docs/react/guides/configuring#delivery), también puedes previsualizar el contenido traducido mientras editas.

Para el flujo de trabajo de traducción automática, incorpora este comando de compilación a los scripts que ya tienes en tu `package.json`:

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

Configura `GT_PROJECT_ID` y `GT_API_KEY` en el entorno de compilación. Asegúrate de que la CLI, instalada como dependencia de desarrollo, esté disponible durante esa compilación. Agrega `src/_gt/` a `.gitignore` si tu compilación vuelve a generar la salida de traducción cada vez.

Si elegiste la traducción manual, conserva tus archivos traducidos en el control de versiones u obtenlos de tu propio flujo de traducción. Ejecuta `next build` cuando esos archivos estén disponibles. No pierdas la única copia de las traducciones que mantienes manualmente por ignorarlas como si fueran una salida reproducible.

Después de compilar, ejecuta la aplicación en modo de producción y vuelve a comprobar el cambio de idioma. Así pruebas los archivos que realmente se van a publicar, en lugar de fiarte solo del comportamiento en desarrollo.

El [flujo de trabajo de traducción incremental](/docs/cli/guides/generating-translations#retranslate) traduce el contenido de origen modificado y reutiliza las traducciones coincidentes de versiones anteriores. Para automatizar también los cambios en el repositorio, configura [Locadex](/docs/platform/locadex/guides/configuring-automations) para que internacionalice nueva UI, genere traducciones o sincronice cambios de configuración regional mediante pull requests. Ajusta la configuración de activación y revisión a tu proceso de lanzamiento.

Si quieres publicar actualizaciones sin tener que recompilar la aplicación, elige la [entrega por CDN](/docs/react/nextjs/config) en lugar del cargador local. Así, las ediciones de traducción publicadas pueden llegar a la aplicación desplegada según su configuración de versión y caché.

Si tus páginas públicas necesitan URL independientes por idioma, continúa con el [enrutamiento por configuración regional con App Router](/docs/react/nextjs/app-router-middleware). El ejemplo basado en cookies de esta guía no crea páginas `/es` ni `/fr`, ni configura URL canónicas ni metadatos `hreflang`.

## Un prompt para tu agente de programación

Empieza con el [prompt oficial de configuración inicial](https://generaltranslation.com/agent-prompt.md), que mantenemos actualizado, y luego añade esta descripción de la funcionalidad:

```text
Usa el inglés como idioma de origen y el español y el francés como idiomas de destino.
Localiza la página del proyecto con traducciones empaquetadas localmente. Conserva los
proveedores y las rutas existentes. Incluye su encabezado, párrafo, campo de búsqueda,
etiqueta accesible y un selector de idioma. Usa la terminología compartida del proyecto.
Verifica el cambio de idioma, la persistencia tras recargar, el contenido server-rendered,
los atributos del cliente y la compilación de producción. Informa de qué se probó realmente
y qué sigue pendiente de revisión lingüística. No despliegues ni fusiones.
```

Para conocer el flujo de trabajo completo, consulta [i18n sin archivos de traducción](/kb/i18n-without-translation-files) y [cómo usar un agente de programación](/kb/ai-agent-i18n-setup).

## Related questions

- [¿Puedo hacer i18n sin archivos de traducción?](https://generaltranslation.com/es/kb/i18n-without-translation-files.mdx): Sí. Las bibliotecas gt-react y gt-next de General Translation permiten hacer i18n en React y Next.js sin claves de traducción y sin tener que mantener un archivo JSON por idioma. El texto permanece inline en JSX dentro del componente `<T>`, y el comando gt translate genera las traducciones de cada idioma durante la compilación, con contexto extraído de tu código. Locadex puede mantenerlas al día mediante pull requests.
- [¿Cómo internacionalizo una aplicación con Cursor o Claude Code?](https://generaltranslation.com/es/kb/ai-agent-i18n-setup.mdx): Empieza con el prompt Setup for Agents de General Translation en Cursor o Claude Code, elige una funcionalidad y los idiomas de destino, y deja que el agente implemente y verifique el resultado. El inicio de sesión desde el navegador, la documentación legible por máquinas y las herramientas MCP enlazan la configuración inicial con la traducción y la revisión. Usa Locadex para automatizar la localización continua mediante pull requests.
- [¿Cómo mantengo las traducciones actualizadas en cada despliegue?](https://generaltranslation.com/es/kb/translations-in-ci.mdx): Ejecuta la traducción como un paso del flujo antes de cada compilación de producción, para que el texto nuevo se publique ya traducido en el mismo despliegue que lo incorpora. La CLI gt de General Translation lo hace con npx gt translate, usando una clave de API del proyecto y el ID del proyecto almacenados como secretos de CI.

## Previous and next questions

- Previous question: [General Translation vs. Weblate: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-weblate.mdx)
- Next question: [¿Cómo doy formato a números, fechas y monedas para cada configuración regional?](https://generaltranslation.com/es/kb/format-numbers-dates-currencies.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.