Flat czy nested: jaka struktura kluczy JSON jest lepsza?

Flat (np. 'homepage.hero.title') jest prostszy w wyszukiwaniu i nie powoduje problemów z głębokim zagnieżdżaniem. Nested (obiekt w obiekcie) jest bardziej czytelny wizualnie i naturalny dla dużych projektów. Wybór zależy od frameworka i wielkości projektu. React-i18next wspiera oba.

Jak działa pluralizacja w plikach JSON i18n?

Pluralizacja wymaga zdefiniowania wariantów formy liczebnika per język. Angielski ma 2 formy (one/other), polski ma 3 (one/few/many), arabski ma 6. Klucze w JSON wyglądają np. 'items_one', 'items_few', 'items_many'. Biblioteka i18n dobiera formę na podstawie liczby.

Czym jest interpolacja w kontekście i18n?

Interpolacja to wstawianie dynamicznych wartości do przetłumaczonych tekstów, np. 'Witaj, {{name}}!' gdzie {{name}} jest zastępowane imieniem użytkownika. Ważne, by tłumacz nie modyfikował placeholderów. Dobre narzędzia TMS walidują to automatycznie.

Jak walidować pliki JSON tłumaczeń?

Stosujemy walidację na kilku poziomach: poprawność składni JSON (linting), kompletność kluczy (porównanie z plikiem źródłowym), walidację placeholderów interpolacji, sprawdzenie form pluralizacji per język i test integracyjny (czy aplikacja wyświetla wszystkie stringi).

Ile plików JSON potrzebuję do wielojęzycznej aplikacji?

Minimum jeden plik per język (np. pl.json, en.json, de.json). W większych projektach stosuje się namespaces: osobne pliki per moduł (common.json, checkout.json, dashboard.json) w katalogu per język. Pozwala to na lazy loading tłumaczeń i lepszą organizację pracy tłumaczy.

Wdrożenia

Wdrożenie JSON i18n

JSON to najpopularniejszy format plików tłumaczeniowych w nowoczesnych aplikacjach webowych. Pomagamy zaprojektować strukturę kluczy, wdrożyć pluralizację i zintegrować z frameworkiem.

Flat czy nested? Jak obsłużyć polską pluralizację? Jak zorganizować namespaces? Odpowiadamy na te pytania i implementujemy rozwiązanie w Twoim projekcie.

Co wdrażamy:

Struktura kluczy (flat / nested)
Pluralizacja (ICU / custom rules)
Interpolacja zmiennych ({{name}})
Namespaces i lazy loading
Walidacja i QA plików

Struktura kluczy: flat vs nested

Wybór struktury wpływa na czytelność, zarządzanie i performance. Oto porównanie.

Flat (klucze z kropką)

{
  "homepage.hero.title": "Witaj",
  "homepage.hero.subtitle": "Opis",
  "checkout.button.pay": "Zapłać",
  "checkout.button.cancel": "Anuluj"
}

Zalety:

+ Łatwe wyszukiwanie (Ctrl+F)

+ Brak problemów z głębokim zagnieżdżaniem

+ Proste do eksportu CSV

Wady:

- Mniej czytelne wizualnie

- Długie klucze przy dużych projektach

Nested (zagnieżdżone obiekty)

{
  "homepage": {
    "hero": {
      "title": "Witaj",
      "subtitle": "Opis"
    }
  },
  "checkout": {
    "button": {
      "pay": "Zapłać",
      "cancel": "Anuluj"
    }
  }
}

Zalety:

+ Czytelna hierarchia

+ Naturalne namespaces

+ Łatwiejsze code review

Wady:

- Głębokie zagnieżdżanie trudne w zarządzaniu

- Konflikty merge w Git

Pluralizacja per język

Każdy język ma inne reguły odmiany form liczebnikowych. JSON i18n musi to uwzględniać.

Język	Formy	Przykład
Angielski	one, other	"1 item" / "5 items"
Polski	one, few, many, other	"1 produkt" / "2 produkty" / "5 produktów"
Arabski	zero, one, two, few, many, other	6 form liczebnikowych
Japoński	other (tylko jedna forma)	Brak odmiany
Rosyjski	one, few, many, other	Jak polski, ale inne reguły

Przykład w JSON (polski): "items_one": "{{count}} produkt", "items_few": "{{count}} produkty", "items_many": "{{count}} produktów"

Obsługiwane frameworki

react-i18next

Najpopularniejsza biblioteka i18n w React. Pełne wsparcie flat i nested JSON, namespaces, lazy loading, pluralizacja ICU.

JSON flat lub nested

Vue i18n

Natywna biblioteka i18n dla Vue.js. Wsparcie SFC (Single File Components), linked messages, pluralizacja per locale.

JSON nested (domyślnie)

Angular i18n / ngx-translate

Wbudowany system Angular i18n (XLIFF) lub ngx-translate (JSON). AOT compilation, ICU expressions, lazy loading per moduł.

JSON flat (ngx-translate) / XLIFF (built-in)

Next.js (next-intl)

Dedykowane i18n dla Next.js App Router. JSON per locale, type-safe keys, RSC support, middleware routing.

JSON nested per namespace

Checklist walidacji JSON

Poprawność składni JSON (brak trailing commas, brakujących cudzysłowów)

Kompletność kluczy (porównanie z plikiem źródłowym)

Walidacja placeholderów interpolacji ({{name}}, {count})

Sprawdzenie form pluralizacji per język

Testowanie długości tekstu (overflow w UI)

Weryfikacja encodingu (UTF-8, emoji, znaki specjalne)

Sprawdzenie brakujących wartości (puste stringi)

Walidacja namespaces (brak osieroconych kluczy)

Najczęstsze błędy w JSON i18n

Brak pluralizacji

Używanie jednej formy dla wszystkich liczb. W polskim 'produkty' ma 3 formy, nie 2. Brak proper pluralization to natychmiastowy sygnał kiepskiej lokalizacji.

Hardcoded spaceholders

Łączenie "Masz " + count + " wiadomości" zamiast jednego klucza z interpolacją. Każdy język ma inny szyk zdania.

Niespójne nazewnictwo kluczy

Mieszanie konwencji: "homePage.Title" vs "home_page.title" vs "HOMEPAGE_TITLE". Ustal jedną konwencję i trzymaj się jej.

Zbyt duży plik na jednym loadingu

Ładowanie 500KB JSON z wszystkimi tłumaczeniami na start. Dziel na namespaces i ładuj per strona.

Brak kontekstu w kluczach

Klucz "delete" bez kontekstu: czy to "Usuń" (plik), "Skasuj" (konto) czy "Wymaż" (dane)? Dodawaj kontekst w nazwie klucza.

Wdrożymy JSON i18n w Twoim projekcie

Zaprojektujemy strukturę kluczy, wdrożymy pluralizację i zintegrujemy z Twoim frameworkiem. Wyślij link do repo lub opis projektu.