← Rudi kwenye blogu
Terminal output showing a translation script writing de.json and fr.json, alongside a folder tree and a browser rendering the German locale route.

Jinsi ya kutafsiri programu ya Next.js na PolyLingo chini ya dakika 30

By Robert

Jinsi ya kutafsiri app ya Next.js kwa PolyLingo chini ya dakika 30

Mwisho wa mafunzo haya utakuwa na mradi wa Next.js App Router unaofanya kazi kwa lugha nyingi: mistari imechukuliwa ndani ya messages/en.json, faili za lugha zilizotafsiriwa kwa kila lugha unayohitaji, next-intl ikihudumia faili sahihi kwa kila njia, na script moja ya Node ambayo unaweza kuirudia wakati wowote maudhui yako yanapobadilika.

Hakuna jukwaa la tafsiri la kujiandikisha. Hakuna ada za kila lugha. Mwito mmoja wa API hushughulikia lugha zako zote za lengo kwa wakati mmoja.

Utahitaji:

  • Mradi wa Next.js unaotumia App Router (Next.js 14 au 15)
  • Node.js 18 au baadaye
  • Akaunti ya bure ya PolyLingo na ufunguo wa API

Hatua ya 1: Pata ufunguo wako wa API wa PolyLingo (dakika 5)

Tengeneza akaunti ya bure kwenye usepolylingo.com. Ngazi ya bure inajumuisha tokeni 100,000 kwa mwezi, ambayo ni ya kutosha kutafsiri faili ya lugha ya ukubwa wa kati kwa lugha zaidi ya 10 mara kadhaa.

Mara tu umeingia, nenda kwenye API keys kwenye dashibodi na tengeneza ufunguo. Utaona thamani kamili mara moja tu, kwa hivyo nakili mara moja.

Uongeze kwenye mradi wako kama variable ya mazingira. Usiiweke kamwe kwenye udhibiti wa toleo na usiufichue kwenye msimbo wa upande wa mteja:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Thibitisha API inapatikana kabla ya kuendelea:

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

Unapaswa kurudishiwa payload ndogo ya JSON yenye "status": "ok".

Hatua ya 2: Sakinisha next-intl na weka routing (dakika 10)

Sakinisha maktaba:

npm install next-intl

Tengeneza faili i18n.ts kwenye mzizi wa mradi wako. Hii inamwambia next-intl ni lugha gani unazounga mkono na jinsi ya kupakia faili sahihi ya ujumbe kwa kila ombi:

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

Ongeza middleware ili kuweka kiambishi awali cha lugha kwenye njia:

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

Hamisha faili zako za ukurasa chini ya app/[locale]/. Sasisha layout yako ya mzizi kupokea param ya locale na kuzunguka watoto na 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>
  )
}

Hatua ya 3: Chukua mistari yako ndani ya faili ya ujumbe wa JSON (dakika 10)

Tengeneza folda messages/ kwenye mzizi wa mradi wako. Ongeza faili en.json na mistari yako ya chanzo. next-intl hutumia muundo wa funguo zilizojazwa:

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

Sasisha kurasa zako kutumia useTranslations badala ya mistari iliyowekwa moja kwa moja:

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

Sasa andika script ya tafsiri. Hii husoma messages/en.json, inaituma kwa API ya PolyLingo na format: "json", na inaandika faili moja ya matokeo kwa kila lugha ya lengo. Bendera ya format: "json" inamwambia API kuhifadhi muundo wa funguo na kutafsiri tu thamani za mistari — funguo zilizojazwa, safu, na aina zisizo za mistari hazibadiliki.

// scripts/translate-messages.mjs
// Endesha na: 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'] // ongeza lugha zaidi kwa kuongeza kwenye array hii

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

Endesha:

node scripts/translate-messages.mjs

Unapaswa kuona matokeo kama:

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

Fungua faili hizo na uzikague. Funguo zako zitakuwa sawa na en.json. Thamani za mistari pekee ndizo zitakazobadilika.

Hatua ya 4: Jaribu njia (dakika 5)

Anzisha seva yako ya maendeleo:

npm run dev

Tembelea http://localhost:3000 na http://localhost:3000/de. Kichwa na kitufe vinapaswa kuonyeshwa kwa Kiingereza na Kijerumani mtawalia. Ongeza lugha zaidi kwa kuongeza kwenye array ya TARGETS kwenye script na array ya locales katika i18n.ts, kisha endesha script tena.

Angalia matumizi ya tokeni zako kwenye dashibodi ya PolyLingo chini ya Usage. Kwa faili ndogo ya lugha iliyotafsiriwa kwa lugha mbili, utatumia mamia machache ya tokeni kutoka kwa mkopo wako wa kila mwezi.

Nenda wapi kutoka hapa

Ongeza lugha zaidi. Script hutuma ombi moja bila kujali ni maingizo mangapi yaliyomo kwenye TARGETS. Kuongeza Kijapani, Kihispania, na Kiarabu kunagharimu mwito mmoja wa API, si mitatu.

Unganisha na CI. Ongeza POLYLINGO_API_KEY kama siri ya hifadhi kwenye GitHub Actions na endesha script kama sehemu ya mchakato wako wa kujenga. Faili zako za lugha zitabaki ziko sawa kila wakati en.json inapotabadilika.

Tafsiri fomati nyingine. Mfano huo huo wa script hufanya kazi kwa kurasa za nyaraka za Markdown (format: "markdown") na templeti za barua pepe za HTML (format: "html"). API huhifadhi muundo katika kila kesi.

Tumia endpoint ya batch kwa miradi mikubwa. Ikiwa una faili nyingi za JSON tofauti (moja kwa kila eneo la kipengele, kwa mfano), POST /translate/batch inakubali hadi vitu 100 katika ombi moja, kila moja ikiwa na id na format yake.

Jaribu bure

Ngazi ya bure ya PolyLingo inajumuisha tokeni 100,000 kwa mwezi. Hakuna kadi ya mkopo inahitajika.

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

Pata ufunguo wako wa API