🌐 Riksdagsmonitor — Translation Guide

🗣️ Consistent Multilingual Political Intelligence Across 14 Languages
🇸🇪🇬🇧🇩🇰🇳🇴🇫🇮🇩🇪🇫🇷🇪🇸🇳🇱🇸🇦🇮🇱🇯🇵🇰🇷🇨🇳 · RTL Support · BCP-47 Compliance

📋 Document Owner: CEO | 📄 Version: 1.0 | 📅 Last Updated: 2026-02-10 (UTC)
🏢 Owner: Hack23 AB (Org.nr 559534-7807) | 🏷️ Classification: 🟢 Public
📂 Repository: Hack23/riksdagsmonitor

📋 Overview

This guide provides comprehensive translation standards and terminology for the Riksdagsmonitor platform across all 14 supported languages. It ensures consistency, accuracy, and cultural appropriateness in all language variants.

📰 News articles are translated out-of-band

News articles are not localised by the workflow that generates them. The per-type news workflows (news-propositions, news-motions, news-committee-reports, news-interpellations, news-evening-analysis, news-realtime-monitor, news-week-ahead, news-month-ahead, news-weekly-review, news-monthly-review) each run the two-step aggregate-then-render pipeline (scripts/aggregate-analysis.ts → analysis/daily/$DATE/$SUB/article.md → scripts/render-articles.ts + scripts/render-lib/) to emit rendered HTML files for all 14 languages per article:

• news/$DATE-$SUB-en.html (English master)
• news/$DATE-$SUB-sv.html (Swedish)
• news/$DATE-$SUB-da.html, news/$DATE-$SUB-no.html, …, news/$DATE-$SUB-zh.html (remaining 12 languages)

All 14 language renderings are produced by the per-type workflows themselves via the localized executive-brief cascade inside the renderer. Per-type workflows write only the canonical English article.md (aggregated from all 23 analysis artifacts). The renderer then composes the English article.md body with executive-brief_<lang>.md (when present) via the cascade chain in scripts/render-lib/article-merge.ts (mergeLocalizedWithEnglish) + scripts/render-lib/aggregator/seo/localized-brief.ts to produce each non-English HTML file. The English body remains in English prose — only the executive-brief hero section + SEO metadata is localized.

Per-type workflows do NOT write article.<lang>.md — these files are now forbidden by scripts/validate-file-ownership.ts (category-independent reject). The ownership validator is invoked with --files-from and inspects only the paths it receives; an untouched historical article.<lang>.md already on disk is not flagged simply because a PR modifies another file in the same folder. The validator rejects an article.<lang>.md path only when that specific file is part of the changed-file input (i.e. a PR creates, modifies, deletes, or otherwise lists it).

The standalone news-translate workflow does not touch news/*.html at all; its sole mission is executive-brief Markdown translation — see §"Executive Brief Markdown Translations" below.

In parallel with the rendered HTML, each per-type workflow also writes a Markdown executive brief (the 60-second BLUF artifact, ≈ 400–600 words) at analysis/daily/$DATE/$SUB/executive-brief.md (English only). Localised siblings executive-brief_<lang>.md for all 13 non-English target languages are produced exclusively by news-translate, which runs three times daily (09:00 / 14:00 / 19:00 UTC) and:

1. Scans analysis/daily/**/executive-brief.md for sources that are missing translations or whose <!-- source-sha: ... --> trailer no longer matches the current git log -1 --format=%H of the source.
2. Picks up at most max_briefs source files per run (default 3, range 1–7), prioritising the oldest article date first.
3. Translates each source into every requested target language using the terminology tables in this guide.
4. Validates every translation with scripts/validate-executive-brief-translations.ts (structural parity, dok_id preservation, RTL markers, no English BLUF leakage, source-SHA trailer).
5. Commits the batch and opens one PR per run.

No other workflow — and no other contributor process — writes localised executive briefs or localised article HTML. This decoupling means:

• Editorial changes to a source executive brief ripple through all 14 languages in the next news-translate run.
• Terminology drift is detectable: a single news-translate regression only affects non-EN files.
• The 14 top-level index_*.html pages and political-intelligence_*.html pages remain hand-translated (that workflow is not in scope here).

When translating HTML that has already been rendered, do not modify <pre class="mermaid"> blocks — the Mermaid diagram source is a syntactic DSL that must survive untouched. Translate the adjacent <figcaption> and <details> fallback blocks instead. The same rule applies to fenced ```mermaid blocks in executive-brief Markdown.

Supported Languages (14)

📝 Executive Brief Markdown Translations

Scope. Authoritative rules for translating analysis/daily/$ARTICLE_DATE/$SUBFOLDER/executive-brief.md (the 60-second BLUF artifact produced by every per-type news workflow) into the 13 non-English target languages. The news-translate workflow is the sole writer of these translations; no other workflow or contributor process may emit executive-brief_<lang>.md.

File naming contract

Together with the English source these 14 files cover the full 14-language set. No executive-brief_en.md file is ever created — executive-brief.md IS the English version. This is the only deviation from the index_<lang>.html naming pattern in the rest of the platform.

Source-revision signal (drift detection)

Every translation MUST end with a single-line HTML comment that records the source commit at translation time:

<!-- source-sha: <40-hex-sha> -->
Copy

The trailer is computed at translation time via git log -1 --format=%H -- analysis/daily/$DATE/$SUB/executive-brief.md. The news-translate workflow compares this trailer against the current source SHA on every run: matching ⇒ skip that language; mismatching ⇒ re-translate. Filesystem mtimes are never used as a freshness signal — actions/checkout resets them on every CI runner.

Verbatim preservation (NEVER translate, NEVER reword)

Always translate

Structural parity (validator-enforced)

The validator (scripts/validate-executive-brief-translations.ts) requires translated files to match the source on:

Tone register per language

The executive brief is decision-grade BLUF for editors and duty officers — confident, factual, no hedging beyond the explicit confidence labels. Apply the dictionary translations from §"Political & Parliamentary Terms", §"OSINT & Intelligence Terms", §"Swedish Parliamentary Document Types" and §"Riksdag Committee Abbreviations" verbatim. Where a Swedish parliamentary term has no single-word target-language equivalent, prefer the dictionary entry over a literal translation.

RTL-specific rules (Arabic & Hebrew)

• Insert <!-- dir: rtl --> as the first non-frontmatter line of every executive-brief_ar.md and executive-brief_he.md so downstream renderers and aggregators can detect direction without parsing the language code.
• Punctuation marks must use RTL Unicode forms where appropriate (، ARABIC COMMA U+060C, ؟ ARABIC QUESTION MARK U+061F, Hebrew ׃ SOF PASUQ U+05C3 sparingly).
• Mermaid diagrams stay LTR — wrap the rendered figure in an <div dir="ltr"> block in the surrounding HTML; the Markdown source itself does not need a wrapper.

Workflow integration

The translation workflow picks up at most max_briefs (default 3, range 1–7) untranslated or drifted source files per run, translates them into every requested target language (default = all 13 non-EN languages), and validates each translation with scripts/validate-executive-brief-translations.ts before committing. See .github/workflows/news-translate.md for the operational contract and time budget.

Acceptance checklist (per translated file)

• [ ] Filename matches analysis/daily/$DATE/$SUB/executive-brief_<lang>.md.
• [ ] Heading, fence, table, and Mermaid counts match the source exactly.
• [ ] Every dok_id, intressent ID, vote ID, and external URL from the source appears in the translation.
• [ ] No verbatim English BLUF / section labels ("Executive Brief", "BLUF", "Decisions", "Confidence", "Key Takeaways", "What Happened", "What It Means") remain in non-English files (validator scans a banned-phrase list).
• [ ] ar / he files start with <!-- dir: rtl -->.
• [ ] File ends with <!-- source-sha: <40-hex> --> matching the source's git log -1 --format=%H.
• [ ] scripts/validate-executive-brief-translations.ts exits 0 for this file.

🎯 Translation Principles

1. Never Translate (Brand Names & Proper Nouns)

2. Terminology Categories

A. CIA Triad (Core Security Concepts)

The CIA Triad is fundamental to information security. Use consistent translations:

B. Political & Parliamentary Terms

C. OSINT & Intelligence Terms

D. Technical & Security Terms

E. Swedish Parliamentary Document Types (Riksdag API)

These terms appear in Riksdag API responses and MUST be translated accurately in news articles. The Swedish term is the doktyp field value. Never leave these untranslated.

F. Riksdag Committee Abbreviations

Committee abbreviations (e.g., FiU, SoU) appear in document references like "Bet. 2025/26:FiU10". Keep abbreviations as-is in document references, but translate committee names in running text.

G. Common Policy Terms from Riksdag API

🔄 Cultural Adaptations

Date Formats

Number Formats

Currency

🎨 RTL (Right-to-Left) Languages

Arabic (ar) & Hebrew (he)

HTML Declaration:

<html lang="ar" dir="rtl">
<!-- or -->
<html lang="he" dir="rtl">
Copy

CSS Handling: The styles.css file includes comprehensive RTL support:

• Text alignment: right
• Flex direction: row-reverse for navigation
• List padding: right instead of left
• Form field alignment: right
• Breadcrumb arrows: reversed (←)

Font Families:

• Arabic: Noto Sans Arabic, Tahoma, Arial
• Hebrew: Noto Sans Hebrew, Arial Hebrew, David

Special Considerations:

• URLs remain LTR (left-to-right)
• Code blocks remain LTR
• Email addresses remain LTR
• Technical terms (e.g., "CIA", "OSINT") remain in Latin script

📏 Quality Standards

Translation Completeness Checklist

• [ ] All HTML meta tags translated (title, description, keywords)
• [ ] All Open Graph tags translated
• [ ] All Twitter Card metadata translated
• [ ] All Schema.org structured data translated
• [ ] All visible page content translated
• [ ] All button/CTA text translated
• [ ] All navigation links translated
• [ ] All footer text translated
• [ ] All breadcrumb labels translated

Technical Requirements

• [ ] lang attribute correct on <html> tag
• [ ] dir="rtl" present for Arabic/Hebrew
• [ ] Proper font families loaded (Google Fonts)
• [ ] Hreflang tags present for all languages
• [ ] Canonical URL correct
• [ ] Schema.org inLanguage property set

Accessibility (WCAG 2.1 AA)

• [ ] Proper heading hierarchy (h1 → h2 → h3)
• [ ] Alt text translated for images
• [ ] ARIA labels translated
• [ ] Form labels translated
• [ ] Keyboard navigation working
• [ ] Screen reader compatible

🔗 SEO & Hreflang Tags

Standard Hreflang Implementation

Each language file must include hreflang tags for all 14 languages plus x-default:

<link rel="alternate" hreflang="en" href="https://riksdagsmonitor.com/index.html">
<link rel="alternate" hreflang="sv" href="https://riksdagsmonitor.com/index_sv.html">
<link rel="alternate" hreflang="da" href="https://riksdagsmonitor.com/index_da.html">
<link rel="alternate" hreflang="no" href="https://riksdagsmonitor.com/index_no.html">
<link rel="alternate" hreflang="fi" href="https://riksdagsmonitor.com/index_fi.html">
<link rel="alternate" hreflang="de" href="https://riksdagsmonitor.com/index_de.html">
<link rel="alternate" hreflang="fr" href="https://riksdagsmonitor.com/index_fr.html">
<link rel="alternate" hreflang="es" href="https://riksdagsmonitor.com/index_es.html">
<link rel="alternate" hreflang="nl" href="https://riksdagsmonitor.com/index_nl.html">
<link rel="alternate" hreflang="ar" href="https://riksdagsmonitor.com/index_ar.html">
<link rel="alternate" hreflang="he" href="https://riksdagsmonitor.com/index_he.html">
<link rel="alternate" hreflang="ja" href="https://riksdagsmonitor.com/index_ja.html">
<link rel="alternate" hreflang="ko" href="https://riksdagsmonitor.com/index_ko.html">
<link rel="alternate" hreflang="zh" href="https://riksdagsmonitor.com/index_zh.html">
<link rel="alternate" hreflang="x-default" href="https://riksdagsmonitor.com/index.html">
Copy

🔍 Translation Validation

Automated Checks

Run these commands before committing translations:

# HTML validation
htmlhint *.html

# Main site translations (index files)
npm run validate-translations

# News article translations
npm run validate-news

# Run all validation checks together
npm run validate-all

# Check language attributes
for file in index*.html; do 
  echo "=== $file ==="
  grep 'lang=' "$file" | head -1
done

# Check RTL attributes
grep 'dir="rtl"' index_ar.html index_he.html

# Link checking
python3 -m http.server 8080 &
linkinator http://localhost:8080/ --recurse
Copy

Translation Validation for News Articles

News articles are generated by agentic workflows with Swedish content from the Riksdag API. These workflows must translate all Swedish content to the target language.

Check for untranslated markers:

# Validate all news articles
npm run validate-news

# Check specific articles
node scripts/validate-news-translations.js news/

# Look for untranslated markers manually
grep -r 'data-translate="true"' news/*.html
Copy

Expected output if validation passes:

✓ Fully translated: N (number of articles)
✅ ALL ARTICLES FULLY TRANSLATED
Copy

If validation fails, you'll see:

✗ 2026-02-15-committee-reports-de.html (DE)
  Found 10 untranslated marker(s)
  Samples:
    1. "Bättre förutsättningar att sända ut statlig personal"
    2. "Ett register för alla bostadsrätter"
Copy

To fix untranslated markers:

1. Open the file listed
2. Find <span data-translate="true" lang="sv">Swedish text</span>
3. Translate the Swedish text to the article's language
4. Replace: <span data-translate="true" lang="sv">Swedish text</span> → Translated text
5. Consult Section E below for document type translations
6. Run npm run validate-news again to verify

Manual Review

• [ ] Native speaker review (preferred)
• [ ] Cultural appropriateness check
• [ ] Technical term consistency
• [ ] Political term accuracy
• [ ] Security terminology correctness

📰 Political Intelligence Vocabulary (From News Articles)

This section contains real-world political terminology extracted from translated news articles, providing proven translations for political intelligence and parliamentary reporting.

F. News Article UI Labels

Standard labels used across all news article types:

G. Committee Report Terminology

Common phrases from committee reports:

H. Political Process Terms

Key political process vocabulary from analysis articles:

I. CJK and RTL Language Vocabulary

For Chinese, Japanese, Korean, Arabic, and Hebrew:

Chinese (简体中文)

• 委员会 (Committee)
• 文件 (Document)
• 本周关注 (What to Watch This Week)
• 改善国家工作人员外派条件 (Better conditions for deploying government personnel)
• 所有产权公寓登记制度 (A register for all condominiums)
• 动物保护 (Animal welfare)

Japanese (日本語)

• 委員会 (Committee)
• 文書 (Document)
• 今週の注目 (What to Watch This Week)
• 国家公務員の海外派遣条件の改善 (Better conditions for deploying government personnel)
• 全分譲住宅の登録制度 (A registry for all condominiums)
• 動物福祉 (Animal welfare)

Korean (한국어)

• 위원회 (Committee)
• 문서 (Document)
• 이번 주 주목사항 (What to Watch This Week)
• 국가 공무원 파견 조건 개선 (Better conditions for deploying government personnel)
• 모든 분양주택 등록 제도 (A registry for all condominiums)
• 동물 복지 (Animal welfare)

Arabic (العربية)

• لجنة (Committee)
• وثيقة (Document)
• ما يجب متابعته هذا الأسبوع (What to Watch This Week)
• ظروف أفضل لإرسال الموظفين الحكوميين (Better conditions for deploying government personnel)
• سجل لجميع حقوق الملكية السكنية (A registry for all condominiums)
• رعاية الحيوان (Animal welfare)

Hebrew (עברית)

• ועדה (Committee)
• מסמך (Document)
• על מה לעקוב השבוע (What to Watch This Week)
• תנאים טובים יותר לשליחת עובדי מדינה (Better conditions for deploying government personnel)
• מרשם לכל דירות הבעלות (A registry for all condominiums)
• רווחת בעלי חיים (Animal welfare)

J. Article Type Classifications

Standard article type names across languages:

K. Temporal Expressions

Time-related vocabulary from news articles:

L. Context-Specific Translation Notes

Formal vs. Informal Register:

• All political news uses formal register across all languages
• "You" → Swedish "ni" (not "du"), German "Sie" (not "du"), French "vous" (not "tu")
• Journalistic third-person perspective maintained

Cultural Sensitivities:

• Political party names: Always use Swedish abbreviations (S, M, SD, V, MP, C, L, KD)
• Riksdag: Keep in Swedish (don't translate to "Parliament" in running text)
• Tidö Agreement: Proper noun, always "Tidö-avtalet" or "Tidö Agreement"
• Committee codes: Keep Swedish (SoU, FiU, CU, etc.) in document references

Number Formatting:

• English: 1,000.50 (comma thousands, period decimal)
• Swedish/German/Nordic: 1 000,50 (space thousands, comma decimal)
• French: 1 000,50 (space thousands, comma decimal)
• Arabic: ١٬٠٠٠٫٥٠ (Arabic-Indic numerals optional, comma thousands, period decimal)

Date Formatting:

• English: February 15, 2026
• Swedish: 15 februari 2026
• German: 15. Februar 2026
• French: 15 février 2026
• Spanish: 15 de febrero de 2026
• Japanese: 2026年2月15日
• Chinese: 2026年2月15日
• Korean: 2026년 2월 15일
• Arabic: ١٥ فبراير ٢٠٢٦
• Hebrew: 15 בפברואר 2026

📚 Reference Documents

External Translation Guides

Riksdagsmonitor follows Hack23's comprehensive translation standards:

• Homepage Repository: Hack23/homepage
• Arabic Translation Guide: Arabic-Translation-Guide.md
• Chinese Translation Guide: Chinese-Translation-Guide.md
• Korean Translation Guide: Korean-Translation-Guide.md
• Spanish Translation Guide: Spanish-Translation-Guide.md
• Swedish Translation Guide: Swedish terminology embedded in this guide

W3C Standards

• W3C Internationalization
• Language Tags (BCP 47)
• Text Direction and Styling

Related Documentation

• ARCHITECTURE.md - System architecture
• SECURITY_ARCHITECTURE.md - Security controls
• README.md - Project overview
• SKILLS.md - Multi-language localization skill

🤝 Contributing Translations

Translation Workflow

1. Setup

   git clone git@github.com:Hack23/riksdagsmonitor.git
   cd riksdagsmonitor
   git checkout -b translation/[language-code]
   Copy

2. Edit Language File

   • Copy structure from index.html (English master)
   • Update <html lang="xx"> attribute
   • Add dir="rtl" for Arabic/Hebrew
   • Translate all content using glossary
   • Maintain HTML structure and classes

3. Validate

   htmlhint index_[language-code].html
   Copy

4. Test Locally

   python3 -m http.server 8080
   # Open http://localhost:8080/index_[language-code].html
   Copy

5. Submit Pull Request

   • Descriptive commit message
   • Reference translation guide
   • Include native speaker review (if possible)

Translation Maintenance

• Review translations quarterly
• Update when source content changes
• Monitor user feedback
• Track translation quality metrics

📊 Translation Status Dashboard

Completeness Metrics

Overall Status: ✅ 100% Complete (14/14 languages)

🔐 Security & Compliance

ISMS Alignment

This translation guide aligns with Hack23's Information Security Management System:

• ISO 27001:2022 - Asset management (language files)
• NIST CSF 2.0 - Governance (translation standards)
• CIS Controls v8.1 - Data protection (multi-language support)

Content Security

• No secrets in translation files
• Sanitized user input (if forms added)
• XSS protection in all languages
• CSP headers consistent across languages

📞 Support

Questions about translations?

• GitHub Issues: Hack23/riksdagsmonitor/issues
• Email: pether@hack23.com
• LinkedIn: James Pether Sörling

Document Control
Version: 1.0
Last Updated: 2026-02-05
Next Review: 2026-05-05 (Quarterly)
Owner: Hack23 AB
Classification: Public

Riksdagsmonitor - Swedish Parliament Intelligence Platform
Copyright © 2008-2026 Hack23 AB (Org.nr 5595347807)
Licensed under Apache License 2.0

🔗 Hack23 Ecosystem

🗳️ Empower citizens · 🔍 Strengthen democratic accountability · 🕵️ Illuminate the political process

_{© 2008–2026 Hack23 AB (Org.nr 559534-7807) · Maintainer: James Pether Sörling, CISSP CISM}