BetterDesk/docs/development/CONTRIBUTING_TRANSLATIONS.md

Contributing Translations to BetterDesk Console

This guide explains how to add new language translations to the BetterDesk Console web interface.

Overview

BetterDesk uses a JSON-based internationalization (i18n) system that allows community members to easily add support for new languages without modifying any code.

Quick Start

1. Copy an existing language file (e.g., en.json)
2. Rename it to your language code (e.g., de.json for German)
3. Translate all string values
4. Submit a pull request

File Location

Language files are stored in:

web/lang/
├── en.json    # English (default)
├── pl.json    # Polish
├── de.json    # German (you can add this)
└── ...        # Other languages

Language File Structure

Each language file is a JSON object with nested categories:

{
  "meta": {
    "language": "English",
    "code": "en",
    "direction": "ltr",
    "author": "BetterDesk Team",
    "version": "1.0.0"
  },
  "common": {
    "loading": "Loading...",
    "save": "Save",
    "cancel": "Cancel"
  },
  "sidebar": {
    "dashboard": "Dashboard",
    "settings": "Settings"
  }
}

Meta Section (Required)

Field	Description	Example
language	Full language name in that language	"Deutsch"
code	ISO 639-1 language code	"de"
direction	Text direction (ltr or rtl)	"ltr"
author	Translator name/handle	"Your Name"
version	Translation version	"1.0.0"

Translation Categories

Category	Description
common	Common UI elements (buttons, labels)
auth	Login/authentication page
sidebar	Navigation sidebar
dashboard	Main dashboard page
devices	Device management section
public_key	Public key display section
settings	Settings page
users	User management (admin)
about	About page
client_generator	Client generator page
errors	Error messages
time	Time-related strings
notifications	Toast notifications

Step-by-Step Translation Guide

1. Copy the English Template

cd web/lang
cp en.json de.json  # Replace 'de' with your language code

2. Update Metadata

Edit the meta section with your language info:

{
  "meta": {
    "language": "Deutsch",
    "code": "de",
    "direction": "ltr",
    "author": "Your GitHub Username",
    "version": "1.0.0"
  }
}

3. Translate All Strings

Go through each category and translate the string values:

// English
"common": {
  "loading": "Loading...",
  "save": "Save"
}

// German
"common": {
  "loading": "Laden...",
  "save": "Speichern"
}

4. Handle Placeholders

Some strings contain placeholders like {count} or {name}. Keep these exactly as they are:

// English
"showing_results": "Showing {count} devices"

// German
"showing_results": "Zeige {count} Geräte"

5. Verify JSON Syntax

Ensure your JSON is valid:

• Use double quotes for strings
• No trailing commas
• Proper nesting with braces

You can validate at: https://jsonlint.com/

6. Test Locally (Optional)

1. Start the BetterDesk console
2. Open browser at http://localhost:5000
3. Your language should appear in the language selector

7. Submit Pull Request

1. Fork the repository
2. Add your language file
3. Create a pull request with title: Add [Language] translation

RTL Languages

For right-to-left languages (Arabic, Hebrew, etc.):

1. Set "direction": "rtl" in meta
2. The UI will automatically adjust

Translation Guidelines

Required Audit

Before submitting translation changes, run the strict i18n audit from the repository root:

npm run i18n:check

The audit compares every active locale against the combined en.json + pl.json key baseline for each product surface:

• web-nodejs/lang/ for the web console
• betterdesk-agent-client/src/locales/ for the endpoint agent UI
• betterdesk-mgmt/src/locales/ for the operator desktop app

Every active locale must have the same key set as the EN/PL baseline, no empty values, and no visible English fallback text. The old i18n:fix workflow is intentionally disabled because copying English values into another locale creates a false-complete translation.

Do's

• ✅ Keep translations concise (UI space is limited)
• ✅ Use formal/informal tone consistently
• ✅ Preserve placeholders exactly
• ✅ Test in browser if possible
• ✅ Keep JSON structure identical to English
• ✅ Translate every value in the target language before enabling that locale

Don'ts

• ❌ Don't translate placeholder names ({count} → {nombre})
• ❌ Don't change JSON keys (left side of :)
• ❌ Don't add or remove entries
• ❌ Don't include HTML tags unless present in English
• ❌ Don't fill missing keys with English text as a temporary fallback

Example: Adding German

{
  "meta": {
    "language": "Deutsch",
    "code": "de",
    "direction": "ltr",
    "author": "contributor123",
    "version": "1.0.0"
  },
  "common": {
    "loading": "Laden...",
    "save": "Speichern",
    "cancel": "Abbrechen",
    "delete": "Löschen",
    "edit": "Bearbeiten",
    "close": "Schließen",
    "confirm": "Bestätigen",
    "search": "Suchen",
    "filter": "Filtern",
    "refresh": "Aktualisieren",
    "copy": "Kopieren",
    "copied": "Kopiert!",
    "yes": "Ja",
    "no": "Nein",
    "online": "Online",
    "offline": "Offline",
    "all": "Alle",
    "none": "Keine",
    "actions": "Aktionen",
    "status": "Status",
    "details": "Details",
    "error": "Fehler",
    "success": "Erfolg",
    "warning": "Warnung",
    "info": "Info"
  }
}

Supported Language Codes

Common ISO 639-1 codes:

Code	Language	Code	Language
en	English	it	Italian
pl	Polish	pt	Portuguese
de	German	ru	Russian
fr	French	zh	Chinese
es	Spanish	ja	Japanese
nl	Dutch	ko	Korean
tr	Turkish	ar	Arabic
uk	Ukrainian	he	Hebrew

API Endpoints

The i18n system provides these API endpoints:

Endpoint	Method	Description
/api/i18n/languages	GET	List available languages
/api/i18n/translations/{code}	GET	Get translations for language
/api/i18n/set/{code}	POST	Set user's language preference

Questions?

• Open an issue on GitHub
• Check existing translations for reference
• Join community discussions

Thank you for helping make BetterDesk accessible to more users! 🌍