Blog

Agrega i18n a una aplicación Next.js App Router en una solicitud de extracción

Una ejecución de localize.dev en una nueva aplicación Next.js 16: lo que encuentra, lo que cambia en componentes de cliente y servidor, lo que aún haces a mano y cómo se envía como una solicitud de extracción.

Stephen Ufort · 16 de noviembre de 2026 · 8 min de lectura

Una línea de un componente cliente de Next.js reescrita a t() con su fecha como marcador de posición, el mensaje en español, alemán y francés, y el resumen de la ejecución

Esta es una ejecución de localize.dev en una nueva aplicación Next.js 16 App Router, desde la primera comprobación hasta la solicitud de extracción. Cada comando, archivo y línea de salida a continuación proviene de esa ejecución.

La aplicación es una pequeña aplicación de notas hecha con create-next-app: una página de inicio con un formulario de registro, una página de notas, dos componentes de cliente y metadatos de página. Muestra doce fragmentos de texto de interfaz de usuario, todos codificados en inglés.

Ver lo que está codificado

Comienza con check. Se ejecuta en tu máquina, no necesita cuenta y no cambia nada:

npx localize-dev check
$ npx localize-dev check
  src/app/layout.tsx:6  "Shared notes your team can search in seconds."
  src/app/notes/page.tsx:6  "My notes"
  src/app/notes/page.tsx:13  "My notes"
  src/app/page.tsx:7  "Shared notes your team can search in seconds"
  src/app/page.tsx:9  "Write meeting notes, tag them and find them again from any workspace. Read the <a>quick start</a> or start a free trial."
  src/components/NoteList.tsx:12  "Search your notes"
  src/components/NoteList.tsx:13  "{count} notes"
  src/components/NoteList.tsx:14  "Nothing matches "{query}". Try another word."
  src/components/NoteList.tsx:19  "Last edited {updated}"
  src/components/SignUpForm.tsx:12  "Check your email address and try again."
  src/components/SignUpForm.tsx:25  "Your work email"
  src/components/SignUpForm.tsx:29  "Get started"
⚠️  12 hardcoded string(s) in 5 file(s). Fix with: npx localize-dev run

Enumera más que texto JSX: la descripción de metadatos, un marcador de posición, un aria-label y un mensaje de error pasado a setError. El plural aparece una vez como {count} notes, y la oración con una fecha como Last edited {updated}, porque cada uno de ellos se convierte en un mensaje.

Mantener el nombre del producto

El título de la página es solo el nombre del producto, Acme Notes. Una ejecución anterior sin ninguna configuración lo tradujo a "Acme Notas" en español. Agrega el nombre a doNotTranslate y enumera los idiomas que deseas:

localize.config.json
{
  "targetLocales": ["es", "de", "fr"],
  "doNotTranslate": ["Acme Notes"]
}

El texto compuesto únicamente por esos nombres deja de contar como copia, por eso el título no está en la lista anterior. Donde el nombre aparece dentro de una oración más larga, cada idioma lo mantiene tal como está escrito.

Ejecutar

run asigna una clave a cada cadena, reescribe el código, traduce los nuevos mensajes y configura i18next para el App Router. Necesita una clave API (npx localize-dev login). El plan gratuito cubre 1.000 cadenas al mes en 3 idiomas, lo que es más de lo que esta aplicación necesita.

npx localize-dev run
$ npx localize-dev run
🔍 Scanning src/ (target locales: es, de, fr)
Requesting keys/translations for 12 unique string(s) in 5 batch(es)...
✓ Translated 12 string(s) in 4s

src/app/layout.tsx
  L6  'Shared notes your team can search in seconds.'  →  t('layout.shared_notes_description')

src/app/notes/page.tsx
  L6  'My notes'  →  t('notes.metadata_title')
  L13  My notes  →  {t('notes.metadata_title')}

src/app/page.tsx
  L7  Shared notes your team can search in seconds  →  {t('home.hero_heading')}
  L9  Write meeting notes, tag them and find them again from any workspace. Read the <Link href="/docs">quick start</Link> or start a free trial.  →  <Trans t={t} i18n={i18n} i18nKey="home.meeting_notes_description" components={{ a: <Link href="/docs" /> }} />

src/components/NoteList.tsx
  L12  "Search your notes"  →  {t('note_list.search_placeholder')}
  L13  {shown.length === 1 ? '1 note' : `${shown.length} notes`}  →  {t('note_list.notes_count', { count: shown.length })}
  L14  Nothing matches "{query}". Try another word.  →  {t('note_list.no_results_message', { query })}
  L19  Last edited {n.updated.toLocaleDateString()}  →  {t('note_list.last_edited_label', { updated: n.updated.toLocaleDateString(i18n.language) })}

src/components/SignUpForm.tsx
  L12  'Check your email address and try again.'  →  t('signup.email_error')
  L25  "Your work email"  →  {t('signup.work_email_input_label')}
  L29  Get started  →  {t('signup.get_started_button')}

✅ Localized 12 string(s) across 5 file(s) (11 new keys, 1 reused). 22 file(s) written.
📦 Added i18next, react-i18next, localize-dev to package.json
🛠️  Created src/i18n.ts, imported in src/app/layout.tsx
🌐 Added <LanguageSwitcher /> in src/language-switcher.tsx; render it where people pick a language
⚠️  Set "siteUrl" in localize.config.json (https://your-site.com): `src/app/sitemap.ts` needs full addresses, and off Vercel, Netlify, Render and Railway it has no other way to know them.
⚠️  Locale files now merge key by key: run this once per clone (and in CI before merging) so git uses it: git config merge.localize-dev.driver "npx localize-dev merge-locales %O %A %B %P"
👉 Run `npm install` to install them.

La ejecución escribió 22 archivos. Las ediciones de código son pequeñas y la mayoría de los archivos son nuevos: los archivos de localización y la configuración de i18n. Actúa sobre las dos notas al final: configura siteUrl si la aplicación no está desplegada en Vercel, Netlify, Render o Railway, y ejecuta la línea git config una vez por clon para que los archivos de localización se fusionen clave por clave.

Un componente cliente

NoteList es un componente cliente, por lo que obtiene useTranslation():

src/components/NoteList.tsx
'use client';

import { useState } from 'react';
import type { Note } from '@/lib/notes';
import { useTranslation } from 'react-i18next';

export function NoteList({ notes }: { notes: Note[] }) {
  const { t, i18n } = useTranslation();
  const [query, setQuery] = useState('');
  const shown = notes.filter((n) => n.title.toLowerCase().includes(query.toLowerCase()));

  return (
    <section className="mt-6">
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder={t('note_list.search_placeholder')} className="w-full rounded border px-3 py-2" />
      <p className="mt-2 text-sm text-gray-500">{t('note_list.notes_count', { count: shown.length })}</p>
      {shown.length === 0 && <p className="mt-6">{t('note_list.no_results_message', { query })}</p>}
      <ul className="mt-4 space-y-2">
        {shown.map((n) => (
          <li key={n.id} className="rounded border p-3">
            <span className="font-medium">{n.title}</span>
            <span className="ms-2 text-sm text-gray-500">{t('note_list.last_edited_label', { updated: n.updated.toLocaleDateString(i18n.language) })}</span>
          </li>
        ))}
      </ul>
    </section>
  );
}

El ternario 1 note o N notes se convirtió en un mensaje plural con un count, por lo que un idioma con más formas plurales los obtiene todos (el español obtuvo one, many y other). La fecha permaneció dentro de su oración como un marcador de posición llamado updated, por lo que el alemán lo coloca después de "Zuletzt bearbeitet" y un idioma que pone la fecha primero puede hacerlo. La fecha ahora se formatea con i18n.language, el idioma de la solicitud. Antes de la ejecución usaba la del navegador. El /es/notes dice 11/10/2026, día primero.

Un componente de servidor

Los componentes del servidor no pueden usar hooks, por lo que la página de inicio espera getTranslation() en su lugar. La oración con un enlace se convierte en un <Trans> que mantiene tu <Link>:

src/app/page.tsx
import Link from 'next/link';
import { SignUpForm } from '@/components/SignUpForm';
import { getTranslation } from '../i18n.server';
import { Trans } from 'react-i18next/TransWithoutContext';

export default async function Home() {
  const { t, i18n } = await getTranslation();
  return (
    <main className="mx-auto max-w-2xl px-6 py-24">
      <h1 className="text-4xl font-semibold">{t('home.hero_heading')}</h1>
      <p className="mt-4 text-lg text-gray-600">
        <Trans t={t} i18n={i18n} i18nKey="home.meeting_notes_description" components={{ a: <Link href="/docs" /> }} />
      </p>
      <SignUpForm />
    </main>
  );
}

Los metadatos funcionan de la misma manera. export const metadata se convirtió en un generateMetadata() que traduce el título y la descripción para cada solicitud, con la dirección canónica y el og:locale del idioma de la solicitud.

La configuración que añade

Cada archivo nuevo comienza con un comentario que dice lo que hace:

  • src/proxy.ts: /es/notes renderiza /notes en español, por lo que cada idioma tiene su propia dirección. Las direcciones sin prefijo siguen la cookie lang, luego Accept-Language.
  • src/i18n.server.ts: getTranslation() para componentes del servidor, con el idioma de la solicitud.
  • src/i18n-provider.tsx y src/i18n.ts: una instancia de i18next por árbol de renderizado para componentes cliente, por lo que dos solicitudes en diferentes idiomas nunca comparten una.
  • src/i18n-seo.ts, src/i18n-alternates.tsx, src/app/sitemap.ts y src/app/robots.ts: direcciones canónicas, og:locale, enlaces hreflang y un sitemap con cada página en cada idioma.
  • locales/en.json, es.json, de.json, fr.json y localize.lock.json, que registra de qué se hizo cada traducción, por lo que una ejecución posterior solo traduce lo que ha cambiado.
  • src/language-switcher.tsx, y una línea .gitattributes para que dos ramas que agregan claves se fusionen sin conflicto.

El layout raíz ahora lee el idioma de cada solicitud y establece <html lang dir> a partir de él, por lo que un idioma de derecha a izquierda se presenta de derecha a izquierda desde la primera representación.

Mostrar un selector de idioma

La ejecución genera <LanguageSwitcher /> pero deja la colocación a tu cargo. Aquí va en el encabezado de la página de notas:

src/app/notes/page.tsx
import { LanguageSwitcher } from '../../language-switcher';

export default async function NotesPage() {
  const { t } = await getTranslation();
  const notes = await getNotes();
  return (
    <main className="mx-auto max-w-2xl px-6 py-12">
      <header className="flex items-center justify-between">
        <h1 className="text-2xl font-semibold">{t('notes.metadata_title')}</h1>
        <LanguageSwitcher />
      </header>
      <NoteList notes={notes} />
    </main>
  );
}

Guarda la elección en la cookie lang y se actualiza, por lo que los componentes del servidor también se renderizan en el nuevo idioma.

Lee las traducciones

Alguien que lea cada idioma debería revisar los archivos de locale en el diff. Comprueba palabras con dos significados, nombres que deberían haberse mantenido como están escritos y cómo la app se dirige al lector. localize.dev envía una forma de dirigirse por idioma con cada lote (Sie en alemán, vous en francés, tú en español), para que una ejecución no las mezcle. Si tu app dice du, ponlo en las notas de estilo del glosario de tu espacio de trabajo.

locales/es.json
{
  "layout": {
    "shared_notes_description": "Notas compartidas que tu equipo puede buscar en segundos."
  },
  "notes": {
    "metadata_title": "Mis notas"
  },
  "home": {
    "hero_heading": "Notas compartidas que tu equipo puede buscar en segundos",
    "meeting_notes_description": "Escribe notas de reuniones, etiquétalas y encuéntralas de nuevo desde cualquier espacio de trabajo. Lee la <a>guía de inicio rápido</a> o inicia una prueba gratuita."
  },
  "note_list": {
    "search_placeholder": "Busca tus notas",
    "notes_count_one": "{{count}} nota",
    "notes_count_many": "{{count}} notas",
    "notes_count_other": "{{count}} notas",
    "no_results_message": "Nada coincide con \"{{query}}\". Intenta con otra palabra.",
    "last_edited_label": "Última edición {{updated}}"
  },
  "signup": {
    "email_error": "Comprueba tu dirección de correo electrónico y vuelve a intentarlo.",
    "work_email_input_label": "Tu correo electrónico del trabajo",
    "get_started_button": "Empezar"
  }
}

Para cambiar una traducción, edita el archivo de locale. La siguiente ejecución traduce solo los mensajes cuyo inglés ha cambiado, por lo que deja tu edición intacta.

Abrir la pull request

Pon la ejecución en una rama, comprueba que la app todavía compila y abre la pull request:

git switch -c add-languages
npx localize-dev run
npm install
npm run build
git add -A
git commit -m "Spanish, German and French"
gh pr create --fill

npx localize-dev pr hace lo mismo en un solo paso: ejecuta la localización y abre la pull request desde una rama localize-dev/<branch>, con un token de GITHUB_TOKEN.

Mantenlo traducido

La próxima función agregará texto en inglés nuevamente. Ejecuta npx localize-dev check en CI para detectarlo: no necesita una clave y falla en copias codificadas o traducciones faltantes. O agrega la GitHub Action, que traduce texto nuevo en cada push y abre una pull request con él:

.github/workflows/localize.yml
# Copy to .github/workflows/localize.yml in the repository you want to localize.
# Needs the repository secret LOCALIZEDEV_API_KEY (create a key in the localize.dev dashboard).
name: Localize

on:
  push:
    branches: [main] # your default branch
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch: # "Run workflow" button in the Actions tab

permissions:
  contents: write # push the localize-dev/<branch> branch
  pull-requests: write # open or update the localization PR

# One run per branch at a time; a newer push supersedes the running one.
concurrency:
  group: localize-${{ github.head_ref || github.ref_name }}
  cancel-in-progress: true

jobs:
  localize:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    # Skip localize.dev's own branches, and fork PRs (their token is read-only).
    if: >-
      !startsWith(github.head_ref || github.ref_name, 'localize-dev/') &&
      (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
    steps:
      - name: Checkout
        uses: actions/checkout@v5
        with:
          # On PRs, scan the branch itself rather than the merge commit.
          ref: ${{ github.head_ref || github.ref_name }}

      - name: Localize
        uses: ufortstephen/autolocalize-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          api_key: ${{ secrets.LOCALIZEDEV_API_KEY }}
          target_locales: 'es,de,fr'
          # src_dir: 'src' # default: your framework's (src, app/views, resources/views, lib…)
          # locales_path: 'public/locales/{locale}/common.json' # default: your framework's
          # working_directory: 'apps/web' # monorepo: localize just this app

El flujo de trabajo necesita un secreto de repositorio LOCALIZEDEV_API_KEY y omite sus propias ramas localize-dev/.

Pruébalo en tu propio código en la zona de juegos, no se necesita cuenta