Jak tłumaczyć pliki JSON i18next w React i Next.js (2026)

Właśnie ukończyłeś aplikację React, która musi zostać wydana w 12 językach do przyszłego piątku. Twoje pliki lokalizacji znajdują się w public/locales/en/common.json, masz 340 kluczy na każdą lokalizację, a tokeny w twoich ciągach znaków wyglądają jak {{userName}} i {{count}} rozsiane po zagnieżdżonych obiektach. Wklejasz JSON do ChatGPT, a on zwraca {{ nombreUsuario }}, dodatkowe spacje i połowę kluczy liczby mnogiej zmienionych. Twoja aplikacja ulega awarii podczas kompilacji.

Jeśli próbowałeś zautomatyzować tłumaczenie JSON i18next, znasz ten ból. Format JSON jest elastyczny, i właśnie dlatego większość narzędzi do tłumaczenia go zniekształca. Prawdziwym problemem nie jest jakość modelu językowego – problem w tym, że narzędzia AI dla konsumentów nie rozumieją reguł strukturalnych i18next.

Ten przewodnik omawia, co odróżnia JSON i18next od innych formatów lokalizacji, dlaczego naiwne podejścia do tłumaczenia psują aplikacje React i Next.js, oraz jak bezpiecznie zautomatyzować tłumaczenie w dziesiątkach lokalizacji bez ręcznego przeglądania każdego klucza.

Co to jest JSON i18next i dlaczego tłumaczenie jest trudne

i18next to najczęściej używana biblioteka i18n w ekosystemie JavaScript. Wspiera React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue i usługi backendowe Node. Przechowuje przetłumaczalne ciągi znaków w płaskich lub zagnieżdżonych plikach JSON, po jednym dla każdej lokalizacji.

Typowy plik wygląda tak:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

To wygląda prosto, ale trzy rzeczy sprawiają, że tłumaczenie go za pomocą ogólnego AI jest niebezpieczne.

Tokeny Interpolacji Są Strukturalne, Nie Tekstowe

Sekwencja {{userName}} nie jest słowem – to symbol zastępczy, który środowisko wykonawcze zastępuje danymi. Dodaj spację ({{ userName }}), zmień nazwę lub przetłumacz wewnętrzny identyfikator, a środowisko wykonawcze zawiedzie po cichu lub zgłosi błąd. Niektórzy tłumacze 'pomocnie' konwertują {{count}} na {{conteo}} w języku hiszpańskim. Twoja aplikacja próbuje teraz interpolować zmienną, która nie istnieje i wyświetla użytkownikowi surowy symbol zastępczy.

Klucze Pluralizacji to Magiczne Sufiksy

i18next wykrywa liczbę mnogą za pomocą sufiksów: _zero, _one, _two, _few, _many, _other. To nie są dowolne ciągi znaków – muszą odpowiadać kategoriom liczby mnogiej CLDR dla docelowej lokalizacji. Angielski używa tylko _one i _other. Rosyjski, arabski i polski używają do sześciu kategorii. Jeśli Twój tłumacz pominie _other lub zmieni jego nazwę, łańcuch zastępczy zostanie przerwany.

Zagnieżdżone Klucze Muszą Pozostać Nienaruszone

W przeciwieństwie do plików Gettext .po, które są płaskimi parami klucz-wartość, pliki i18next mogą być dowolnie zagnieżdżone. Leniwy tłumacz może spłaszczyć strukturę, zmienić nazwy kluczy tak, aby pasowały do przetłumaczonego tekstu, lub zmienić kolejność obiektów. Twoje wywołanie t('cart.items_other') w kodzie przestaje działać.

Złe Rozwiązania, Które Deweloperzy Próbują Najpierw

Każdy zespół przechodzi przez ten sam trzystopniowy cykl błędów, zanim zainwestuje w prawdziwe rozwiązanie.

Etap Pierwszy: Wklejanie do ChatGPT

Kopiujesz 200 kluczy do ChatGPT, pytasz „przetłumacz ten JSON na hiszpański” i wklejasz wynik z powrotem. Działa dla 180 kluczy. Dwudziestu dodano spacje wewnątrz {{...}}, trzem przepisano sufiksy liczby mnogiej, a jeden tag <strong> został przetłumaczony na <fuerte>. Twoja kompilacja albo zawodzi, albo cicho wysyła uszkodzone ciągi znaków na produkcję.

Etap Drugi: Google Translate API

Podłączasz Google Translate REST API, iterujesz po swoim JSON i wysyłasz każdą wartość. Prędkość jest świetna. Jakość – już nie. API Google traktuje każdy ciąg znaków w izolacji – brak kontekstu o Twojej aplikacji, brak zrozumienia, że {{count}} to symbol zastępczy, brak świadomości, że klucz cart.empty różni się od cart.items_one. Nadal potrzebujesz ludzkiego przeglądu każdego klucza.

Etap Trzeci: Komercyjne Platformy TMS

Zapisujesz się do systemu zarządzania tłumaczeniami. Pobierają opłaty za słowo, wymagają integracji z GitHub i wiążą Cię miesięcznymi subskrypcjami. Dla projektu pobocznego lub aplikacji niezależnej, ekonomia szybko się załamuje – a Ty nadal napotykasz te same problemy z uszkodzeniem symboli zastępczych, jeśli ich silnik nie przetwarza specjalnie formatu i18next.

Te same tryby błędów pojawiają się również w przepływach pracy Gettext. Nasz przewodnik na temat jak tłumaczyć pliki .po bez psucia zmiennych kodu omawia analogiczny problem dla WordPress i innych stosów opartych na Gettext.

Bezpieczne Podejście: Tłumaczenie Świadome Składni

Jedynym niezawodnym sposobem na skalowanie tłumaczenia i18next JSON jest użycie narzędzia, które najpierw analizuje format, blokuje składnię i wysyła tylko przetłumaczalny tekst do AI.

Oto, co robi przetwarzanie świadome składni pod spodem:

1. Analizuje JSON do abstrakcyjnego drzewa, zachowując ścieżki kluczy i zagnieżdżenia.
2. Identyfikuje tokeny interpolacji ({{name}}, {{count, number}}, {{date, datetime}}) i zastępuje je identyfikatorami symboli zastępczych.
3. Identyfikuje tagi HTML wewnątrz komponentów Trans (<0>, <strong>, <br/>) i je blokuje.
4. Wykrywa klucze liczby mnogiej po sufiksie i mapuje je do reguł CLDR dla docelowej lokalizacji.
5. Wysyła tylko oczyszczony tekst do LLM z kontekstem ścieżki klucza.
6. Ponownie wstawia oryginalne tokeny i tagi w ich dokładnych pozycjach.
7. Waliduje wynik – jeśli brakuje jakiegokolwiek symbolu zastępczego lub jest źle sformułowany, wraca do źródła.

To ta sama zasada, która sprawia, że tłumaczenie PO oparte na chmurze jest bezpieczne. Jeśli jesteś ciekawy podstawowej architektury, nasze porównanie jakości tłumaczeń AI szczegółowo opisuje, jak różne LLM-y radzą sobie z tymi ograniczeniami.

Krok po Kroku: Tłumaczenie i18next JSON za pomocą SimplePoTranslate

SimplePoTranslate natywnie obsługuje i18next JSON w planach Pro i Lifetime. Darmowy plan obejmuje obecnie .po i .pot – uaktualnij lub skorzystaj z wersji próbnej, aby uzyskać dostęp do JSON.

1. Przygotuj Plik Źródłowy

Użyj swojego angielskiego (lub źródłowego pliku lokalizacji) jako mastera. Upewnij się, że jest to prawidłowy JSON i zawiera wszystkie klucze używane przez Twoją aplikację. Częstym błędem jest pozostawianie przestarzałych lub nieużywanych kluczy, co marnuje Twój limit tłumaczeń na ciągi znaków, których nigdy nie wyświetlisz.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. Prześlij do SimplePoTranslate

Zaloguj się do swojego panelu, kliknij Nowe Tłumaczenie i prześlij common.json. Platforma automatycznie wykrywa format i18next. Wybierz język docelowy spośród 41 obsługiwanych lokalizacji, wybierz ton (profesjonalny, swobodny, marketingowy) i prześlij.

3. Pozwól Silnikowi Działać

Pod spodem plik jest analizowany, dzielony na bezpieczne partie i tłumaczony równolegle. Tokeny interpolacji są zablokowane. Sufiksy liczby mnogiej są zachowane i mapowane do reguł CLDR docelowej lokalizacji. HTML wewnątrz komponentów Trans pozostaje nienaruszony.

4. Pobierz Plik ZIP

Otrzymasz plik ZIP zawierający przetłumaczony JSON oraz alternatywne formaty (.php dla aplikacji PHP, .po dla kompatybilności między narzędziami). Wrzuć JSON do public/locales/es/common.json i wdróż ponownie.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Powtórz lub Wykonaj Wsadowo

Dla wszystkich 12 docelowych lokalizacji prześlij 12 zadań. Limity planu Pro pokrywają dziesiątki typowych aplikacji SaaS. Dla monorepo z wieloma plikami przestrzeni nazw, prześlij każdy osobno lub przetwarzaj je wsadowo sekwencyjnie.

Integrowanie Tłumaczeń z Powrotem do Twojej Aplikacji

Gdy masz już przetłumaczone pliki JSON, integracja jest łatwą częścią. Kilka pułapek:

• Zweryfikuj kategorie liczby mnogiej. Uruchom szybki test dymny dla każdej lokalizacji: wyrenderuj komponent z count={0}, count={1}, count={5} i potwierdź, że wszystkie trzy generują prawidłowy ciąg znaków.
• Sprawdź lokalizacje RTL. Jeśli tłumaczyłeś na arabski, hebrajski lub perski, Twój interfejs użytkownika potrzebuje CSS z obsługą RTL. Nasz przewodnik po tłumaczeniu RTL dla WordPress omawia wzorce CSS, które mają zastosowanie również do aplikacji React.
• Skonfiguruj łańcuch zastępczy. Skonfiguruj i18next, aby wracał do angielskiego, jeśli brakuje klucza, tak aby stany w trakcie wdrożenia nie powodowały awarii u użytkowników.
• Zablokuj plik źródłowy w CI. Dodaj kontrolę, która odrzuca PR-y, w których en/common.json zmienia się bez ponownego generowania innych lokalizacji. Dryf tłumaczeniowy jest największą przyczyną błędów i18n w produkcji.

Dla zespołów wdrażających rozwiązania w React, Next.js i po stronie serwera, produkcja każdego formatu z jednego źródła to ogromna korzyść. Nasz post o jednym pliku wejściowym, pięciu formatach wyjściowych wyjaśnia, dlaczego wyjście w wielu formatach jest ważne dla długoterminowej konserwacji.

Kiedy JSON To Za Mało: Obsługa Złożonych Przypadków

Kilka skrajnych przypadków wymaga dodatkowej uwagi.

ICU MessageFormat

Jeśli Twój projekt używa składni ICU ({count, plural, one {1 item} other {# items}}), i18next traktuje to jako interpolację, ale struktura jest bardziej złożona. Upewnij się, że Twoje narzędzie do tłumaczenia rozpoznaje parametry ICU i nie tłumaczy nazw kategorii, takich jak one, other, ani identyfikatorów formatów, takich jak plural, number, date.

Komponent Trans z Węzłami React

<Trans> renderuje komponenty React wewnątrz przetłumaczonych ciągów znaków, indeksowane (<0>, <1>). Tłumacz musi zachować dokładną kolejność tagów. Blokada składni SimplePoTranslate radzi sobie z tym, ale jeśli używasz innego narzędzia, zweryfikuj to przed wdrożeniem.

Pliki Przestrzeni Nazw

Duże aplikacje dzielą lokalizacje na przestrzenie nazw: common.json, dashboard.json, checkout.json. Tłumacz każdy plik niezależnie – nie łącz ich. Jakość kontekstu jest wyższa, gdy ścieżki kluczy każdej przestrzeni nazw pozostają w zasięgu.

Podsumowanie

Tłumaczenie i18next JSON dla aplikacji React lub Next.js nie polega na wyborze najlepszego modelu AI. Chodzi o poszanowanie reguł strukturalnych formatu: interpolacje, sufiksy liczby mnogiej, zagnieżdżone klucze i tagi HTML muszą przetrwać proces tłumaczenia. Narzędzia AI dla konsumentów traktują JSON jako niestrukturyzowany tekst. Narzędzia świadome składni analizują go jako dane strukturalne i dotykają tylko powierzchni przeznaczonych do tłumaczenia.

Jeśli wdrażasz wielojęzyczną aplikację i kopiowałeś/wklejałeś JSON do interfejsów czatu, już znasz koszty: godziny ręcznego przeglądu dla każdej lokalizacji, losowe błędy produkcyjne i rosnący stos uszkodzonych form liczby mnogiej. Potok świadomy formatu eliminuje każdy z tych trybów błędów.

Gotowy bezpiecznie tłumaczyć swoje pliki i18next JSON? Wypróbuj SimplePoTranslate za darmo – karta kredytowa nie jest wymagana. Prześlij raz, wdróż w 41 językach.