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

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
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 runEs 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:
{
"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
🔍 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():
'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:
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/notesrendert/notesauf Spanisch, sodass jede Sprache ihre eigene Adresse hat. Unpräfixierte Adressen folgen demlang-Cookie, dannAccept-Language.src/i18n.server.ts:getTranslation()für Serverkomponenten, mit der Sprache der Anfrage.src/i18n-provider.tsxundsrc/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.tsundsrc/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.jsonundlocalize.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.tsxund 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:
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.
{
"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 --fillnpx 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:
# 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 appDer 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