Blog

Ajoutez i18n à une application Next.js App Router en une seule pull request

Une exécution de localize.dev sur une nouvelle application Next.js 16 : ce qu'elle trouve, ce qu'elle modifie dans les composants client et serveur, ce que vous faites encore à la main, et comment elle est livrée en une seule pull request.

Stephen Ufort · 16 novembre 2026 · 8 min de lecture

Une ligne d'un composant client Next.js réécrite en t() avec sa date comme espace réservé, le message en espagnol, allemand et français, et le résumé de l'exécution

Ceci est une exécution de localize.dev sur une nouvelle application Next.js 16 App Router, de la première vérification à la pull request. Chaque commande, fichier et ligne de sortie ci-dessous provient de cette exécution.

L'application est une petite application de notes créée avec create-next-app : une page d'accueil avec un formulaire d'inscription, une page de notes, deux composants client et des métadonnées de page. Elle affiche douze éléments de texte d'interface utilisateur, tous codés en dur en anglais.

Voir ce qui est codé en dur

Commencez avec check. Il s'exécute sur votre machine, ne nécessite aucun compte et ne change rien :

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

Il liste plus que du texte JSX : la description des métadonnées, un espace réservé, un aria-label et un message d'erreur passé à setError. Le pluriel apparaît une fois sous forme de {count} notes, et la phrase avec une date sous forme de Last edited {updated}, car chacun d'eux devient un message.

Conserver le nom du produit

Le titre de la page est uniquement le nom du produit, Acme Notes. Une exécution précédente sans aucune configuration l'a traduit en "Acme Notas" en espagnol. Ajoutez le nom à doNotTranslate et listez les langues que vous souhaitez :

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

Un texte composé uniquement de ces noms n'est plus considéré comme une copie, c'est pourquoi le titre ne figure pas dans la liste ci-dessus. Lorsque le nom apparaît dans une phrase plus longue, chaque langue le conserve tel quel.

Exécuter

run attribue une clé à chaque chaîne, réécrit le code, traduit les nouveaux messages et configure i18next pour l'App Router. Il nécessite une clé API (npx localize-dev login). Le plan gratuit couvre 1 000 chaînes par mois dans 3 langues, ce qui est plus que ce dont cette application a besoin.

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.

L'exécution a écrit 22 fichiers. Les modifications de code sont mineures et la plupart des fichiers sont nouveaux : les fichiers de langue et la configuration i18n. Agissez sur les deux notes à la fin : définissez siteUrl si l'application n'est pas déployée sur Vercel, Netlify, Render ou Railway, et exécutez la ligne git config une fois par clone afin que les fichiers de langue fusionnent clé par clé.

Un composant client

NoteList est un composant client, il reçoit donc 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>
  );
}

Le ternaire 1 note ou N notes est devenu un message pluriel avec un count, de sorte qu'une langue avec plus de formes plurielles les obtient toutes (l'espagnol a obtenu one, many et other). La date est restée dans sa phrase comme un espace réservé nommé updated, donc l'allemand le place après "Zuletzt bearbeitet" et une langue qui place la date en premier peut le faire. La date est maintenant formatée avec i18n.language, la langue de la requête. Avant l'exécution, elle utilisait celle du navigateur. Le /es/notes indique 11/10/2026, le jour en premier.

Un composant serveur

Les composants serveur ne peuvent pas utiliser de hooks, la page d'accueil attend donc getTranslation() à la place. La phrase avec un lien devient un <Trans> qui conserve votre <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>
  );
}

Les métadonnées fonctionnent de la même manière. export const metadata est devenu un generateMetadata() qui traduit le titre et la description pour chaque requête, avec l'adresse canonique et l'og:locale de la langue de la requête.

La configuration qu'il ajoute

Chaque nouveau fichier commence par un commentaire qui indique ce qu'il fait :

  • src/proxy.ts : /es/notes rend /notes en espagnol, donc chaque langue a sa propre adresse. Les adresses sans préfixe suivent le cookie lang, puis Accept-Language.
  • src/i18n.server.ts : getTranslation() pour les composants serveur, avec la langue de la requête.
  • src/i18n-provider.tsx et src/i18n.ts : une instance i18next par arbre de rendu pour les composants client, de sorte que deux requêtes dans des langues différentes n'en partagent jamais une.
  • src/i18n-seo.ts, src/i18n-alternates.tsx, src/app/sitemap.ts et src/app/robots.ts : adresses canoniques, og:locale, liens hreflang et un sitemap avec chaque page dans chaque langue.
  • locales/en.json, es.json, de.json, fr.json et localize.lock.json, qui enregistre à partir de quoi chaque traduction a été créée, de sorte qu'une exécution ultérieure ne traduit que ce qui a changé.
  • src/language-switcher.tsx, et une ligne .gitattributes pour que deux branches qui ajoutent toutes deux des clés fusionnent sans conflit.

La mise en page racine lit maintenant la langue de chaque requête et définit <html lang dir> à partir de celle-ci, de sorte qu'une langue de droite à gauche est disposée de droite à gauche dès le premier rendu.

Afficher un sélecteur de langue

L'exécution génère <LanguageSwitcher /> mais vous laisse le soin de la mise en page. Voici comment elle apparaît dans l'en-tête de la page de notes :

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

Il enregistre le choix dans le cookie lang et actualise, de sorte que les composants serveur soient également rendus dans la nouvelle langue.

Lisez les traductions

Quelqu'un qui lit chaque langue devrait examiner les fichiers de locale dans le diff. Vérifiez les mots à double sens, les noms qui auraient dû rester tels quels, et la manière dont l'application s'adresse au lecteur. localize.dev envoie une forme d'adresse par langue avec chaque lot (Sie en allemand, vous en français, tú en espagnol), de sorte qu'une exécution ne les mélange pas. Si votre application utilise du, indiquez-le dans les notes de style de votre glossaire d'espace de travail.

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

Pour changer une traduction, modifiez le fichier de locale. La prochaine exécution ne traduit que les messages dont l'anglais a changé, elle laisse donc votre modification intacte.

Ouvrir la pull request

Mettez l'exécution sur une branche, vérifiez que l'application se construit toujours, et ouvrez 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 fait la même chose en une seule étape : il exécute la localisation et ouvre la pull request à partir d'une branche localize-dev/<branch>, avec un token de GITHUB_TOKEN.

Gardez-le traduit

La prochaine fonctionnalité ajoutera à nouveau du texte en anglais. Exécutez npx localize-dev check dans CI pour le détecter : il n'a pas besoin de clé et échoue en cas de copie codée en dur ou de traduction manquante. Ou ajoutez l'action GitHub, qui traduit le nouveau texte à chaque push et ouvre une pull request avec celui-ci :

.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

Le workflow nécessite un secret de dépôt LOCALIZEDEV_API_KEY et ignore ses propres branches localize-dev/.

Essayez-le sur votre propre code dans le terrain de jeu, aucun compte requis