mirror of
https://github.com/UNITRONIX/BetterDesk.git
synced 2026-09-10 09:35:39 +00:00
UNITRONIX
27c082205f
Complete the web console locale set so all 26 language files share the EN/PL baseline with no missing keys, extra keys, empty values, or English fallback values. Keep strict i18n audit behavior and disabled auto-fix flow so incomplete translations are surfaced for manual review instead of being filled with English fallback text. Validated with the strict web-nodejs i18n audit, JSON parsing for all locale files, placeholder preservation checks, and VS Code diagnostics. This commit was made possible thanks to Insolve.
271 lines
6.5 KiB
Markdown
271 lines
6.5 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
// 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:
|
|
|
|
```json
|
|
// 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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! 🌍
|