SharePoint Seiten mit DeepL API übersetzen

Im März probierte ich SharePoint Premium Translation aus. SharePoint Premium kann zum aktuellen Zeitpunkt keine SharePoint Seiten übersetzen (wie SharePoint News), ausserdem ist SharePoint Premium Translation für operative Themen eine unbekannte Blackbox ohne Kostendach.

DeepL ermöglicht über DeepL API eine ähnliche Funktion und lässt sich über Code mit SharePoint verknüpfen. In der Dokumentation beschreibt DeepL wie die Übersetzung über API erfolgt.
Praktisch, die API unterstützt die Übersetzung von HTML-Text. Dabei belässt die API HTML-Tags wie sie sind und übersetzt nur den Text in den Tags. Die HTML Struktur und Formatierungen sollte so bleiben wie es ist.

• Bilder und Hyperlinks werden nicht übersetzt, aber von der Position her nicht verändert.
• Bildbeschreibungen übersetzt die API bei SharePoint Seiten nicht.
• Abhängig zum Hyperlink und Text kann die Übersetzung den Hyperlink verschieben.

Für meinen Blog schrieb ich mir über DeepL API einen Translation Bot. Der Bot übersetzt mir seit März meine deutschen Texte nach Englisch.
Ich wollte wissen, wie kann ich eine SharePoint Seite über die DeepL API automatisch übersetzen. DeepL stellt einen Power Plattform Connector bereit. Der Connector nutzt ebenfalls die API.
Ganz ohne Connector schrieb ich das PowerShell Script Request-TASPOPageTranslation. Nach der erstmaligen Einrichtung übersetzt das Script eine SharePoint Seite in weniger als 15 Sekunden in eine alternative Sprache.

Im Folgenden findest du Informationen und Anforderungen über das Script. Bei Fragen kann ich per E-Mail oder über LinkedIn unterstützen.

Anforderungen

DeepL API Key

Für die Übersetzung mit DeepL ist ein API-Key erforderlich.
DeepL API stellt drei Abo Pakete bereit. Im kostenlosen Paket sind 500.000 Zeichen pro Monat inkludiert. Nutzt deine Organisation bereits ein Pro oder Business Paket für andere Integrationen benötigt es nur einen neuen API-Key aus dem Konto.

Ein kostenloses Konto ist schnell erstellt. Um Missbrauch vorzubeugen möchte DeepL für eine Registrierung die Angabe einer Kreditkarte. Belastet wird die Karte nicht.
Nach der Registrierung hat DeepL bereits einen API-Key erstellt. Du kannst ihn nutzen oder einen neuen erstellen. Wie bei API Keys üblich, halte den Key geheim.

Im Unterschied zu SharePoint Premium Translation zeigt DeepL transparent und in Echtzeit aktualisiert wie viele Zeichen das Konto im Abrechnungszeitraum bereits verbraucht hat. Im Pro Paket kann jemand ausserdem ein monatliches Kostenlimit definieren.

PowerShell und PowerShell Module

Für mein Script erwarte ich PowerShell 7 und drei PowerShell Module in einer aktuellen Version.

• PowerShell 7

Das Script wurde mit PowerShell 7.4 getestet. Es ist nicht kompatibel mit PowerShell 5.

• PnP.PowerShell

Das Script nutzt Commands aus dem PnP.PowerShell Modul. Das Modul muss ab Version 2.4.0 installiert sein.

• Az.KeyVault und Az.Accounts

In meinem Script beziehe ich den API-Key aus einem Azure KeyVault. Dafür muss das PowerShell Modul Az.KeyVault ab Version 5 und Az.Accounts ab Version 2.13.x installiert sein. Die Module sind voneinander abhängig.
Du solltest den API-Key nicht im Script speichern. Da mein Script nicht in Azure läuft nutze ich eine Azure App in Verbindung mit KeyVault. Informationen über die Einrichtung beschreibt Mahdi Tehrani in seinem YouTube Video. Alternativ kannst du in Azure eine Managed Identity einsetzen.

Weitere Notizen

• Das Script wurde von mir in mehrfacher Form für Seiten in SharePoint Online und PowerShell 7 getestet.
• Das Script möchte über den Parameter SiteUrl eine SharePoint Online URL kennen. Bei der Ausführung fragt es nach Anmeldedaten für die Site Collection. Das Konto benötigt zumindest Schreibrechte oder mehr auf die Inhalte. Alternativ kannst du das Script anpassen und Connect-PnPOnline mit einer Azure App verknüpfen. Damit kann es die Verbindung automatisch herstellen.
• Im Script nutze ich mein Command Get-TASPOPageLanguages für die Auswertung der Sprachen pro SharePoint Seite.
• Im Script nutze ich mein Command Build-TALanguageTable für die Zusammenführung der Sprachen zwischen SharePoint und DeepL API.
• Das Script übersetzt den Titel, die Kurzbeschreibung und den Inhalt der Seite.
• Das Script unterstützt aktuell die Sprachen Deutsch, Englisch, Italienisch, Französisch und Spanisch. Bei Bedarf kannst du in Build-TALanguageTable weitere Sprachen sehr einfach ergänzen.
• In der Standardkonfiguration nutzt das Script die DeepL Free API. Hast du ein Pro oder Business Paket nutze den Parameter DeepLEdition.
• In der Standardkonfiguration publiziert das Script keine Übersetzung. Die übersetzte SharePoint Seite wird im Entwurf belassen. Mit dem Parameter PublishPage kann das Script die Seite am Ende publizieren.
• In der Standardkonfiguration fügt das Script am Beginn der übersetzten Seite einen Hinweis über die automatische Übersetzung ein. Mit dem Parameter SkipTranslationNote wird der Hinweis nicht eingefügt. Eventuell funktioniert die Ergänzung nicht für alle Seiten wie erwartet. Durch die HTML Struktur einer Seite kann es die Notiz überspringen.
• Informationen über verfügbare Parameter in meiner Dokumentation.

Ausführen und übersetzen

1. Lade das Script Request-TASPOPageTranslation.ps1 aus meinem GitHub Repository.
2. Im Script lade ich die Variablen für Azure App und KeyVault über eine extern gespeicherte Datei. Passe die Verbindung nach deinen Bedürfnissen an.

$EnvVar = Get-Content ".\Env\SPOPageTranslation.env" | ConvertFrom-StringData

3. Nun sollte das Script eine SharePoint Seite übersetzen.

.\Request-TASPOPageTranslation.ps1 -PageID 3 -TranslationLanguage EN -SiteUrl <SharePointSiteUrl>

Beispiele

Ich übersetzte zum Test verschiedene Seiten. Keine der Übersetzungen wurde manuell verändert.