JSON translations

Vaak wordt de dynamische content van een website via JSON ingeladen, als dit wordt gedaan binnen hetzelfde domein dan biedt Clonable een oplossing voor het vertalen van deze content.

De Json translations zijn te vinden bij clone --> translations settings --> Json translations. Mocht je hier geen Json translations vinden maar Json exclusions dan kun je dit artikel overslaan.

Standaard JSON translations

Er bestaan JSON keys die we eigenlijk altijd kunnen toevoegen, deze keys hebben bijna altijd een positieve werking op de website. Een lijst van deze keys is: html, text, content, title, translation, body, deze standaard keys staan altijd aangegeven met de list name: "default entry".

Platform specifieke standaarden staan altijd aangegeven met de list name: "required for {platform}".

JSON vertalen

Technische kennis

De volgende koppen duiken dieper in de werking van websites, we gaan er vanuit dat je minimale kennis van de werking van websites hebt.

Hier staat beschreven hoe je JSON kan herkennen en vertalen.

Hoe herken je JSON?

JSON kan in 2 vormen voorkomen op de website:

1. Statisch in de source code
2. Dynamisch via API communicatie
   • Voorbeelden hiervan zijn GRAPHQL of REST API's.

Statische content

Iedere browser werkt net iets anders

De toetsencombinaties en termen die worden gebruik in de onderstaande uitleg kunnen variëren op basis van je systeem, browser en taal maar zijn over het algemeen redelijk gelijk in de meeste browsers.

Statische content kun je simpelweg vinden door op een pagina de toetscombinatie ctrl + u (view source code) te gebruiken. Dit opent de pagina op de manier hoe Clonable hem ook zou openen. Wanneer de JSON content in een script tag staat met het type application/json, dan kun je deze content vertalen met Clonable. Dat ziet er bijvoorbeeld zo uit:

<script type="application/json">
{ 'title': 'This is a test page', 'color': 'blue', 'include_in_page': false }
</script>

Dynamische content

Dynamische content is vaak iets lastiger te vinden, maar de beste aanpak hiervoor is door de netwerk tabblad van je browser te gebruiken. Dit kun je doen door op de F12 te drukken, of rechtermuisknop de klikken en de inspect optie te selecteren. Dit zal een venster openen waarin je aan de bovenkant verschillende tabbladen hebt, hier moet je het 'Network' tabblad selecteren.

In dit scherm zie je als het goed is een lijst aan netwerk verzoeken staan, om alles nog een keer op te halen kun je de pagina een keer verversen. Deze netwerk verzoeken hebben een kolom met de naam 'Type', voor JSON vertalingen zijn we op zoek naar netwerk verzoeken met het type 'json'. Als je op een netwerk verzoek klikt zal er nog een scherm openen waarin je het tabblad 'Response' moet selecteren, hierin staat als het goed is de JSON informatie.

Let op!

Dynamische JSON moet vanaf het domein van de clone komen, mocht er een ander domein of subdomain zijn gebruikt dan is deze JSON data niet te vertalen.

Hoe vertaal ik JSON?

Wanneer je succesvol de JSON hebt gevonden, kun je aan de slag met het vertalen. Clonable vereist dat je de keys van de JSON doorgeeft die vertaald moet worden. JSON werk met zogeheten key-value pairs. Voorbeeld: 'title': 'Test pagina', bij dit voorbeeld is de key 'title'. Binnen Clonable zou je dus title toevoegen aan de JSON translations.

Dynamische keys

In sommige gevallen moet je dynamische of nested keys vertalen, hiervoor raden we aan om wildcards te gebruiken. Wanneer keys dynamisch zijn, maar toch vertaalbare content bevatten, moet je een wildcard gebruiken. Neem volgend voorbeeld:

{
    'page': {
        'content': {
            'value': 'Clonable json translations',
            'paragraph': {
                'value': 'You can use Clonable to translate your JSON.'
            }
        }
    }
}

Hierbij zou je een wildcard JSON vertaling kunnen gebruiken, die zou er dan als volgt uitzien: page.*.value, hierbij geven we aan dat we een wildcard met met exact één niveau hebben. Hier zou dan alleen de tekst: 'Clonable json translations' vertaald worden door Clonable.

Wanneer je meerdere niveaus in een keer wil vertalen, kun je een dubbele wildcard gebruiken. Bij de input: page.**.value, zou alle content met de key 'value' vertaald worden.

Absolute keys

Soms wil je een key maar op één plek vertalen, hierbij kun je absolute paden gebruiken. Neem het volgende voorbeeld:

{
    'pages': {
        'home': {
            'model': 'New model now available',
        },
        'pricing: {
            'model' : 'pricing_model_1',
        }
    }
}

Hier zie je dat bij pricing het model misschien niet vertaald moet worden, omdat het op een configuratie waarde lijkt, maar de model van de home key lijkt wel prima vertaalbaar. Hiervoor zou me de volgende waarde toevoegen: pages.home.model. Dit zorgt ervoor dat alleen de tekst 'New model now available' vertaald wordt.

Gevaarlijke keys

Het is ook mogelijk om functionaliteit van je site te breken wanneer je JSON vertalingen toevoegt, dit gebeurd bijvoorbeeld als je een waarde in JSON configuratie vertaald naar een waarde die een server niet verwacht, dit kan bijvoorbeeld 422, of 500 netwerk errors opleveren.

Keys waarvan we aanraden om ze niet toe te voegen zijn: value, id, model, class. Deze keys heb je sommige gevallen wel nodig, hiervoor raden we aan op absolute JSON paden te gebruiken.

Platformspecifiek

Sommige platformen bieden JSON niet aan via een bepaalde API, maar embedden de JSON in de source code van de website. Voor sommige van deze platformen biedt Clonable een standaard oplossing.

Magento

Magento 2 plaats af en toe ook JSON configuratie in de source code van de pagina, dit wordt gedaan met script tags met een specifiek type. Dat ziet er als volgt uit:

<script type="text/x-magento-init">
    { 'my_config': { 'attribute_1': 'Purple', 'title': 'Configuratie' } }
</script>

De keys die je in dit soort configuratie scripts vindt kun je ook toevoegen aan JSON translations.

Next.js

Werkt niet altijd

JSON vertalingen werken niet altijd als oplossing bij Next.js websites, onderdelen zoals server-side React components kunnen hier niet mee vertaald worden.

Next.js werkt in veel gevallen ook met JSON, zo zie je vaak dat bepaalde vertalingen terugspringen na het vertalen van de pagina. Clonable heeft hier specifiek een oplossing voor bedacht.

Wanneer er niet vertaalde tekst in de source-code van de pagina staat, is er een kans dat deze tekst van het type NEXT_DATA is. Die ziet er als volgt uit:

<script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps": "page" ... }}</script>

Hierin kun je bijvoorbeeld zoeken naar menu items die niet vertaald zijn, en daarvan de key toevoegen aan de JSON translations van de clone.