← Zpět na 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.

Jak přeložit aplikaci Next.js pomocí PolyLingo za méně než 30 minut

By Robert

Jak přeložit aplikaci Next.js pomocí PolyLingo za méně než 30 minut

Na konci tohoto tutoriálu budete mít funkční vícejazyčný projekt Next.js App Router: řetězce extrahované do messages/en.json, přeložené soubory lokalizace pro každý požadovaný jazyk, next-intl poskytující správný soubor pro každou trasu a jeden Node skript, který můžete znovu spustit kdykoli se váš obsah změní.

Není potřeba se registrovat na žádné překladatelské platformě. Žádné paušální poplatky za jazyk. Jeden API volání zvládne všechny vaše cílové jazyky najednou.

Co budete potřebovat:

  • Projekt Next.js používající App Router (Next.js 14 nebo 15)
  • Node.js 18 nebo novější
  • Zdarma účet PolyLingo a API klíč

Krok 1: Získejte svůj PolyLingo API klíč (5 minut)

Vytvořte si zdarma účet na usepolylingo.com. Bezplatný tarif zahrnuje 100 000 tokenů měsíčně, což je dost na překlad středně velkého lokalizačního souboru do více než 10 jazyků několikrát.

Jakmile jste přihlášeni, přejděte do API keys v dashboardu a vytvořte klíč. Celou hodnotu uvidíte pouze jednou, proto ji ihned zkopírujte.

Přidejte ji do svého projektu jako proměnnou prostředí. Nikdy ji nezveřejňujte ve verzovacím systému ani v klientském kódu:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

Ověřte, že je API dostupné, než budete pokračovat:

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

Měli byste obdržet malou JSON odpověď s "status": "ok".

Krok 2: Nainstalujte next-intl a nastavte směrování (10 minut)

Nainstalujte knihovnu:

npm install next-intl

Vytvořte soubor i18n.ts v kořenovém adresáři projektu. Tento soubor říká next-intl, jaké lokalizace podporujete a jak načíst správný soubor zpráv pro každý požadavek:

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

Přidejte middleware, který přidá prefix s lokalizací do tras:

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

Přesuňte své soubory stránek do app/[locale]/. Aktualizujte svůj kořenový layout tak, aby přijímal parametr locale a obaloval děti pomocí 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>
  )
}

Krok 3: Extrahujte své řetězce do JSON souboru zpráv (10 minut)

Vytvořte složku messages/ v kořenovém adresáři projektu. Přidejte soubor en.json se svými zdrojovými řetězci. next-intl používá vnořenou strukturu klíčů:

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

Aktualizujte své stránky, aby používaly useTranslations místo pevně zakódovaných řetězců:

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

Nyní napište překladový skript. Ten načte messages/en.json, odešle jej na PolyLingo API s format: "json" a zapíše jeden výstupní soubor pro každou cílovou lokalizaci. Příznak format: "json" říká API, aby zachovalo strukturu klíčů a přeložilo pouze hodnoty řetězců — vnořené klíče, pole a netextové typy zůstanou nedotčeny.

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

Spusťte jej:

node scripts/translate-messages.mjs

Měli byste vidět výstup jako:

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

Otevřete tyto soubory a zkontrolujte je. Vaše klíče budou identické s en.json. Změní se pouze hodnoty řetězců.

Krok 4: Rychlý test tras (5 minut)

Spusťte svůj vývojový server:

npm run dev

Navštivte http://localhost:3000 a http://localhost:3000/de. Nadpis a tlačítko by měly být vykresleny v angličtině a němčině. Přidejte další lokalizace rozšířením pole TARGETS ve skriptu a pole locales v i18n.ts, poté skript znovu spusťte.

Zkontrolujte využití tokenů v PolyLingo dashboardu pod Usage. Pro malý lokalizační soubor přeložený do dvou jazyků jste použili několik stovek tokenů z měsíčního limitu.

Kam dál

Přidejte více lokalizací. Skript odešle jeden požadavek bez ohledu na počet položek v TARGETS. Přidání japonštiny, španělštiny a arabštiny stojí jedno API volání, ne tři.

Propojte to s CI. Přidejte POLYLINGO_API_KEY jako tajný klíč repozitáře v GitHub Actions a spusťte skript jako součást vašeho build pipeline. Vaše lokalizační soubory zůstanou automaticky synchronizované kdykoli se změní en.json.

Překládejte jiné formáty. Stejný vzor skriptu funguje pro Markdown dokumentační stránky (format: "markdown") a HTML emailové šablony (format: "html"). API zachovává strukturu ve všech případech.

Použijte dávkový endpoint pro větší projekty. Pokud máte více samostatných JSON souborů (například jeden pro každou oblast funkce), POST /translate/batch přijímá až 100 položek v jednom požadavku, každá s vlastním id a format.

Vyzkoušejte zdarma

Bezplatný tarif PolyLingo zahrnuje 100 000 tokenů měsíčně. Kreditní karta není potřeba.

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

Získejte svůj API klíč