← 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 menterjemah aplikasi Next.js dengan PolyLingo dalam masa kurang daripada 30 minit

By Robert

Cara menterjemah aplikasi Next.js dengan PolyLingo dalam masa kurang dari 30 minit

Menjelang akhir tutorial ini, anda akan mempunyai projek Next.js App Router berbilang bahasa yang berfungsi: rentetan diekstrak ke dalam messages/en.json, fail locale yang diterjemah untuk setiap bahasa yang anda perlukan, next-intl menyajikan fail yang betul bagi setiap laluan, dan satu skrip Node yang boleh anda jalankan semula bila-bila masa kandungan anda berubah.

Tiada platform terjemahan untuk didaftar. Tiada yuran rata per bahasa. Satu panggilan API mengendalikan semua bahasa sasaran anda sekaligus.

Apa yang anda perlukan:

  • Projek Next.js yang menggunakan App Router (Next.js 14 atau 15)
  • Node.js 18 atau lebih baru
  • Akaun PolyLingo percuma dan kunci API

Langkah 1: Dapatkan kunci API PolyLingo anda (5 minit)

Buat akaun percuma di usepolylingo.com. Tahap percuma termasuk 100,000 token sebulan, yang cukup untuk menterjemah fail locale bersaiz sederhana ke dalam 10+ bahasa beberapa kali.

Setelah anda masuk, pergi ke API keys dalam papan pemuka dan buat kunci. Anda hanya akan melihat nilai penuh sekali sahaja, jadi salin segera.

Tambahkannya ke projek anda sebagai pembolehubah persekitaran. Jangan sekali-kali komit ke kawalan versi dan jangan dedahkan dalam kod sisi klien:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Sahkan API boleh dicapai sebelum meneruskan:

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

Anda sepatutnya mendapat kembali muatan JSON kecil dengan "status": "ok".

Langkah 2: Pasang next-intl dan sediakan routing (10 minit)

Pasang perpustakaan:

npm install next-intl

Buat fail i18n.ts di akar projek anda. Ini memberitahu next-intl locale yang anda sokong dan cara memuatkan fail mesej yang betul 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,
  }
})

Tambah middleware untuk menambah awalan laluan dengan locale:

// 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 fail halaman anda ke bawah app/[locale]/. Kemas kini susun atur akar anda untuk menerima param locale dan bungkus anak 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 rentetan anda ke dalam fail mesej JSON (10 minit)

Buat folder messages/ di akar projek anda. Tambah fail en.json dengan rentetan sumber anda. next-intl menggunakan struktur kunci bersarang:

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

Kemas kini halaman anda untuk menggunakan useTranslations dan bukannya rentetan keras:

// 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, menghantarnya ke API PolyLingo dengan format: "json", dan menulis satu fail output bagi setiap locale sasaran. Flag format: "json" memberitahu API untuk mengekalkan struktur kunci dan hanya menterjemah nilai rentetan — kunci bersarang, tatasusunan, dan jenis bukan rentetan semuanya kembali tanpa diubah.

// scripts/translate-messages.mjs
// Run with: 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'] // extend this array to add more locales

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 sepatutnya melihat output seperti:

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

Buka fail tersebut dan periksa. Kunci anda akan sama dengan en.json. Hanya nilai rentetan yang berubah.

Langkah 4: Uji laluan (5 minit)

Mulakan pelayan pembangunan anda:

npm run dev

Lawati http://localhost:3000 dan http://localhost:3000/de. Tajuk dan butang harus dipaparkan dalam Bahasa Inggeris dan Jerman masing-masing. Tambah lebih banyak locale dengan meluaskan array TARGETS dalam skrip dan array locales dalam i18n.ts, kemudian jalankan semula skrip.

Semak penggunaan token anda dalam papan pemuka PolyLingo di bawah Usage. Untuk fail locale kecil yang diterjemah ke dua bahasa, anda akan menggunakan beberapa ratus token daripada kuota bulanan anda.

Dari sini ke mana

Tambah lebih banyak locale. Skrip menghantar satu permintaan tanpa mengira berapa banyak entri dalam TARGETS. Menambah Jepun, Sepanyol, dan Arab hanya memerlukan satu panggilan API, bukan tiga.

Sambungkan ke CI. Tambah POLYLINGO_API_KEY sebagai rahsia repositori dalam GitHub Actions dan jalankan skrip sebagai sebahagian daripada saluran binaan anda. Fail locale anda akan sentiasa diselaraskan secara automatik bila-bila masa en.json berubah.

Terjemah format lain. Corak skrip yang sama berfungsi untuk halaman dokumentasi Markdown (format: "markdown") dan templat e-mel HTML (format: "html"). API mengekalkan struktur dalam semua kes.

Gunakan titik akhir batch untuk projek lebih besar. Jika anda mempunyai beberapa fail JSON berasingan (satu bagi setiap kawasan ciri, contohnya), POST /translate/batch menerima sehingga 100 item dalam satu permintaan, setiap satu dengan id dan format sendiri.

Cuba secara percuma

Tahap percuma PolyLingo termasuk 100,000 token sebulan. Tiada kad kredit diperlukan.

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