Blog

Fai tradurre il testo dell'interfaccia utente da Claude Code mentre scrive

Una richiesta di funzionalità in un'app Next.js con tre lingue: la configurazione, il messaggio dell'hook, la chiamata a localize, le traduzioni e il controllo, da una sessione reale di Claude Code.

Stephen Ufort · 16 novembre 2026 · 5 min di lettura

La richiesta di funzionalità in Claude Code, la chiamata a localize con le sue statistiche, il messaggio di conferma in spagnolo, tedesco e francese e il controllo superato

Claude Code scrive il testo dell'interfaccia utente in inglese, ovunque la funzionalità ne abbia bisogno. In un'app già tradotta, ogni nuova funzionalità lascia alcune stringhe codificate in modo fisso. Questo post segue una richiesta di funzionalità in un'app Next.js con spagnolo, tedesco e francese, dalla configurazione al controllo superato, con i comandi e l'output reali.

L'app è l'app delle note dal post sull'aggiunta di i18n a un'app Next.js App Router in una singola pull request. Ha già i18next, file di localizzazione e un selettore di lingua. Come funzionano internamente il server MCP e l'hook è nel post sulla localizzazione mentre il tuo agente di codifica scrive; questo li mostra su una modifica reale.

Configuralo

Un comando aggiunge il server MCP, l'hook post-modifica e le istruzioni per l'agente:

$ npx localize-dev init --agent
🤖 Wrote .mcp.json
🤖 Wrote .cursor/mcp.json
🤖 Wrote .claude/settings.json
🤖 Wrote AGENTS.md
🤖 Wrote CLAUDE.md
🤖 Wrote .cursor/rules/localize.mdc
Commit these so everyone working on the project, and their agents, gets them. Restart the agent to load the MCP server.

L'hook va in .claude/settings.json. Dopo ogni Modifica, MultiModifica o Scrittura, Claude Code esegue localize-dev hook sul file che l'agente ha modificato:

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y localize-dev hook",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

AGENTS.md ottiene una breve sezione, e CLAUDE.md la importa, così Claude Code la legge all'inizio di ogni sessione:

AGENTS.md
## Translations (localize.dev)

The UI text is translated with localize.dev, so text people see goes through the i18n library and isn't hardcoded.

- After adding or changing UI text, call the `localize` tool of the localize-dev MCP server with the files you changed (`paths`, relative to the source folder `src`). It gives the text keys, rewrites the code and translates the new messages. Without the MCP server, run `npx localize-dev run --files <files>`.
- Before finishing, run `npx localize-dev check --changed`. It should pass.
- Leave new messages out of the other languages' locale files: localize fills them in. Fixing a translation that's wrong is fine.

Esegui il commit dei file in modo che anche il resto del team e i loro agenti li ricevano. Quindi riavvia Claude Code in modo che avvii il server MCP.

Richiedi una funzionalità

Questa è l'intera richiesta. Non menziona traduzioni:

the prompt
Add a delete button to each note in the notes list. Ask for confirmation before removing a note, and show a short message after it's deleted.

Claude Code ha letto il codice delle note, quindi ha scritto un'azione server che elimina una nota, una funzione di eliminazione nel livello dati e il nuovo NoteList: un pulsante Elimina su ogni nota, una conferma all'interno della riga, un messaggio dopo l'eliminazione e un messaggio di errore in caso di fallimento. Quella prima bozza conteneva sette pezzi di testo in inglese.

Cosa vede l'hook

Ecco cosa stampa l'hook per quella prima bozza. Ha trovato tutti e sette, inclusi aria-label e le due stringhe letterali:

hook output
localize.dev: src/components/NoteList.tsx has UI text that isn't translated yet.
  line 41: "Deleted "{deletedTitle}"."
  line 43: "Couldn't delete the note. Try again."
  line 54: "Delete "{title}"?"
  line 56: "Delete"
  line 59: "Cancel"
  line 63: "Delete "{title}""
  line 64: "Delete"
Call the localize tool of the localize-dev MCP server with paths ["components/NoteList.tsx"]: it gives this text translation keys, rewrites the code and translates it.
Without the MCP server, run in the project folder: npx localize-dev run --files src/components/NoteList.tsx

L'hook esce con il codice 2, quindi Claude Code mostra questo messaggio all'agente. Un file senza nulla da tradurre esce con il codice 0 e non stampa nulla. Per disattivare l'hook per una sessione, imposta LOCALIZE_DEV_HOOK=off.

La chiamata localize

Subito dopo aver scritto il componente, l'agente ha chiamato lo strumento localize con quel percorso. Queste sono la chiamata e le statistiche del suo risultato:

localize tool call and result
localize({ "paths": ["components/NoteList.tsx"] })

"stats": {
  "filesScanned": 1,
  "stringsReplaced": 7,
  "newKeys": 6,
  "reusedKeys": 1,
  "translations": { "es": 6, "de": 6, "fr": 6 }
}

Sette stringhe sono diventate sei chiavi: i due pulsanti Elimina condividono note_list.delete_button. Le stringhe letterali sono diventate messaggi con segnaposto, quindi Delete "${n.title}" è ora un messaggio con un segnaposto title, e una lingua può posizionare il titolo ovunque la sua grammatica lo richieda. La riga di conferma ora appare così:

src/components/NoteList.tsx
{confirmingId === n.id ? (
  <div className="flex items-center gap-2 text-sm">
    <span>{t('note_list.delete_note_confirmation', { title: n.title })}</span>
    <button type="button" onClick={() => remove(n)} disabled={pending} className="rounded bg-red-600 px-3 py-1 text-white disabled:opacity-50">
      {t('note_list.delete_button')}
    </button>
    <button type="button" onClick={() => setConfirmingId(null)} disabled={pending} className="rounded border px-3 py-1">
      {t('note_list.cancel')}
    </button>
  </div>
) : (
  <button type="button" onClick={() => { setConfirmingId(n.id); setFailed(false); }} aria-label={t('note_list.delete_note_button_label', { title: n.title })} className="rounded border px-3 py-1 text-sm text-red-600">
    {t('note_list.delete_button')}
  </button>
)}

Le traduzioni

La stessa chiamata compilata in spagnolo, tedesco e francese. Queste sono le aggiunte tedesche:

locales/de.json
"deleted_note_message": "„{{deletedTitle}}“ gelöscht.",
"delete_note_error": "Die Notiz konnte nicht gelöscht werden. Versuchen Sie es erneut.",
"delete_note_confirmation": "„{{title}}“ löschen?",
"delete_button": "Löschen",
"cancel": "Abbrechen",
"delete_note_button_label": "„{{title}}“ löschen"

Il tedesco usa le proprie virgolette e il Sie formale ("Versuchen Sie es erneut"), come il resto dell'app. Il francese ha ricevuto « » con spazi all'interno. Lo spagnolo usa tú, come nei messaggi precedenti:

locales/es.json
"deleted_note_message": "Se eliminó \"{{deletedTitle}}\".",
"delete_note_error": "No se pudo eliminar la nota. Inténtalo de nuevo.",
"delete_note_confirmation": "¿Eliminar \"{{title}}\"?",
"delete_button": "Eliminar",
"cancel": "Cancelar",
"delete_note_button_label": "Eliminar \"{{title}}\""

L'agente non ha scritto nessuno di questi a mano. La sezione in AGENTS.md gli chiede di lasciare stare i file di localizzazione delle altre lingue, e così ha fatto.

Controllato prima che finisse

Prima di dichiarare che era stato fatto, l'agente ha eseguito il controllo, quindi il type checker e il linter:

$ npx localize-dev check --changed
✅ Everything is localized (1 files scanned).

Il suo riepilogo diceva tre cose utili. Ha integrato la conferma nella riga invece di usare il popup del browser, quindi il testo può essere tradotto. Le note eliminate ritornano quando il server si riavvia, perché il livello dati è un sostituto. E non aveva provato la funzionalità in un browser. Prova tu stesso prima di unire: il controllo copre il testo, non se l'eliminazione funziona.

Cursore e altri agenti

Cursor ottiene lo stesso server MCP in .cursor/mcp.json e una regola in .cursor/rules/localize.mdc per i file dell'interfaccia utente dell'app. init --agent non aggiunge alcun hook per Cursor, quindi la regola è ciò che chiede all'agente di chiamare localize. Altri agenti che leggono AGENTS.md ricevono le stesse istruzioni e un agente senza MCP può eseguire npx localize-dev run --files con i file che ha modificato.

Per le modifiche apportate senza un agente, npx localize-dev init --agent --pre-commit controlla anche i file preparati prima di ogni commit, e npx localize-dev check in CI fallisce una pull request con testo hardcoded. Nessuno dei due necessita di una chiave API.

Qualcuno che legge ogni lingua dovrebbe comunque guardare i file di localizzazione nel diff. L'esecuzione mantiene una forma di indirizzo per lingua, ma solo un lettore sa se "Löschen" è la parola che i tuoi utenti tedeschi si aspettano su quel pulsante.

Provalo sul tuo codice nell'area di gioco, non è necessario un account