Next.js + PolyLingo

Dodaj wielojęzyczność do swojej aplikacji Next.js.

Tłumacz pliki lokalizacji, zawartość Markdown i strony HTML za pomocą jednego wywołania API. Działa z App Router, next-intl i dowolną konfiguracją routingu i18n.

App Router
Obsługiwane Next.js 13–15
next-intl
natywna integracja
10 języków
jedno uruchomienie skryptu
~3s
typowy czas działania skryptu tłumaczącego

Next.js zapewnia routing. Nie zapewnia tłumaczeń.

Next.js App Router ma doskonałe wbudowane wsparcie dla routingu opartego na lokalizacji. Biblioteki takie jak next-intl ułatwiają zarządzanie plikami tłumaczeń i przełączanie lokalizacji. Nie rozwiązują jednak samego tłumaczenia — ktoś musi przygotować przetłumaczoną zawartość w każdym języku, a tym kimś zazwyczaj jesteś Ty. Dla większości zespołów proces wygląda tak: kopiuj angielski JSON do DeepL, popraw formatowanie, które się psuje, wklej wynik z powrotem, powtarzaj dla każdego języka. To powolne, podatne na błędy i nie skalowalne.

Najczęstszy workflow to pisanie wszystkich tekstów UI po angielsku w kodzie źródłowym, a następnie tłumaczenie pliku messages.json dla każdego języka docelowego. Teoretycznie jest to proste. W praktyce utrzymanie synchronizacji ponad 10 plików lokalizacji z zmianami w źródle staje się powtarzającym się problemem. Za każdym razem, gdy zmienia się angielski tekst, każdy plik lokalizacji wymaga aktualizacji. Korzystając ze standardowych API tłumaczeniowych, nazwy kluczy ulegają uszkodzeniu, zmienne zastępcze są tłumaczone, a struktura JSON różni się między lokalizacjami — powodując subtelne błędy w czasie działania, które trudno zlokalizować.

PolyLingo wpasowuje się w Twoją istniejącą konfigurację i18n Next.js.

Jeśli używasz next-intl lub innej biblioteki i18n, Twoje wiadomości są już w formacie JSON. PolyLingo bierze ten JSON, przesyła go przez model tłumaczeniowy i zwraca przetłumaczone kopie dla każdego docelowego języka — z zachowaniem kluczy, struktury zagnieżdżenia i poprawnym tłumaczeniem wartości tekstowych. Możesz wywołać to z poziomu skryptu budującego, webhooka lub interfejsu PolyLingo. Wynik trafia bezpośrednio do katalogu z wiadomościami.

Workflow: napisz swój angielski messages.json. Uruchom jeden skrypt, który wywołuje API PolyLingo z Twoim plikiem źródłowym i wszystkimi kodami języków docelowych. Otrzymaj jeden przetłumaczony plik JSON na język, o identycznej strukturze. Zapisz każdy w katalogu messages/. Zacommituj. Gotowe.

Dla stron z dużą ilością treści w Markdown w CMS (Sanity, Contentful) ta sama metoda dotyczy treści: eksportuj jako Markdown lub HTML, tłumacz, zapisz z powrotem do CMS przez jego API. Cały proces może działać jako krok budowania lub na wyzwalacz webhooka.

Skrypt tłumaczący PolyLingo — to repozytorium zawiera translate-messages.mjs
// This repository: frontend/scripts/translate-messages.mjs
// Chunks large namespaces (e.g. home) so the model stays within output limits.
//
//   export POLYLINGO_API_KEY=pl_xxx
//   npm run i18n:polylingo
//
// Writes messages/es.json, fr.json, … from messages/en.json via POST /v1/translate
// with format: "json". See MARKETING_I18N.md for options and CI notes.
//
// Minimal one-shot pattern (fine for small message files):
//
// const source = readFileSync('./messages/en.json', 'utf8')
// const { translations } = await fetch(apiUrl + '/translate', {
//   method: 'POST',
//   headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
//   body: JSON.stringify({
//     content: source, format: 'json', source: 'en',
//     targets: ['es', 'fr', 'de'], model: 'standard',
//   }),
// }).then((r) => r.json())
//
// for (const [lang, raw] of Object.entries(translations)) {
//   const obj = typeof raw === 'string' ? JSON.parse(raw) : raw
//   writeFileSync(`./messages/${lang}.json`, JSON.stringify(obj, null, 2))
// }
i18n.ts — konfiguracja next-intl v4
// i18n.ts (next-intl v4)
import { getRequestConfig } from 'next-intl/server'

export const locales = [
  'en', 'ar', 'bn', 'cs', 'da', 'de', 'el', 'es', 'fa', 'fi',
  'fr', 'he', 'hi', 'id', 'it', 'ja', 'ko', 'ms', 'nl', 'no',
  'pl', 'pt', 'ru', 'sv', 'sw', 'th', 'tr', 'uk', 'vi', 'zh',
] as const
export type Locale = (typeof locales)[number]

export default getRequestConfig(async ({ requestLocale }) => {
  const locale = await requestLocale
  return {
    locale,
    messages: (await import(`./messages/${locale}.json`)).default,
  }
})
package.json — dodaj tłumaczenie do pipeline budowania
// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "i18n:polylingo": "node scripts/translate-messages.mjs",
    "translate:build": "npm run i18n:polylingo && next build"
  }
}

Dlaczego PolyLingo pasuje do workflow i18n Next.js

  • Tłumacz pliki messages/*.json bezpośrednio — klucze zawsze zachowane
  • Tłumacz zawartość Markdown dla postów na blogu i stron dokumentacji
  • Działa z next-intl, next-i18next i niestandardowymi konfiguracjami
  • REST API integruje się ze skryptami budującymi i webhookami CMS
  • Wszystkie 36 języków w jednym żądaniu
  • Darmowy plan — 100 000 tokenów miesięcznie
  • To repozytorium używa tego workflow: npm run i18n:polylingo regeneruje lokalizacje marketingowe z messages/en.json (patrz MARKETING_I18N.md).
  • Działa z App Router i Pages Router
  • Pliki wyjściowe gotowe do commitowania — bez potrzeby zmiany formatowania

Skonfiguruj wielojęzyczność w swojej aplikacji Next.js

1

Skonfiguruj next-intl z angielskim plikiem wiadomości

Zainstaluj next-intl i skonfiguruj i18n.ts oraz middleware. Napisz wszystkie teksty UI w messages/en.json. Struktura pliku dowolna — płaska lub zagnieżdżona. To będzie Twoje jedyne źródło prawdy.

2

Uruchom skrypt tłumaczący

Użyj PolyLingo JSON API z małym skryptem Node (patrz kod powyżej). W tym monorepo uruchom npm run i18n:polylingo z frontend/ z ustawionym POLYLINGO_API_KEY — dzieli duże przestrzenie nazw dla niezawodności. Typowe uruchomienia trwają znacznie poniżej minuty dla pełnego pakietu marketingowego.

3

Zacommituj pliki lokalizacji i wdroż

Wygenerowane pliki lokalizacji to poprawny JSON o identycznej strukturze jak źródło. Zacommituj je do repozytorium. Dodaj skrypt tłumaczący do pipeline CI, aby utrzymać synchronizację lokalizacji przy każdej zmianie treści.

Przypadki użycia wielojęzyczności Next.js

🚀

Aplikacje SaaS i pulpity

Przetłumacz całą bibliotekę tekstów UI w jednym uruchomieniu skryptu. Obsługuje wszystkie funkcje formatowania next-intl — daty, liczby, liczby mnogie — ponieważ struktura JSON jest dokładnie zachowana.

📰

Strony z treścią i blogi

Dla stron Next.js z dużą ilością treści korzystających z Sanity lub Contentful, użyj PolyLingo do tłumaczenia treści stron oraz tekstów UI — to samo API, te same gwarancje zachowania formatu.

🛒

E-commerce z wariantami regionalnymi

Tłumacz nazwy produktów, opisy, strony kategorii i UI koszyka. Używaj modelu Advanced do tekstów marketingowych, gdzie liczy się głos marki, Standard do funkcjonalnych tekstów UI.

Najczęściej zadawane pytania

Czy to działa z Next.js App Router?

Tak. Integracja PolyLingo to po prostu skrypt, który czyta i zapisuje pliki JSON — nie zależy od wewnętrznych mechanizmów Next.js. Działa z App Router, Pages Router lub dowolnym frameworkiem. Przykład konfiguracji next-intl pokazany używa API v4 z requestLocale, kompatybilnego z Next.js 13, 14 i 15.

Co jeśli mój messages.json często się zmienia?

Zalecany wzorzec to dodanie skryptu tłumaczącego do pipeline CI/CD, wywoływanego przy zmianach w messages/en.json. To automatycznie utrzymuje synchronizację wszystkich plików lokalizacji. Dla zespołów z częstymi zmianami tekstów zapobiega to dryfowi lokalizacji.

Czy PolyLingo działa z next-i18next tak samo jak z next-intl?

Tak. next-i18next używa tej samej struktury JSON lokalizacji. Skrypt tłumaczący działa identycznie — wskaż katalog public/locales/en/ i zapisz wyniki do innych katalogów lokalizacji. Kompatybilność formatu JSON jest taka sama.

A co z dynamiczną zawartością, która nie jest w pliku wiadomości?

Dynamiczna zawartość — posty na blogu, opisy produktów, treści generowane przez użytkowników — powinna być tłumaczona na poziomie danych, w CMS lub przez skrypt budujący, który przetwarza zawartość przed dotarciem do Next.js. PolyLingo obsługuje Markdown, HTML i zwykły tekst równie dobrze do tego celu.

Czy mogę tłumaczyć tylko teksty zmienione od ostatniego uruchomienia?

Tłumaczenie przyrostowe (tylko zmienionych kluczy) jest w planach. Obecnie skrypt tłumaczy cały plik. Dla większości plików wiadomości (poniżej 20KB) jest to wystarczająco szybkie, by uruchamiać przy każdym commicie. Dla bardzo dużych plików zaleca się dzielenie na przestrzenie nazw.

Czy jest sposób, by przejrzeć tłumaczenia przed wdrożeniem?

Zalecany wzorzec to commitowanie przetłumaczonych plików lokalizacji do osobnej gałęzi lub PR do przeglądu przed scaleniem do main. To standardowa praktyka dla zespołów potrzebujących ludzkiej kontroli jakości tłumaczeń. PolyLingo generuje dobry pierwszy draft — dla większości tekstów UI wynik modelu Standard nie wymaga edycji.

Przetłumacz swój pierwszy plik lokalizacji w mniej niż 5 minut.

Darmowy klucz API. Bez karty kredytowej. Wklej swój JSON z wiadomościami i zobacz wynik od razu.

Uzyskaj swój klucz API

Skrypt tłumaczący konfiguruje się w 5 minut. Darmowy plan — bez karty kredytowej.

Dodaj wielojęzyczność do swojej aplikacji Next.js — PolyLingo | PolyLingo