Blog

Fügen Sie i18n zu einer Next.js App Router-App in einem einzigen Pull Request hinzu

Ein localize.dev-Lauf auf einer neuen Next.js 16-App: Was es findet, was es in Client- und Serverkomponenten ändert, was Sie immer noch von Hand erledigen und wie es als ein Pull Request ausgeliefert wird.

Stephen Ufort · 16. November 2026 · 8 Min. Lesezeit

Eine Zeile einer Next.js-Clientkomponente, die zu t() umgeschrieben wurde, mit ihrem Datum als Platzhalter, der Nachricht auf Spanisch, Deutsch und Französisch und der Zusammenfassung des Laufs

Dies ist ein Lauf von localize.dev auf einer neuen Next.js 16 App Router-App, vom ersten Check bis zum Pull Request. Jeder Befehl, jede Datei und jede Zeile der Ausgabe unten stammt aus diesem Lauf.

Die App ist eine kleine Notizen-App, die mit create-next-app erstellt wurde: eine Startseite mit einem Anmeldeformular, eine Notizenseite, zwei Client-Komponenten und Seitenmetadaten. Sie zeigt zwölf UI-Texte an, die alle in Englisch hartcodiert sind.

Sehen Sie, was hartcodiert ist

Beginnen Sie mit check. Es läuft auf Ihrem Rechner, benötigt kein Konto und ändert nichts:

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

Es listet mehr als nur JSX-Text auf: die Metadatabeschreibung, ein Platzhalter, ein aria-label und eine Fehlermeldung, die an setError übergeben wird. Das Plural erscheint einmal als {count} notes und der Satz mit einem Datum als Last edited {updated}, da jede dieser Elemente zu einer Nachricht wird.

Behalten Sie den Produktnamen bei

Der Seitentitel ist nur der Produktname, Acme Notes. Ein früherer Lauf ohne Konfiguration übersetzte ihn ins Spanische mit "Acme Notas". Fügen Sie den Namen zu doNotTranslate hinzu und listen Sie die gewünschten Sprachen auf:

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

Text, der nur aus diesen Namen besteht, zählt nicht als Text, weshalb der Titel nicht in der obigen Liste steht. Wo der Name in einem längeren Satz vorkommt, behält jede Sprache ihn unverändert bei.

Ausführen

run weist jeder Zeichenkette einen Schlüssel zu, schreibt den Code neu, übersetzt die neuen Nachrichten und richtet i18next für den App Router ein. Es benötigt einen API-Schlüssel (npx localize-dev login). Der kostenlose Plan deckt 1.000 Zeichenketten pro Monat in 3 Sprachen ab, was mehr ist, als diese App benötigt.

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.

Der Lauf hat 22 Dateien geschrieben. Die Code-Änderungen sind klein, und die meisten Dateien sind neu: die Locale-Dateien und das i18n-Setup. Beachten Sie die beiden Hinweise am Ende: Setzen Sie siteUrl, wenn die App nicht auf Vercel, Netlify, Render oder Railway bereitgestellt wird, und führen Sie die Zeile git config einmal pro Klon aus, damit die Locale-Dateien Schlüssel für Schlüssel zusammengeführt werden.

Eine Client-Komponente

NoteList ist eine Client-Komponente und erhält daher 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>
  );
}

Das 1 note oder N notes Ternary wurde zu einer Pluralnachricht mit einem count, sodass eine Sprache mit mehr Pluralformen alle erhält (Spanisch erhielt one, many und other). Das Datum blieb als Platzhalter namens updated innerhalb seines Satzes, sodass Deutsch es nach "Zuletzt bearbeitet" setzt und eine Sprache, die das Datum zuerst setzt, dies tun kann. Das Datum wird jetzt mit i18n.language formatiert, der Sprache der Anfrage. Vor dem Lauf wurde der des Browsers verwendet. Am /es/notes liest es 11.10.2026, zuerst der Tag.

Eine Server-Komponente

Server-Komponenten können keine Hooks verwenden, daher wartet die Startseite stattdessen auf getTranslation(). Der Satz mit einem Link wird zu einem <Trans>, das Ihre <Link> beibehält:

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>
  );
}

Metadaten funktionieren auf die gleiche Weise. export const metadata wurde zu einem generateMetadata(), das den Titel und die Beschreibung für jede Anfrage übersetzt, zusammen mit der kanonischen Adresse und dem og:locale der Sprache der Anfrage.

Das von ihm hinzugefügte Setup

Jede neue Datei beginnt mit einem Kommentar, der erklärt, was sie tut:

  • src/proxy.ts: /es/notes rendert /notes auf Spanisch, sodass jede Sprache ihre eigene Adresse hat. Unpräfixierte Adressen folgen dem lang-Cookie, dann Accept-Language.
  • src/i18n.server.ts: getTranslation() für Serverkomponenten, mit der Sprache der Anfrage.
  • src/i18n-provider.tsx und src/i18n.ts: eine i18next-Instanz pro Render-Baum für Client-Komponenten, sodass zwei Anfragen in verschiedenen Sprachen niemals eine gemeinsam nutzen.
  • src/i18n-seo.ts, src/i18n-alternates.tsx, src/app/sitemap.ts und src/app/robots.ts: kanonische Adressen, og:locale, hreflang-Links und eine Sitemap mit jeder Seite in jeder Sprache.
  • locales/en.json, es.json, de.json, fr.json und localize.lock.json, welche aufzeichnen, woraus jede Übersetzung erstellt wurde, sodass ein späterer Durchlauf nur das übersetzt, was sich geändert hat.
  • src/language-switcher.tsx und eine .gitattributes-Zeile, damit zwei Branches, die beide Schlüssel hinzufügen, ohne Konflikt zusammengeführt werden.

Das Root-Layout liest nun die Sprache für jede Anfrage und setzt <html lang dir> daraus, sodass eine rechts-nach-links-Sprache vom ersten Rendering an von rechts nach links angeordnet wird.

Sprachumschalter anzeigen

Der Lauf generiert <LanguageSwitcher />, überlässt die Platzierung aber Ihnen. Hier kommt es in die Kopfzeile der Notizenseite:

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>
  );
}

Es speichert die Wahl im lang-Cookie und aktualisiert, sodass Serverkomponenten auch in der neuen Sprache gerendert werden.

Lesen Sie die Übersetzungen

Jemand, der jede Sprache liest, sollte sich die Locale-Dateien in der Diff ansehen. Überprüfen Sie Wörter mit zwei Bedeutungen, Namen, die unverändert hätten bleiben sollen, und wie die App den Leser anspricht. localize.dev sendet pro Sprache eine Anrede pro Batch (Sie auf Deutsch, vous auf Französisch, tú auf Spanisch), sodass ein Lauf sie nicht vermischt. Wenn Ihre App du sagt, vermerken Sie das in den Stilnotizen Ihres Workspace-Glossars.

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

Um eine Übersetzung zu ändern, bearbeiten Sie die Locale-Datei. Der nächste Lauf übersetzt nur Nachrichten, deren Englisch sich geändert hat, sodass Ihre Bearbeitung unberührt bleibt.

Pull-Request öffnen

Legen Sie den Lauf auf einen Branch, überprüfen Sie, ob die App noch erstellt wird, und öffnen Sie den 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 macht dasselbe in einem Schritt: Es führt die Lokalisierung aus und öffnet den Pull Request von einem localize-dev/<branch>-Branch mit einem Token von GITHUB_TOKEN.

Behalten Sie es übersetzt

Die nächste Funktion fügt wieder englischen Text hinzu. Führen Sie npx localize-dev check in CI aus, um es abzufangen: Es benötigt keinen Schlüssel und schlägt bei hartcodiertem Text oder fehlender Übersetzung fehl. Oder fügen Sie die GitHub Action hinzu, die neuen Text bei jedem Push übersetzt und damit einen Pull Request öffnet:

.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

Der Workflow benötigt ein LOCALIZEDEV_API_KEY Repository-Geheimnis und überspringt seine eigenen localize-dev/ Branches.

Probieren Sie es mit Ihrem eigenen Code im Playground aus, kein Konto erforderlich