PolyLingo ile 30 dakika içinde Next.js uygulaması nasıl çevrilir

Bu öğreticinin sonunda çalışan çok dilli bir Next.js App Router projeniz olacak: dizeler messages/en.json dosyasına çıkarılmış, ihtiyacınız olan her dil için çevrilmiş yerel dosyalar, next-intl her rota için doğru dosyayı sunuyor ve içeriğiniz değiştiğinde yeniden çalıştırabileceğiniz tek bir Node betiği.

Kayıt olmanız gereken bir çeviri platformu yok. Dil başına sabit ücret yok. Tek bir API çağrısı tüm hedef dillerinizi aynı anda hallediyor.

İhtiyacınız olacak:

App Router kullanan bir Next.js projesi (Next.js 14 veya 15)
Node.js 18 veya üzeri
Ücretsiz bir PolyLingo hesabı ve API anahtarı

Adım 1: PolyLingo API anahtarınızı alın (5 dakika)

usepolylingo.com adresinde ücretsiz bir hesap oluşturun. Ücretsiz katman ayda 100.000 token içerir, bu da orta büyüklükte bir yerel dosyayı 10+ dile birkaç kez çevirmek için yeterlidir.

Hesabınıza girdikten sonra, kontrol panelinde API anahtarları bölümüne gidin ve bir anahtar oluşturun. Tam değeri yalnızca bir kez göreceksiniz, bu yüzden hemen kopyalayın.

Projeye bir ortam değişkeni olarak ekleyin. Asla sürüm kontrolüne göndermeyin ve istemci tarafı kodda asla açığa çıkarmayın:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Devam etmeden önce API'nin erişilebilir olduğunu doğrulayın:

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

Küçük bir JSON yükü içinde "status": "ok" yanıtı almalısınız.

Adım 2: next-intl'i kurun ve yönlendirmeyi ayarlayın (10 dakika)

Kütüphaneyi kurun:

npm install next-intl

Proje kökünde i18n.ts dosyası oluşturun. Bu dosya next-intl'e hangi yerelleri desteklediğinizi ve her istek için doğru mesaj dosyasını nasıl yükleyeceğini söyler:

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

Yönlendirmeleri yerel ile öneklemek için ara katman (middleware) ekleyin:

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

Sayfa dosyalarınızı app/[locale]/ altına taşıyın. Kök düzeninizi (layout) güncelleyerek locale parametresini alın ve çocukları NextIntlClientProvider ile sarın:

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

Adım 3: Dizelerinizi JSON mesaj dosyasına çıkarın (10 dakika)

Proje kökünde messages/ klasörü oluşturun. Kaynak dizelerinizle en.json dosyası ekleyin. next-intl iç içe anahtar yapısı kullanır:

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

Sayfalarınızı sert kodlanmış dizeler yerine useTranslations kullanacak şekilde güncelleyin:

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

Şimdi çeviri betiğini yazın. Bu betik messages/en.json dosyasını okur, PolyLingo API'sine format: "json" ile gönderir ve hedef yerel başına bir çıktı dosyası yazar. format: "json" bayrağı API'ye anahtar yapısını korumasını ve sadece dize değerlerini çevirmesini söyler — iç içe anahtarlar, diziler ve dize olmayan türler değişmeden kalır.

// scripts/translate-messages.mjs
// Çalıştırmak için: 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'] // daha fazla yerel eklemek için bu diziyi genişletin

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

Çalıştırın:

node scripts/translate-messages.mjs

Şu çıktıyı görmelisiniz:

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

Bu dosyaları açın ve kontrol edin. Anahtarlarınız en.json ile aynı olacak. Sadece dize değerleri değişmiş olacak.

Adım 4: Rotaları hızlıca test edin (5 dakika)

Geliştirme sunucunuzu başlatın:

npm run dev

http://localhost:3000 ve http://localhost:3000/de adreslerini ziyaret edin. Başlık ve buton sırasıyla İngilizce ve Almanca olarak render edilmelidir. Betikteki TARGETS dizisini ve i18n.ts içindeki locales dizisini genişleterek daha fazla yerel ekleyin, sonra betiği yeniden çalıştırın.

PolyLingo kontrol panelinde Usage altında token kullanımınızı kontrol edin. İki dile çevrilmiş küçük bir yerel dosya için aylık kotanızdan birkaç yüz token kullanmış olacaksınız.

Buradan sonra ne yapmalı

Daha fazla yerel ekleyin. Betik, TARGETS dizisinde kaç giriş olursa olsun tek bir istek gönderir. Japonca, İspanyolca ve Arapça eklemek bir API çağrısı maliyetindedir, üç değil.

CI'ya entegre edin. GitHub Actions'da POLYLINGO_API_KEY'yi depo sırrı olarak ekleyin ve betiği derleme hattınızın bir parçası olarak çalıştırın. en.json değiştikçe yerel dosyalarınız otomatik olarak senkronize kalır.

Diğer formatları çevirin. Aynı betik deseni Markdown dokümantasyon sayfaları (format: "markdown") ve HTML e-posta şablonları (format: "html") için de çalışır. API tüm durumlarda yapıyı korur.

Daha büyük projeler için toplu uç noktayı kullanın. Birden fazla ayrı JSON dosyanız varsa (örneğin her özellik alanı için bir dosya), POST /translate/batch tek bir istekte 100 öğeye kadar kabul eder, her biri kendi id ve format ile.

Ücretsiz deneyin

PolyLingo'nun ücretsiz katmanı ayda 100.000 token içerir. Kredi kartı gerekmez.

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

API anahtarınızı alın