← Leren

Probleemoplossing

Elk item hier is een foutscenario waar iemand daadwerkelijk tegenaan is gelopen. Bij elk item staan het symptoom, de oorzaak en de oplossing. De meeste gevallen komen neer op een van drie dingen: de zin zit niet in het project, de SDK is nooit geïnitialiseerd, of een placeholder is voor de verkeerde context geschreven.

Er wordt niets vertaald — elke zin blijft in de brontaal

Als alles brontekst toont, is de SDK vrijwel zeker niet geïnitialiseerd. Hij faalt bewust zachtjes (je UI mag nooit breken), dus het enige duidelijke signaal is de browserconsole — kijk daar eerst. De gebruikelijke oorzaken, in volgorde van waarschijnlijkheid:

1. CORS. Het eerste verzoek van de SDK is authorize-project; als je API de origin van de app niet op de allowlist zet, blokkeert de browser het verzoek en stopt de initialisatie meteen. Bedenk dat een origin precies uit schema + host + poort bestaat — localhost:5173 en localhost:5174 zijn verschillende origins, en ontwikkelservers schuiven op naar een andere poort als de gebruikelijke bezet is. Zet daarom elke poort waarop je daadwerkelijk ontwikkelt op de allowlist.
2. Onjuiste inloggegevens. Een ontbrekende of verkeerd getypte project-id / API-sleutel laat dezelfde autorisatieaanroep mislukken. De console toont het mislukte verzoek en de URL.
3. Je bekijkt de basistaal. In de basistaal is de "vertaling" de brontekst — er verandert niets zichtbaars. Schakel over naar een doeltaal om te testen.

# The SDK's first call is an authorize-project request.
# If the browser blocks it, NOTHING translates. Check the console for:
Access to fetch at 'https://your-api/api/authorize-project/...'
from origin 'http://localhost:5173' has been blocked by CORS policy

# Fix: allowlist the app's EXACT origin (scheme + host + port) on the API.
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.example.com

Eén zin wordt niet vertaald (maar andere wel)

De phrase in je code is de opzoeksleutel — de phrase is de sleutel. Als één enkele phrase als brontekst wordt weergegeven terwijl de phrases eromheen wel vertaald worden, staat die sleutel niet in de catalogus van het project:

• De phrase is nooit geregistreerd. Registratie verloopt via token discovery, en alleen een schrijfsleutel kan dat doen. Als de phrase is ontstaan terwijl de app draaide met een alleen-lezensleutel, is hij nergens naartoe verstuurd — doorloop het scherm één keer in development met een schrijfsleutel, of voeg de phrase toe in het dashboard.
• De tekst is gewijzigd. Elke wijziging — een woord, leesteken of zelfs een spatie — maakt er een nieuwe zin van zonder vertalingen. De oude vertalingen bestaan nog wel onder de oude sleutel. Dit speelt vooral bij contentblokken: een <Translate>-blok wordt getokeniseerd op basis van de markup, dus als je de tekst of structuur van het blok wijzigt, verandert wat er wordt opgezocht, en het blok valt stilletjes terug op de brontekst totdat de nieuwe vorm is geregistreerd en vertaald.
• De machinevertaling is er nog niet. Een zojuist geregistreerde zin kan even op zijn vertalingen moeten wachten, en voor een locale die niet op de doellijst van het project staat komt er nooit een vertaling. Controleer de zin in het dashboard: geregistreerd? vertaald naar deze locale?

Waarom geven ontbrekende phrases geen foutmelding?

Dit is bewust zo. In productie moet een vertaalsysteem terugvallen op leesbare brontekst, nooit op een kapotte pagina — dus een niet-geregistreerde zin toont zijn brontekst en de SDK blijft stil. Keerzijde: met een alleen-lezen sleutel is een ontbrekende zin stil. Er wordt niets gelogd, niets geregistreerd, en je hoort het pas wanneer een gebruiker Engels ziet. Wat dit voorkomt is de sleutelsplitsing — ontwikkel met een schrijfsleutel zodat elke zin die je UI toont wordt ontdekt, en lever daarna alleen-lezen uit.

# Development — write key: new phrases are discovered,
# registered, and machine-translated as you build.
VITE_LANGSYS_API_KEY=write-key

# Production — read-only key: fetches the finished catalog only.
# Unregistered phrases silently render their source text.
VITE_LANGSYS_API_KEY=read-only-key

Mijn placeholder wordt letterlijk weergegeven — "Hi %name%" of "Hi {name}"

• In t()-aanroepen zijn plaatsaanduidingen enkele accolades {name}, en interpolatie werkt alleen als je de parameters meegeeft: t('Hello, {name}!', 'Greetings', { name }).
• Schrijf in <Translate>/<Phrase>-markup onder React, Vue of Svelte de placeholders als %name%. De compiler van het framework verwerkt een kale {name} als expressie nog voordat de SDK hem ziet; %name% overleeft de compilatie en de SDK zet het bij het vastleggen weer om naar {name}. Gewone {name} is prima in pure HTML, waar geen templatesyntaxis is om mee te botsen.
• Ontbreken er params? Als er geen params worden meegegeven, wordt de template ongewijzigd weergegeven — dat is de letterlijke %name% die je ziet.

Het werkt, maar gaat stuk nadat ik meerdere keren heen en weer wissel tussen locales

Werk de SDK bij. Echte, opgeloste bugs op dit gebied: terugkeren naar de initiële/SSR-locale liet de vorige catalogus actief (opgelost in langsys-js-typescript 0.2.2), en consumers van contentblok-Translate/Phrase konden eindeloos blijven hangen bij een server-geseede catalogus (opgelost in 0.2.3). Zie je strings in een verouderde locale of blokken die nooit worden opgelost, vergelijk dan je geïnstalleerde versie met de changelog van de basis-SDK voordat je je eigen code gaat debuggen.

Server-side: de pagina geeft een 500-fout in plaats van soepel terug te vallen

De client van de PHP-SDK geeft een foutmelding als hij zonder inloggegevens wordt aangemaakt — dus een Laravel-app (of gewone PHP-app) met een lege LANGSYS_API_KEY faalt bij het oplossen van de container, voordat er een vertaling wordt uitgevoerd. Stel de inloggegevens in (of bind, voor een app die zonder inloggegevens moet kunnen opstarten, een vervangende client, zoals de demo-apps doen). Zodra er inloggegevens zijn, vallen API-fouten tijdens runtime wel netjes terug: een onbereikbare of weigerende API toont de brontekst en meldt de uitzondering — de pagina valt nooit uit.

Server-side: het eerste verzoek blijft hangen, daarna gaat alles snel

De HTTP-timeout van de PHP SDK is 30 seconden, en een API-instantie die uit de slaapstand komt, kan daar bij de allereerste aanroep tegenaan zitten. Dat verzoek wordt dan ofwel traag voltooid (en vult de cataloguscache — alles daarna komt uit de cache) ofwel loopt het op een timeout af en wordt de brontekst weergegeven. Is je eerste paginalading na een rustige periode traag, dan is dit de reden; de API warmt op, het ligt niet aan je integratie.

Server-side: ik heb gerenderd met een write key, maar de zin staat niet in het dashboard

Ontdekte frasen worden tijdens het verzoek in de wachtrij gezet en verstuurd nadat het antwoord is verzonden — de terminable middleware van Laravel. Ververs het dashboard even nadat de pagina is geladen, niet tijdens het laden. Zorg er bij langlopende worker-runtimes (Octane, FrankenPHP, RoadRunner) voor dat je de meegeleverde integratie van de SDK gebruikt — de gewone PHP-shutdownhook wordt tussen worker-verzoeken nooit geactiveerd.

Server-side rendering: vertalingen van het ene verzoek lekken door naar een ander

De JS-basis-SDK bevat steeds de catalogus van één locale: het is een singleton op moduleniveau. Een Node-server die voor gelijktijdige verzoeken verschillende locales rendert, krijgt race conditions. Haal de catalogus per verzoek op en vul de client daarmee, zoals in de gidsen voor Next.js, Nuxt en SvelteKit, of draai één locale per proces.