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

Kuinka kääntää Next.js-sovellus PolyLingolla alle 30 minuutissa

By Robert

Kuinka kääntää Next.js-sovellus PolyLingon avulla alle 30 minuutissa

Tämän opetusohjelman lopussa sinulla on toimiva monikielinen Next.js App Router -projekti: merkkijonot on eroteltu tiedostoon messages/en.json, käännetyt paikallistetut tiedostot jokaista tarvitsemaasi kieltä varten, next-intl palvelee oikeaa tiedostoa reitin mukaan ja sinulla on yksittäinen Node-skripti, jota voit ajaa uudelleen aina kun sisältösi muuttuu.

Ei tarvitse rekisteröityä käännösalustalle. Ei kiinteitä maksuja kielikohtaisesti. Yksi API-kutsu hoitaa kaikki kohdekielesi kerralla.

Mitä tarvitset:

  • Next.js-projektin, joka käyttää App Routeria (Next.js 14 tai 15)
  • Node.js 18 tai uudempi
  • Ilmaisen PolyLingo-tilin ja API-avaimen

Vaihe 1: Hanki PolyLingo API-avain (5 minuuttia)

Luo ilmainen tili osoitteessa usepolylingo.com. Ilmainen taso sisältää 100 000 tokenia kuukaudessa, mikä riittää kääntämään keskikokoisen paikallistustiedoston yli 10 kielelle useita kertoja.

Kun olet kirjautunut sisään, siirry kojelaudalla kohtaan API keys ja luo avain. Näet koko arvon vain kerran, joten kopioi se heti.

Lisää se projektiisi ympäristömuuttujana. Älä koskaan tallenna sitä versionhallintaan äläkä paljasta sitä asiakaspuolen koodissa:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Varmista, että API on saavutettavissa ennen kuin jatkat:

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

Saat pienen JSON-vastauksen, jossa on "status": "ok".

Vaihe 2: Asenna next-intl ja määritä reititys (10 minuuttia)

Asenna kirjasto:

npm install next-intl

Luo i18n.ts-tiedosto projektisi juureen. Tämä kertoo next-intl:lle, mitä kieliä tuet ja miten ladata oikea viestitiedosto jokaista pyyntöä varten:

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

Lisää middleware, joka lisää kieliprefiksin reitteihin:

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

Siirrä sivutiedostosi kansioon app/[locale]/. Päivitä juurilayout vastaanottamaan locale-parametri ja kääri lapset NextIntlClientProvider-komponenttiin:

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

Vaihe 3: Erottele merkkijonot JSON-viestitiedostoon (10 minuuttia)

Luo messages/-kansio projektisi juureen. Lisää en.json-tiedosto lähdemerkkijonoillasi. next-intl käyttää sisäkkäistä avainrakennetta:

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

Päivitä sivusi käyttämään useTranslations-hookia kovakoodattujen merkkijonojen sijaan:

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

Kirjoita nyt käännösskripti. Tämä lukee messages/en.json-tiedoston, lähettää sen PolyLingo API:lle format: "json" -asetuksella ja kirjoittaa yhden ulostulotiedoston jokaista kohdekieltä varten. format: "json" -lippu kertoo API:lle säilyttää avainrakenne ja kääntää vain merkkijonojen arvot — sisäkkäiset avaimet, taulukot ja ei-merkkijonotyypit säilyvät koskemattomina.

// scripts/translate-messages.mjs
// Suorita komennolla: 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'] // laajenna tätä taulukkoa lisätäksesi kieliä

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

Suorita se:

node scripts/translate-messages.mjs

Näet tulosteen kuten:

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

Avaa tiedostot ja tarkista ne. Avaimesi ovat identtisiä en.json-tiedoston kanssa. Vain merkkijonojen arvot ovat muuttuneet.

Vaihe 4: Testaa reitit nopeasti (5 minuuttia)

Käynnistä kehityspalvelin:

npm run dev

Vieraile osoitteissa http://localhost:3000 ja http://localhost:3000/de. Otsikon ja napin pitäisi näkyä englanniksi ja saksaksi vastaavasti. Lisää kieliä laajentamalla TARGETS-taulukkoa skriptissä ja locales-taulukkoa i18n.ts-tiedostossa, ja aja skripti uudelleen.

Tarkista tokenien käyttö PolyLingo-kojelautalta kohdasta Usage. Pienen paikallistustiedoston kääntäminen kahdelle kielelle kuluttaa muutamia satoja tokeneita kuukausittaisesta kiintiöstäsi.

Mihin tästä eteenpäin

Lisää kieliä. Skripti lähettää yhden pyynnön riippumatta siitä, kuinka monta kohdetta TARGETS-taulukossa on. Japanin, espanjan ja arabian lisääminen maksaa yhden API-kutsun, ei kolmea.

Integroi CI:hin. Lisää POLYLINGO_API_KEY GitHub Actionsin repository-salaisuudeksi ja aja skripti osana build-putkea. Paikallistustiedostosi pysyvät synkronoituna automaattisesti aina kun en.json muuttuu.

Käännä muita formaatteja. Sama skriptimalli toimii Markdown-dokumentaatiosivuille (format: "markdown") ja HTML-sähköpostipohjille (format: "html"). API säilyttää rakenteen kaikissa tapauksissa.

Käytä batch-päätepistettä suuremmissa projekteissa. Jos sinulla on useita erillisiä JSON-tiedostoja (esim. yksi per ominaisuusalue), POST /translate/batch hyväksyy jopa 100 kohdetta yhdessä pyynnössä, jokaisella omalla id:llä ja format-asetuksella.

Kokeile ilmaiseksi

PolyLingon ilmainen taso sisältää 100 000 tokenia kuukaudessa. Ei luottokorttia vaadita.

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

Hanki API-avaimesi