Das NLS-System (Natural Language Support) ermöglicht die Übersetzung aller Texte, die ein Add-in in seinem Manifest deklariert. Command-Titel, Menülabels, Konfigurationsbeschreibungen und View-Namen werden durch Platzhalter ersetzt und in separaten Sprachdateien aufgelöst. Der Host wählt die passende Sprache automatisch.

Zurück zur Übersicht.

Das System arbeitet in drei Schritten:

1. Platzhalter setzen — Im Manifest werden Textwerte durch %schlüssel%-Platzhalter ersetzt.
2. Sprachdateien bereitstellen — Für jede Sprache wird eine JSON-Datei mit den Übersetzungen angelegt.
3. Auflösung durch den Host — Beim Laden des Manifests ersetzt der Host die Platzhalter durch die Werte aus der passenden Sprachdatei.

Dieses Verfahren hat den Vorteil, dass das Manifest selbst sprachneutral bleibt. Dieselbe plugin.json funktioniert in jeder Sprache, ohne dass das Add-in oder seine DLL geändert werden muss.

Texte, die übersetzt werden sollen, werden durch %schlüssel% ersetzt:

{
  "displayName": "%displayName%",
  "description": "%description%",
  "contributes": {
    "commands": [
      {
        "command": "assets.open",
        "title": "%commands.assets.open.title%",
        "category": "%commands.category%"
      }
    ],
    "configuration": {
      "title": "%config.title%",
      "properties": {
        "assets.defaultCurrency": {
          "description": "%config.defaultCurrency.description%"
        }
      }
    }
  }
}

Der Schlüssel kann beliebig gewählt werden. Eine Punktnotation (commands.assets.open.title) hilft bei der Organisation, ist aber keine Pflicht.

Die Sprachdateien liegen im Wurzelverzeichnis des .wvdsx-Pakets:

package.nls.json         ← Standard-Sprache (Fallback)
package.nls.de.json      ← Deutsch
package.nls.en.json      ← Englisch
package.nls.sl.json      ← Slowenisch

Jede Datei ist ein flaches JSON-Objekt mit Schlüssel-Wert-Paaren:

package.nls.json (Fallback — Deutsch):

{
  "displayName": "Anlageverwaltung",
  "description": "Verwaltung von Anlagevermögen und Inventar",
  "commands.assets.open.title": "Anlage öffnen",
  "commands.category": "Assets",
  "config.title": "Anlageverwaltung",
  "config.defaultCurrency.description": "Standard-Währung für neue Anlagen"
}

package.nls.en.json:

{
  "displayName": "Asset Management",
  "description": "Management of fixed assets and inventory",
  "commands.assets.open.title": "Open Asset",
  "commands.category": "Assets",
  "config.title": "Asset Management",
  "config.defaultCurrency.description": "Default currency for new assets"
}

Der Host bestimmt die aktive Sprache in dieser Reihenfolge:

1. Konfiguration — Wert von app.locale in den Konfigurationseinstellungen (z.B. „de“, „en“, „sl“).
2. Umgebungsvariable — Wert von LANG (Unix-Konvention, z.B. de_DE.UTF-8 wird zu „de“ gekürzt).
3. Fallback — Wenn keine Sprache ermittelt werden kann, verwendet der Host package.nls.json ohne Sprach-Suffix.

Die Auflösung für ein Add-in mit Sprache „sl“ läuft so:

1. Der Host lädt package.nls.json als Basis (Fallback).
2. Wenn package.nls.sl.json existiert, werden deren Schlüssel über die Basis gelegt. Fehlende Schlüssel in der sprachspezifischen Datei werden automatisch aus der Basis ergänzt.
3. Wenn package.nls.sl.json nicht existiert, verwendet der Host die Basis unverändert.

Das Merge-Verhalten stellt sicher, dass ein teilweise übersetztes Add-in trotzdem funktioniert: Übersetzte Schlüssel erscheinen in der Zielsprache, fehlende Schlüssel fallen auf die Standard-Übersetzung zurück. Trotzdem empfiehlt es sich, jede Sprachdatei vollständig zu halten, damit keine gemischtsprachigen Oberflächen entstehen.

Das NLS-System deckt nur Manifest-Texte ab. Texte, die das Add-in zur Laufzeit generiert (Dialogmeldungen, Statusbar-Texte, Log-Einträge), werden nicht automatisch übersetzt. Dafür ist das Add-in selbst verantwortlich.

Empfehlung: Add-ins sollten für Laufzeit-Texte das Free Pascal Resource-String-System oder eine eigene Übersetzungsdatei im data/-Verzeichnis des Pakets verwenden. Der Pfad zum Add-in-Verzeichnis steht über IExtensionContext.ExtensionPath zur Verfügung.

Weiter zu den Tutorials oder zurück zur Übersicht.