Skip to content

Translations & i18n ​

The Ongehoord website is bilingual: Dutch (nl) is the primary language, and English (en) is the secondary language. This page explains how the translation system works and how to manage content in both languages.

How It Works ​

There are two types of translatable text on the website:

  1. Content — Markdown files in content/nl/ and content/en/ (investigations, pages, locations)
  2. UI strings — Interface text like button labels and navigation items in i18n/locales/nl.json and en.json

Content Translation ​

The Mirror Rule ​

The Dutch and English content folders must mirror each other exactly:

content/
├── nl/
│   └── onderzoek/
│       └── 2.het-leven-van-een-varken/
│           ├── index.md                    ← Dutch text
│           ├── hoofdstukken/
│           │   └── 1.natuurlijk-leven.md   ← Dutch text
│           └── locaties/
│               └── aalten-gendringseweg-37.md
│
└── en/
    └── onderzoek/
        └── 2.het-leven-van-een-varken/     ← SAME folder name
            ├── index.md                    ← English text
            ├── hoofdstukken/
            │   └── 1.natuurlijk-leven.md   ← SAME file name, English text
            └── locaties/
                └── aalten-gendringseweg-37.md

What must be identical across languages ​

ElementMust match?Example
Folder namesYes2.het-leven-van-een-varken/
File namesYes1.natuurlijk-leven.md
Frontmatter keysYesanimals, video, date
animals valuesYes[pig, cow]
video URLYesSame Vimeo/YouTube URL
image.srcYesSame image path
dateYesSame publication date
publishedYesBoth true or both false

What differs between languages ​

ElementNL exampleEN example
titleHet leven van een varkenThe life of a pig
descriptionHet onderzoeksteam bezocht...The research team visited...
image.altHet leven van een varkenThe life of a pig
Body textDutch Markdown contentEnglish Markdown content

Translation example ​

Dutch (content/nl/onderzoek/2.het-leven-van-een-varken/index.md):

yaml
---
title: Het leven van een varken
description: >-
  Het onderzoeksteam van Ongehoord bezocht maarliefst
  26 varkensfokkers.
animals:
  - pig
video: https://vimeo.com/522281301
image:
  src: /images/investigations/het-leven-van-een-varken/hero.jpg
  alt: Het leven van een varken
date: 2011-06-19
published: true
---

In juni 2011 publiceerde Ongehoord haar onderzoek naar de
Nederlandse varkenshouderij.

English (content/en/onderzoek/2.het-leven-van-een-varken/index.md):

yaml
---
title: The life of a pig
description: >-
  The Ongehoord research team visited no fewer than
  26 pig farms.
animals:
  - pig
video: https://vimeo.com/522281301
image:
  src: /images/investigations/het-leven-van-een-varken/hero.jpg
  alt: The life of a pig
date: 2011-06-19
published: true
---

In June 2011, Ongehoord published its investigation into
Dutch pig farming.

Notice how animals, video, image.src, date, and published are identical. Only title, description, image.alt, and the body text are translated.

Automated Translation ​

The project includes an AI-powered translation script that translates Dutch content to English automatically:

bash
# Preview what would be translated (no changes made)
pnpm translate:en:dry

# Translate all untranslated Dutch content to English
pnpm translate:en

The script:

  • Finds Dutch content files that don't have an English counterpart (or have been updated)
  • Translates the text using Google Translate API
  • Creates/updates the English files with the correct structure
  • Preserves all Markdown formatting, links, and components

Recommended workflow for new content

  1. Write the content in Dutch first
  2. Run pnpm translate:en to auto-translate
  3. Review the English translation and fix any awkward phrasing
  4. Run pnpm fix:grammar:en to clean up translation artifacts

See Automation Scripts for full details on the translation and other content scripts.

UI String Translation ​

Interface text (buttons, labels, navigation) is managed through JSON translation files:

i18n/locales/
├── nl.json    # Dutch UI strings
└── en.json    # English UI strings

Structure ​

The files use nested keys:

json
{
  "common": {
    "donate": "Doneren",
    "contact": "Contact",
    "read_more": "Lees meer",
    "share": "Delen"
  },
  "contact": {
    "form": {
      "submit": "Verzenden",
      "email_label": "Email",
      "message_label": "Bericht"
    }
  }
}

Adding a new UI string ​

If you need to add a new translatable string:

  1. Add the key and Dutch text to i18n/locales/nl.json
  2. Add the same key with English text to i18n/locales/en.json
  3. Use it in a component with $t('key.path'):
vue
<template>
  <button>{{ $t('common.donate') }}</button>
</template>

WARNING

Both nl.json and en.json must have the same keys. If you add a key to one file, add it to the other as well. Missing keys will show the key path instead of the translated text.

Translation Checklist ​

When translating a new investigation:

  • [ ] index.md — title, description, alt text, and body translated
  • [ ] All chapters in hoofdstukken/ — title, description, alt text, and body translated
  • [ ] All locations in locaties/ — title and body text translated
  • [ ] Annotation sources in bronnen/ — copied as-is (scientific references stay in original language)
  • [ ] Folder names and file names are identical to the Dutch version
  • [ ] Structural frontmatter (animals, video, image.src, date, published) is identical

Common Mistakes ​

Different folder names ​

# WRONG — different folder names
content/nl/onderzoek/2.het-leven-van-een-varken/
content/en/onderzoek/2.the-life-of-a-pig/         ← WRONG!

# CORRECT — same folder names
content/nl/onderzoek/2.het-leven-van-een-varken/
content/en/onderzoek/2.het-leven-van-een-varken/   ← Correct!

Missing English files ​

If a Dutch file exists but the English version is missing, the website will fall back to showing the Dutch content for English visitors. This is a safe fallback, but for the best experience, always create both versions.

Translating technical values ​

Don't translate technical values like animal keys, URLs, or paths:

yaml
# WRONG
animals:
  - varken     ← Don't translate this!

# CORRECT
animals:
  - pig        ← Use the English key in BOTH languages