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:
- Content — Markdown files in
content/nl/andcontent/en/(investigations, pages, locations) - UI strings — Interface text like button labels and navigation items in
i18n/locales/nl.jsonanden.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.mdWhat must be identical across languages
| Element | Must match? | Example |
|---|---|---|
| Folder names | Yes | 2.het-leven-van-een-varken/ |
| File names | Yes | 1.natuurlijk-leven.md |
| Frontmatter keys | Yes | animals, video, date |
animals values | Yes | [pig, cow] |
video URL | Yes | Same Vimeo/YouTube URL |
image.src | Yes | Same image path |
date | Yes | Same publication date |
published | Yes | Both true or both false |
What differs between languages
| Element | NL example | EN example |
|---|---|---|
title | Het leven van een varken | The life of a pig |
description | Het onderzoeksteam bezocht... | The research team visited... |
image.alt | Het leven van een varken | The life of a pig |
| Body text | Dutch Markdown content | English Markdown content |
Translation example
Dutch (content/nl/onderzoek/2.het-leven-van-een-varken/index.md):
---
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):
---
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:
# Preview what would be translated (no changes made)
pnpm translate:en:dry
# Translate all untranslated Dutch content to English
pnpm translate:enThe 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
- Write the content in Dutch first
- Run
pnpm translate:ento auto-translate - Review the English translation and fix any awkward phrasing
- Run
pnpm fix:grammar:ento 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 stringsStructure
The files use nested keys:
{
"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:
- Add the key and Dutch text to
i18n/locales/nl.json - Add the same key with English text to
i18n/locales/en.json - Use it in a component with
$t('key.path'):
<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:
# WRONG
animals:
- varken ← Don't translate this!
# CORRECT
animals:
- pig ← Use the English key in BOTH languages