← Torna al blog
Terminal output showing a translation script writing de.json and fr.json, alongside a folder tree and a browser rendering the German locale route.

Come tradurre un'app Next.js con PolyLingo in meno di 30 minuti

By Robert

Come tradurre un'app Next.js con PolyLingo in meno di 30 minuti

Alla fine di questo tutorial avrai un progetto Next.js App Router multilingue funzionante: stringhe estratte in messages/en.json, file di localizzazione tradotti per ogni lingua di cui hai bisogno, next-intl che serve il file giusto per ogni percorso e un singolo script Node che puoi rieseguire ogni volta che il tuo contenuto cambia.

Nessuna piattaforma di traduzione a cui iscriversi. Nessuna tariffa fissa per lingua. Una chiamata API gestisce tutte le lingue di destinazione contemporaneamente.

Cosa ti servirà:

  • Un progetto Next.js che utilizza l'App Router (Next.js 14 o 15)
  • Node.js 18 o superiore
  • Un account gratuito PolyLingo e una chiave API

Passo 1: Ottieni la tua chiave API PolyLingo (5 minuti)

Crea un account gratuito su usepolylingo.com. Il piano gratuito include 100.000 token al mese, sufficienti per tradurre un file di localizzazione di medie dimensioni in più di 10 lingue più volte.

Una volta dentro, vai su API keys nella dashboard e crea una chiave. Vedrai il valore completo solo una volta, quindi copialo immediatamente.

Aggiungila al tuo progetto come variabile d'ambiente. Non committarla mai nel controllo versione e non esporla mai nel codice client-side:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Verifica che l'API sia raggiungibile prima di procedere:

curl -sS "https://api.usepolylingo.com/v1/health"

Dovresti ricevere un piccolo payload JSON con "status": "ok".

Passo 2: Installa next-intl e configura il routing (10 minuti)

Installa la libreria:

npm install next-intl

Crea un file i18n.ts nella root del progetto. Questo indica a next-intl quali localizzazioni supporti e come caricare il file di messaggi giusto per ogni richiesta:

// i18n.ts
import { getRequestConfig } from 'next-intl/server'

export const locales = ['en', 'de', 'fr'] as const
export type Locale = (typeof locales)[number]
export const defaultLocale: Locale = 'en'

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale
  if (!locale || !locales.includes(locale as Locale)) {
    locale = defaultLocale
  }
  return {
    locale,
    messages: (await import(`./messages/${locale}.json`)).default,
  }
})

Aggiungi un middleware per anteporre il prefisso della localizzazione alle rotte:

// middleware.ts
import createMiddleware from 'next-intl/middleware'
import { locales, defaultLocale } from './i18n'

export default createMiddleware({
  locales: [...locales],
  defaultLocale,
  localePrefix: 'as-needed',
})

export const config = {
  matcher: ['/((?!api|_next|.*\..*).*)'],
}

Sposta i file delle pagine sotto app/[locale]/. Aggiorna il layout root per ricevere il parametro locale e avvolgere i figli con NextIntlClientProvider:

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl'
import { getMessages } from 'next-intl/server'

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ locale: string }>
}) {
  const { locale } = await params
  const messages = await getMessages()
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  )
}

Passo 3: Estrai le tue stringhe in un file JSON di messaggi (10 minuti)

Crea una cartella messages/ nella root del progetto. Aggiungi un file en.json con le tue stringhe sorgente. next-intl usa una struttura di chiavi annidate:

{
  "Home": {
    "title": "Welcome",
    "cta": "Get started"
  }
}

Aggiorna le tue pagine per usare useTranslations invece di stringhe hardcoded:

// app/[locale]/page.tsx
import { useTranslations } from 'next-intl'

export default function HomePage() {
  const t = useTranslations('Home')
  return (
    <main>
      <h1>{t('title')}</h1>
      <button type="button">{t('cta')}</button>
    </main>
  )
}

Ora scrivi lo script di traduzione. Questo legge messages/en.json, lo invia all'API PolyLingo con format: "json" e scrive un file di output per ogni locale di destinazione. Il flag format: "json" dice all'API di preservare la struttura delle chiavi e tradurre solo i valori stringa — chiavi annidate, array e tipi non stringa tornano intatti.

// scripts/translate-messages.mjs
// Esegui con: node scripts/translate-messages.mjs

import fs from 'node:fs'
import path from 'node:path'

const API_KEY = process.env.POLYLINGO_API_KEY
const API_URL = (process.env.POLYLINGO_API_URL || 'https://api.usepolylingo.com/v1').replace(/\/$/, '')
const TARGETS = ['de', 'fr'] // estendi questo array per aggiungere altre localizzazioni

const enPath = path.join('messages', 'en.json')
const en = JSON.parse(fs.readFileSync(enPath, 'utf8'))

const res = await fetch(`${API_URL}/translate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: JSON.stringify(en),
    format: 'json',
    targets: TARGETS,
    model: 'standard',
  }),
})

if (!res.ok) {
  const err = await res.text()
  throw new Error(`PolyLingo ${res.status}: ${err}`)
}

const { translations } = await res.json()

for (const locale of TARGETS) {
  const out = path.join('messages', `${locale}.json`)
  fs.writeFileSync(out, JSON.stringify(JSON.parse(translations[locale]), null, 2) + '\n')
  console.log('Wrote', out)
}

Eseguilo:

node scripts/translate-messages.mjs

Dovresti vedere un output simile a:

Wrote messages/de.json
Wrote messages/fr.json

Apri quei file e controllali. Le tue chiavi saranno identiche a en.json. Solo i valori stringa saranno cambiati.

Passo 4: Test rapido delle rotte (5 minuti)

Avvia il server di sviluppo:

npm run dev

Visita http://localhost:3000 e http://localhost:3000/de. L'intestazione e il pulsante dovrebbero essere visualizzati rispettivamente in inglese e tedesco. Aggiungi altre localizzazioni estendendo l'array TARGETS nello script e l'array locales in i18n.ts, poi riesegui lo script.

Controlla il tuo utilizzo di token nella dashboard PolyLingo sotto Usage. Per un piccolo file di localizzazione tradotto in due lingue avrai usato poche centinaia di token del tuo credito mensile.

Dove andare da qui

Aggiungi altre localizzazioni. Lo script invia una sola richiesta indipendentemente da quante voci ci siano in TARGETS. Aggiungere giapponese, spagnolo e arabo costa una chiamata API, non tre.

Integralo nella CI. Aggiungi POLYLINGO_API_KEY come segreto del repository in GitHub Actions ed esegui lo script come parte della pipeline di build. I tuoi file di localizzazione rimangono sincronizzati automaticamente ogni volta che en.json cambia.

Traduci altri formati. Lo stesso schema di script funziona per pagine di documentazione Markdown (format: "markdown") e template email HTML (format: "html"). L'API preserva la struttura in tutti i casi.

Usa l'endpoint batch per progetti più grandi. Se hai più file JSON separati (uno per area funzionale, per esempio), POST /translate/batch accetta fino a 100 elementi in una singola richiesta, ciascuno con il proprio id e format.

Provalo gratis

Il piano gratuito di PolyLingo include 100.000 token al mese. Nessuna carta di credito richiesta.

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"Home\":{\"title\":\"Welcome\",\"cta\":\"Get started\"}}",
    "format": "json",
    "targets": ["de", "fr", "es", "ja"]
  }'

Ottieni la tua chiave API