Come limitare il consumo di token di Claude Code per generare traduzioni

Descrizione del problema

Chiedere a Claude Code (o a qualsiasi agente di sviluppo) di tradurre i tuoi contenuti è il modo più costoso in assoluto. A ogni esecuzione, l'agente deve:

• Caricare l'intero file JSON o di contenuto nel suo contesto, comprese le chiavi già tradotte.
• Cercare nei file correlati per capire dove si trova il contenuto e come è strutturato.
• Individuare quali locale mancano e devono essere generate.
• Rileggere ogni volta le tue istruzioni personalizzate ("trasforma gli URL in questo modo", "mantieni il nome del brand in inglese", "usa una forma informale").
• Riscrivere l'intero file, incluse le parti rimaste invariate.

Tutto questo viene reinviato a ogni iterazione, quindi il costo cresce in base a dimensione del contenuto × numero di locale × numero di iterazioni, e ogni minima divergenza di formattazione o di chiavi deve essere controllata manualmente.

Cosa fa invece Intlayer

Il vantaggio di Intlayer è svolgere questo lavoro al di fuori dell'agente, grazie a una pipeline progettata specificamente per la traduzione:

• Filtra le traduzioni esistenti per limitare l'uso dei token. Le chiavi già tradotte nel tuo JSON vengono escluse, inviando al modello solo quelle mancanti.
• Traduce il markdown blocco per blocco. Per la documentazione, doc translate e doc review confrontano ogni blocco con il documento base e saltano i blocchi già tradotti o invariati.
• Suddivide il tuo JSON in chunk se è troppo grande, per operare nella parte migliore della finestra di contesto.
• Appiattisce e ricostruisce il tuo JSON per ottimizzare il consumo di token.
• Inserisce prompt personalizzati per regole specifiche sul tuo brand e stile (applicationContext, --custom-instructions), così da scriverli una sola volta invece di ripeterli in ogni conversazione.
• Valida la struttura per assicurare coerenza, prevenire la deviazione delle chiavi e preservare la formattazione (markdown, HTML, inserimenti, plurali).
• Implementa la gestione dei tentativi (retry) quando l'output è malformato.
• Accoda e parallelizza le richieste tra file, blocchi e locale per massimizzare la velocità.

Niente di tutto questo passa attraverso il contesto dell'agente. La regola d'oro: lascia che l'agente decida cosa internazionalizzare, e lascia a Intlayer il lavoro ripetitivo.

Soluzione

1. Delegare l'estrazione a intlayer extract

Invece di chiedere all'agente di riscrivere ogni componente a mano, fagli eseguire il comando extract. Questo sposta le stringhe hardcoded in un file .content accanto al componente senza caricare l'intero file nel contesto dell'agente.

npx intlayer extract --file src/components/Header.tsx

2. Delegare la traduzione a intlayer fill

Non chiedere mai all'agente di tradurre direttamente. Il comando fill applica la pipeline sopra descritta: invia solo le chiavi mancanti, le suddivide, elabora le locale in parallelo e riscrive il risultato direttamente nei file di contenuto.

npx intlayer fill

Alcuni flag consentono di contenere l'elaborazione:

• --git-diff (o --uncommitted) elabora solo i dizionari modificati nel branch corrente.
• --file o --keys punta a file di contenuto specifici.
• --output-locales fr es limita l'esecuzione alle sole locale necessarie al momento.
• --skip-metadata ignora la generazione di titolo, descrizione e tag.
• --data-serialization toon invia un payload più compatto al modello (meno token, output leggermente meno prevedibile).

npx intlayer fill --git-diff --output-locales fr es --skip-metadata

3. Tradurre il markdown con doc translate e doc review

Chiedere a un agente di tradurre un file .md comporta l'inclusione dell'intero documento, per ogni locale, a ogni modifica. I comandi doc translate e doc review lavorano invece blocco per blocco.

Usa doc translate quando il file tradotto non esiste ancora. Suddivide il markdown, lo traduce in parallelo e crea i file di destinazione:

npx intlayer doc translate --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

Usa doc review quando il file tradotto esiste già. Confronta ogni blocco con il documento base, salta i blocchi già tradotti o invariati e invia solo quelli divergenti:

npx intlayer doc review --doc-pattern "docs/**/*.md" --base-locale en --locales fr es

Entrambi i comandi accettano le tue regole una volta sola, senza doverle ripetere in ogni prompt:

npx intlayer doc translate --custom-instructions "Do not translate URLs. Keep the markdown structure and the code blocks untouched."

Due modalità di doc review sono utili quando l'agente deve rimanere coinvolto nel flusso, senza alcuna chiamata AI da parte di Intlayer:

• --mode report segnala i blocchi che richiedono attenzione, completi di numero di riga, in modo che l'agente modifichi solo quei blocchi.
• --mode synthesis riporta unicamente quali documenti sono aggiornati e quali presentano ancora blocchi da modificare.

npx intlayer doc review --mode report --locales fr

4. Far chiamare la CLI all'agente tramite il server MCP

Grazie al server MCP di Intlayer, l'agente risponde basandosi sulla documentazione aggiornata ed esegue autonomamente intlayer fill o intlayer doc review, invece di dover reimplementare la logica nella conversazione.

claude mcp add intlayer npx -y @intlayer/mcp

Installare le Agent Skills con npx intlayer init skills evita inoltre che l'agente debba indovinare l'API di Intlayer e rileggere la documentazione a ogni task.

5. Riutilizzare l'abbonamento Claude con claude setup-token

Eseguire la configurazione di i18n nella sessione interattiva di Claude Code mantiene l'intera cronologia della conversazione nel contesto. Sposta invece questo carico di lavoro su una breve sessione headless.

Genera un token a lunga durata dal tuo abbonamento Claude:

claude setup-token

Salvalo come CLAUDE_CODE_OAUTH_TOKEN (in un file .env o nei secret della tua CI), quindi riutilizzalo per una sessione mirata che esegua i comandi Intlayer:

CLAUDE_CODE_OAUTH_TOKEN=... claude -p "Run npx intlayer extract on src/components, then npx intlayer fill --uncommitted"

La sessione conterrà solo quel prompt e l'output del comando, evitando tutta la cronologia precedente. Lo stesso token funziona nella Claude Code GitHub Action per eseguire intlayer fill su ogni pull request.

Il token generato da claude setup-token autentica unicamente Claude Code. Non può essere usato come chiave API Anthropic in ai.apiKey. Per la traduzione vera e propria, intlayer fill usa il tuo account Intlayer (piano gratuito incluso) o la tua chiave fornitore configurata in ai.

Riepilogo