Πώς να μεταφράσετε μια εφαρμογή Next.js με το PolyLingo σε λιγότερο από 30 λεπτά

Στο τέλος αυτού του σεμιναρίου θα έχετε ένα λειτουργικό πολυγλωσσικό έργο Next.js App Router: συμβολοσειρές εξαγόμενες σε messages/en.json, μεταφρασμένα αρχεία τοπικών ρυθμίσεων για κάθε γλώσσα που χρειάζεστε, το next-intl που εξυπηρετεί το σωστό αρχείο ανά διαδρομή και ένα ενιαίο Node script που μπορείτε να εκτελείτε ξανά όποτε αλλάζει το περιεχόμενό σας.

Δεν χρειάζεται να εγγραφείτε σε πλατφόρμα μετάφρασης. Δεν υπάρχουν σταθερές χρεώσεις ανά γλώσσα. Μία κλήση API χειρίζεται όλες τις γλώσσες στόχους ταυτόχρονα.

Τι θα χρειαστείτε:

Ένα έργο Next.js που χρησιμοποιεί το App Router (Next.js 14 ή 15)
Node.js 18 ή νεότερο
Έναν δωρεάν λογαριασμό PolyLingo και κλειδί API

Βήμα 1: Πάρτε το κλειδί API του PolyLingo (5 λεπτά)

Δημιουργήστε έναν δωρεάν λογαριασμό στο usepolylingo.com. Το δωρεάν επίπεδο περιλαμβάνει 100.000 tokens ανά μήνα, αρκετά για να μεταφράσετε ένα μεσαίου μεγέθους αρχείο τοπικών ρυθμίσεων σε πάνω από 10 γλώσσες αρκετές φορές.

Μόλις μπείτε, πηγαίνετε στα API keys στον πίνακα ελέγχου και δημιουργήστε ένα κλειδί. Θα δείτε την πλήρη τιμή μόνο μία φορά, οπότε αντιγράψτε το αμέσως.

Προσθέστε το στο έργο σας ως μεταβλητή περιβάλλοντος. Μην το δεσμεύετε ποτέ στον έλεγχο έκδοσης και μην το εκθέτετε ποτέ σε κώδικα πελάτη:

# .env.local
POLYLINGO_API_KEY="pl_to_kleidi_sas_edo"

Επαληθεύστε ότι η API είναι προσβάσιμη πριν προχωρήσετε:

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

Θα πρέπει να λάβετε ένα μικρό JSON με "status": "ok".

Βήμα 2: Εγκαταστήστε το next-intl και ρυθμίστε το routing (10 λεπτά)

Εγκαταστήστε τη βιβλιοθήκη:

npm install next-intl

Δημιουργήστε ένα αρχείο i18n.ts στη ρίζα του έργου σας. Αυτό λέει στο next-intl ποιες τοπικές ρυθμίσεις υποστηρίζετε και πώς να φορτώνει το σωστό αρχείο μηνυμάτων για κάθε αίτημα:

// 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,
  }
})

Προσθέστε middleware για να προθέτει τοπική ρύθμιση στις διαδρομές:

// 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|.*\..*).*)'],
}

Μετακινήστε τα αρχεία σελίδων σας κάτω από app/[locale]/. Ενημερώστε το root layout σας για να λαμβάνει την παράμετρο locale και να τυλίγει τα παιδιά με 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>
  )
}

Βήμα 3: Εξαγάγετε τις συμβολοσειρές σας σε αρχείο μηνυμάτων JSON (10 λεπτά)

Δημιουργήστε έναν φάκελο messages/ στη ρίζα του έργου σας. Προσθέστε ένα αρχείο en.json με τις αρχικές σας συμβολοσειρές. Το next-intl χρησιμοποιεί μια δομή με εμφωλευμένα κλειδιά:

{
  "Home": {
    "title": "Καλώς ήρθατε",
    "cta": "Ξεκινήστε"
  }
}

Ενημερώστε τις σελίδες σας να χρησιμοποιούν το useTranslations αντί για σκληροκωδικοποιημένες συμβολοσειρές:

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

Τώρα γράψτε το σενάριο μετάφρασης. Αυτό διαβάζει το messages/en.json, το στέλνει στο PolyLingo API με format: "json" και γράφει ένα αρχείο εξόδου ανά τοπική ρύθμιση στόχου. Η σημαία format: "json" λέει στο API να διατηρήσει τη δομή κλειδιών και να μεταφράσει μόνο τις τιμές συμβολοσειρών — εμφωλευμένα κλειδιά, πίνακες και μη-συμβολοσειρές παραμένουν ανέπαφα.

// scripts/translate-messages.mjs
// Εκτέλεση με: 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'] // επεκτείνετε αυτόν τον πίνακα για να προσθέσετε περισσότερες τοπικές ρυθμίσεις

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

Τρέξτε το:

node scripts/translate-messages.mjs

Θα δείτε έξοδο όπως:

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

Ανοίξτε αυτά τα αρχεία και ελέγξτε τα. Τα κλειδιά σας θα είναι ίδια με το en.json. Μόνο οι τιμές των συμβολοσειρών έχουν αλλάξει.

Βήμα 4: Δοκιμάστε τις διαδρομές (5 λεπτά)

Ξεκινήστε τον dev server σας:

npm run dev

Επισκεφθείτε http://localhost:3000 και http://localhost:3000/de. Ο τίτλος και το κουμπί θα εμφανίζονται στα Αγγλικά και Γερμανικά αντίστοιχα. Προσθέστε περισσότερες τοπικές ρυθμίσεις επεκτείνοντας τον πίνακα TARGETS στο σενάριο και τον πίνακα locales στο i18n.ts, και τρέξτε ξανά το σενάριο.

Ελέγξτε τη χρήση των tokens σας στον πίνακα ελέγχου PolyLingo κάτω από Usage. Για ένα μικρό αρχείο τοπικών ρυθμίσεων που μεταφράστηκε σε δύο γλώσσες, θα έχετε χρησιμοποιήσει μερικές εκατοντάδες tokens από το μηνιαίο σας όριο.

Πού να πάτε από εδώ

Προσθέστε περισσότερες τοπικές ρυθμίσεις. Το σενάριο στέλνει ένα αίτημα ανεξάρτητα από το πόσες εγγραφές υπάρχουν στο TARGETS. Η προσθήκη Ιαπωνικών, Ισπανικών και Αραβικών κοστίζει μία κλήση API, όχι τρεις.

Ενσωματώστε το στο CI. Προσθέστε το POLYLINGO_API_KEY ως μυστικό αποθετηρίου στο GitHub Actions και τρέξτε το σενάριο ως μέρος της διαδικασίας κατασκευής σας. Τα αρχεία τοπικών ρυθμίσεων παραμένουν αυτόματα συγχρονισμένα όποτε αλλάζει το en.json.

Μεταφράστε άλλα φορμάτ. Το ίδιο μοτίβο σεναρίου λειτουργεί για σελίδες τεκμηρίωσης Markdown (format: "markdown") και πρότυπα email HTML (format: "html"). Η API διατηρεί τη δομή σε όλες τις περιπτώσεις.

Χρησιμοποιήστε το batch endpoint για μεγαλύτερα έργα. Αν έχετε πολλά ξεχωριστά αρχεία JSON (ένα ανά περιοχή λειτουργίας, για παράδειγμα), το POST /translate/batch δέχεται έως 100 αντικείμενα σε ένα αίτημα, το καθένα με δικό του id και format.

Δοκιμάστε το δωρεάν

Το δωρεάν επίπεδο του PolyLingo περιλαμβάνει 100.000 tokens ανά μήνα. Δεν απαιτείται πιστωτική κάρτα.

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\":\"Καλώς ήρθατε\",\"cta\":\"Ξεκινήστε\"}}",
    "format": "json",
    "targets": ["de", "fr", "es", "ja"]
  }'

Πάρτε το κλειδί API σας