Hoe i18next JSON-bestanden te vertalen in React & Next.js (2026)

Je hebt net een React-app afgerond die volgende week vrijdag in 12 talen moet worden uitgebracht. Je locale-bestanden bevinden zich in public/locales/en/common.json, je hebt 340 sleutels per locale, en de tokens in je strings zien eruit als {{userName}} en {{count}} verspreid over geneste objecten. Je plakt de JSON in ChatGPT, en het komt terug met {{ nombreUsuario }}, extra spaties en de helft van de pluralisatie-sleutels hernoemd. Je app crasht tijdens het bouwen.

Als je hebt geprobeerd om i18next JSON-vertaling te automatiseren, ken je deze pijn. Het JSON-formaat is flexibel, en dat is precies waarom de meeste vertaaltools het verminken. Het echte probleem is niet de kwaliteit van het taalmodel - het is dat AI-tools voor consumenten de structurele regels van i18next niet begrijpen.

Deze gids legt uit wat i18next JSON anders maakt dan andere locale-formaten, waarom naïeve vertaalmethoden React- en Next.js-apps breken, en hoe je vertalingen veilig kunt automatiseren over tientallen locales zonder elke sleutel handmatig te controleren.

Wat is i18next JSON en waarom vertalen lastig is

i18next is de meest gebruikte i18n-bibliotheek in het JavaScript-ecosysteem. Het drijft React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue en Node backend-services aan. Het slaat vertaalbare strings op in platte of geneste JSON-bestanden, één per locale.

Een typisch bestand ziet er zo uit:

{
  "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>."
  }
}

Dit lijkt eenvoudig, maar drie dingen maken het gevaarlijk om te vertalen met algemene AI.

Interpolatie-tokens zijn structureel, geen tekst

De reeks {{userName}} is geen woord - het is een placeholder die de runtime vervangt door gegevens. Voeg een spatie toe ({{ userName }}), hernoem het, of vertaal de interne identifier en de runtime faalt stilzwijgend of gooit een fout. Sommige vertalers zetten {{count}} handig om naar {{conteo}} in het Spaans. Je app probeert nu een variabele te interpoleren die niet bestaat en rendert de onbewerkte placeholder aan je gebruiker.

Pluralisatie-sleutels zijn magische suffixen

i18next detecteert meervouden aan de hand van suffixen: _zero, _one, _two, _few, _many, _other. Dit zijn geen willekeurige strings - ze moeten overeenkomen met de CLDR-meervoudscategorieën voor de doellocale. Het Engels gebruikt alleen _one en _other. Russisch, Arabisch en Pools gebruiken tot zes categorieën. Als je vertaler _other weglaat of hernoemt, wordt de fallback-keten verbroken.

Geneste sleutels moeten intact blijven

In tegenstelling tot Gettext .po-bestanden, die platte sleutel-waardeparen zijn, kunnen i18next-bestanden willekeurig diep genest zijn. Een luie vertaler kan de structuur afvlakken, sleutelnamen wijzigen zodat ze overeenkomen met de vertaalde tekst, of objecten herordenen. Je t('cart.items_other')-aanroep in de code lost dan niet langer op.

Slechte oplossingen die ontwikkelaars als eerste proberen

Elk team doorloopt dezelfde driefasen mislukte cyclus voordat ze investeren in een echte oplossing.

Fase één: Plakken in ChatGPT

Je kopieert 200 sleutels naar ChatGPT, vraagt "vertaal deze JSON naar het Spaans," en plakt het resultaat terug. Het werkt voor 180 sleutels. Twintig hebben spaties toegevoegd binnen {{...}}, drie hebben herschreven meervoudssuffixen, en één <strong>-tag werd vertaald naar <fuerte>. Je build mislukt dan wel, of stuurt stilzwijgend kapotte strings naar productie.

Fase twee: Google Translate API

Je koppelt de Google Translate REST API, itereert over je JSON, en stuurt elke waarde. Snelheid is geweldig. Kwaliteit niet. De API van Google behandelt elke string afzonderlijk - geen context over je app, geen begrip dat {{count}} een placeholder is, geen besef dat sleutel cart.empty verschilt van cart.items_one. Je hebt nog steeds menselijke controle nodig voor elke sleutel.

Fase drie: Commerciële TMS-platforms

Je meldt je aan voor een vertaalbeheersysteem. Ze rekenen per woord, vereisen GitHub-integraties en binden je vast aan maandelijkse plaatsen. Voor een zijproject of een indie-app vallen de kosten snel tegen - en je loopt nog steeds tegen dezelfde problemen met beschadigde placeholders aan als hun engine het i18next-formaat niet specifiek parseert.

Dezelfde foutmodi komen ook voor in Gettext-workflows. Onze gids over hoe .po-bestanden te vertalen zonder codevariabelen te breken behandelt het parallelle probleem voor WordPress en andere op Gettext gebaseerde stacks.

De veilige aanpak: syntaxis-bewuste vertaling

De enige betrouwbare manier om i18next JSON op schaal te vertalen, is met een tool die eerst het formaat parseert, de syntaxis vergrendelt en alleen vertaalbare tekst naar de AI stuurt.

Dit is wat syntaxis-bewuste verwerking onder de motorkap doet:

1. Parseert de JSON in een abstracte boomstructuur, waarbij sleutelpaden en nesten behouden blijven.
2. Identificeert interpolatie-tokens ({{name}}, {{count, number}}, {{date, datetime}}) en vervangt deze door placeholder-ID's.
3. Identificeert HTML-tags binnen Trans-componenten (<0>, <strong>, <br/>) en vergrendelt deze.
4. Detecteert meervoudssleutels aan de hand van suffixen en koppelt deze aan CLDR-regels voor de doellocale.
5. Stuurt alleen de opgeschoonde tekst naar de LLM met context over het sleutelpad.
6. Voegt de originele tokens en tags opnieuw in op hun exacte posities.
7. Valideert de uitvoer - als een placeholder ontbreekt of misvormd is, wordt teruggegaan naar de bron.

Dit is hetzelfde principe dat cloudgebaseerde PO-vertaling veilig maakt. Als je nieuwsgierig bent naar de onderliggende architectuur, legt onze vergelijking van AI-vertaalkwaliteit uit hoe verschillende LLM's met deze beperkingen omgaan.

Stap-voor-stap: Vertaal i18next JSON met SimplePoTranslate

SimplePoTranslate ondersteunt i18next JSON native op Pro- en Lifetime-abonnementen. De gratis laag omvat momenteel .po en .pot - upgrade of gebruik een proefversie om toegang te krijgen tot JSON.

1. Bereid je bronbestand voor

Gebruik je Engelse (of bronlocale) bestand als master. Zorg ervoor dat het geldige JSON is en alle sleutels bevat die je app gebruikt. Een veelvoorkomende fout is het achterlaten van verouderde of ongebruikte sleutels, wat je vertaalquotum verbruikt voor strings die je nooit zult renderen.

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

2. Uploaden naar SimplePoTranslate

Log in op je dashboard, klik op Nieuwe Vertaling en upload common.json. Het platform detecteert automatisch het i18next-formaat. Kies je doeltaal uit de 41 ondersteunde locales, selecteer een toon (professioneel, informeel, marketing) en dien in.

3. Laat de engine zijn werk doen

Onder de motorkap wordt het bestand geparseerd, opgedeeld in veilige batches en parallel vertaald. Interpolatie-tokens worden vergrendeld. Meervoudssuffixen blijven behouden en worden gekoppeld aan de CLDR-regels van de doellocale. HTML binnen Trans-componenten blijft intact.

4. Download de ZIP

Je ontvangt een ZIP-bestand met de vertaalde JSON plus alternatieve formaten (.php voor PHP-apps, .po voor cross-tool compatibiliteit). Plaats de JSON in public/locales/es/common.json en herimplementeer.

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

5. Herhalen of Batchgewijs verwerken

Voor alle 12 doellocales, dien 12 taken in. Pro-plan quota's dekken tientallen typische SaaS-apps. Voor monorepos met meerdere namespace-bestanden, upload elk bestand afzonderlijk of verwerk ze sequentieel in batches.

Vertalingen terug integreren in je app

Zodra je JSON-bestanden hebt vertaald, is de integratie het gemakkelijke deel. Een paar aandachtspunten:

• Controleer meervoudscategorieën. Voer een snelle rooktest uit per locale: render een component met count={0}, count={1}, count={5} en bevestig dat alle drie de juiste string produceren.
• Controleer RTL-locales. Als je naar het Arabisch, Hebreeuws of Perzisch hebt vertaald, heeft je UI RTL-bewuste CSS nodig. Onze WordPress RTL-vertaalgids behandelt de CSS-patronen die ook van toepassing zijn op React-apps.
• Stel een fallback-keten in. Configureer i18next om terug te vallen op het Engels als een sleutel ontbreekt, zodat statussen tijdens de implementatie geen crashes bij gebruikers veroorzaken.
• Vergrendel je bronbestand in CI. Voeg een controle toe die PR's afwijst waarbij en/common.json verandert zonder andere locales opnieuw te genereren. Vertaalafwijking is de grootste oorzaak van i18n-bugs in productie.

Voor teams die leveren via React, Next.js en de server-side, is het produceren van elk formaat vanuit één bron een enorme winst. Onze post over één bestand in, vijf formaten uit legt uit waarom output in meerdere formaten belangrijk is voor langdurig onderhoud.

Wanneer JSON niet genoeg is: complexe gevallen behandelen

Een paar randgevallen vereisen extra aandacht.

ICU MessageFormat

Als je project ICU-syntaxis gebruikt ({count, plural, one {1 item} other {# items}}), behandelt i18next dit als interpolatie, maar de structuur is complexer. Zorg ervoor dat je vertaaltool ICU-parameters herkent en categorienamen zoals one, other, of formaat-identifiers zoals plural, number, date niet vertaalt.

Trans-component met React Nodes

<Trans> rendert React-componenten binnen vertaalde strings, geïndexeerd (<0>, <1>). De vertaler moet de exacte tagvolgorde behouden. De syntaxisvergrendeling van SimplePoTranslate regelt dit, maar als je een andere tool gebruikt, controleer dit dan voor verzending.

Namespace-bestanden

Grote apps splitsen locales op in namespaces: common.json, dashboard.json, checkout.json. Vertaal elk bestand onafhankelijk - voeg ze niet samen. De contextkwaliteit is hoger wanneer de sleutelpaden van elke namespace gescheiden blijven.

Alles samengevat

Het vertalen van i18next JSON voor een React- of Next.js-app gaat niet over het kiezen van het beste AI-model. Het gaat over het respecteren van de structurele regels van het formaat: interpolaties, meervoudssuffixen, geneste sleutels en HTML-tags moeten de ronde reis overleven. Consumenten-AI-tools behandelen JSON als ongestructureerde tekst. Syntaxis-bewuste tools parseren het als gestructureerde data en raken alleen de vertaalbare oppervlakken aan.

Als je een meertalige app uitbrengt en JSON naar chat-interfaces hebt gekopieerd en geplakt, ken je de kosten al: uren handmatige controle per locale, willekeurige productiebugs en een groeiende stapel kapotte meervoudsvormen. Een formaat-bewuste pipeline elimineert al die foutmodi.

Klaar om je i18next JSON-bestanden veilig te vertalen? Probeer SimplePoTranslate gratis - geen creditcard nodig. Upload één keer, lever in 41 talen.