← Kembali ke 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.

Cara menerjemahkan aplikasi Next.js dengan PolyLingo dalam waktu kurang dari 30 menit

By Robert

Cara menerjemahkan aplikasi Next.js dengan PolyLingo dalam waktu kurang dari 30 menit

Pada akhir tutorial ini Anda akan memiliki proyek Next.js App Router multibahasa yang berfungsi: string diekstrak ke dalam messages/en.json, file lokal terjemahan untuk setiap bahasa yang Anda butuhkan, next-intl menyajikan file yang tepat per rute, dan sebuah skrip Node tunggal yang dapat Anda jalankan ulang kapan pun konten Anda berubah.

Tidak perlu mendaftar platform terjemahan. Tidak ada biaya tetap per bahasa. Satu panggilan API menangani semua bahasa target Anda sekaligus.

Yang Anda butuhkan:

  • Proyek Next.js yang menggunakan App Router (Next.js 14 atau 15)
  • Node.js 18 atau lebih baru
  • Akun PolyLingo gratis dan kunci API

Langkah 1: Dapatkan kunci API PolyLingo Anda (5 menit)

Buat akun gratis di usepolylingo.com. Tingkat gratis mencakup 100.000 token per bulan, yang cukup untuk menerjemahkan file lokal berukuran sedang ke lebih dari 10 bahasa beberapa kali.

Setelah masuk, buka API keys di dashboard dan buat kunci. Anda hanya akan melihat nilai lengkapnya sekali, jadi salin segera.

Tambahkan ke proyek Anda sebagai variabel lingkungan. Jangan pernah meng-commit ke kontrol versi dan jangan pernah mengeksposnya di kode sisi klien:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Verifikasi API dapat dijangkau sebelum melanjutkan:

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

Anda harus mendapatkan payload JSON kecil dengan nilai "status": "ok".

Langkah 2: Instal next-intl dan atur routing (10 menit)

Instal perpustakaan:

npm install next-intl

Buat file i18n.ts di root proyek Anda. Ini memberi tahu next-intl bahasa lokal mana yang Anda dukung dan cara memuat file pesan yang tepat untuk setiap permintaan:

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

Tambahkan middleware untuk menambahkan prefix bahasa pada rute:

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

Pindahkan file halaman Anda ke bawah app/[locale]/. Perbarui layout root Anda untuk menerima parameter locale dan membungkus children dengan 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>
  )
}

Langkah 3: Ekstrak string Anda ke file pesan JSON (10 menit)

Buat folder messages/ di root proyek Anda. Tambahkan file en.json dengan string sumber Anda. next-intl menggunakan struktur kunci bersarang:

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

Perbarui halaman Anda untuk menggunakan useTranslations alih-alih string yang dikodekan langsung:

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

Sekarang tulis skrip terjemahan. Ini membaca messages/en.json, mengirimkannya ke API PolyLingo dengan format: "json", dan menulis satu file output per locale target. Flag format: "json" memberi tahu API untuk mempertahankan struktur kunci dan hanya menerjemahkan nilai string — kunci bersarang, array, dan tipe non-string tetap tidak berubah.

// scripts/translate-messages.mjs
// Jalankan dengan: 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'] // perpanjang array ini untuk menambah locale
 
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)
}

Jalankan:

node scripts/translate-messages.mjs

Anda akan melihat output seperti:

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

Buka file tersebut dan periksa. Kunci Anda akan identik dengan en.json. Hanya nilai string yang berubah.

Langkah 4: Uji coba rute (5 menit)

Mulai server pengembangan Anda:

npm run dev

Kunjungi http://localhost:3000 dan http://localhost:3000/de. Judul dan tombol harus tampil dalam bahasa Inggris dan Jerman masing-masing. Tambah locale dengan memperluas array TARGETS dalam skrip dan array locales di i18n.ts, lalu jalankan ulang skrip.

Periksa penggunaan token Anda di dashboard PolyLingo di bawah Usage. Untuk file lokal kecil yang diterjemahkan ke dua bahasa, Anda akan menggunakan beberapa ratus token dari kuota bulanan Anda.

Kemana selanjutnya

Tambah lebih banyak locale. Skrip mengirim satu permintaan terlepas dari berapa banyak entri di TARGETS. Menambahkan bahasa Jepang, Spanyol, dan Arab hanya membutuhkan satu panggilan API, bukan tiga.

Integrasikan ke CI. Tambahkan POLYLINGO_API_KEY sebagai secret repositori di GitHub Actions dan jalankan skrip sebagai bagian dari pipeline build Anda. File locale Anda akan tetap sinkron otomatis setiap kali en.json berubah.

Terjemahkan format lain. Pola skrip yang sama bekerja untuk halaman dokumentasi Markdown (format: "markdown") dan template email HTML (format: "html"). API mempertahankan struktur dalam semua kasus.

Gunakan endpoint batch untuk proyek besar. Jika Anda memiliki beberapa file JSON terpisah (misalnya satu per area fitur), POST /translate/batch menerima hingga 100 item dalam satu permintaan, masing-masing dengan id dan format sendiri.

Coba gratis

Tingkat gratis PolyLingo mencakup 100.000 token per bulan. Tidak perlu kartu kredit.

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

Dapatkan kunci API Anda