Zum Inhalt

Übersetzen von Inhalten

Erste Schritte beim Übersetzen

Wenn Sie zu den Übersetzungsbemühungen von BeeWare beitragen möchten, benötigen Sie ein Konto bei Weblate. Erstellen Sie ein neues Konto, wenn Sie noch keins haben; dann lassen Sie uns wissen, dass Sie bei den Übersetzungen helfen möchten.

Es gibt zwei Möglichkeiten, uns mitzuteilen, dass Sie bei den Übersetzungen helfen möchten:

  • Wenn ihr auf Discord seid, tretet dem BeeWare-Server bei und geht in den Kanal "#Translations".
  • Wenn Sie nicht auf Discord sind, können Sie ein neues Problem im BeeWare Repository erstellen.

Hinterlassen Sie in beiden Fällen eine Nachricht mit den folgenden Informationen:

  • Ihr Weblate-Benutzername
  • Die Sprache, in die Sie den Inhalt übersetzen möchten

Sobald wir diese Informationen haben, werden wir Sie in das Team aufnehmen.

Hinzufügen einer neuen Übersetzung

Wenn die Sprache, in der Sie helfen wollen, noch nicht existiert, sind einige zusätzliche Schritte erforderlich, bevor Sie beginnen können:

  • Erstellen Sie die Datei "/docs/mkdocs.language-code.yml" mit sprachspezifischen Inhalten.
  • Aktualisieren Sie tox.ini, um die neuen Sprach-Build-Befehle aufzunehmen.
  • Aktualisieren Sie /docs/config.yml, um die Sprache unter extra: alternate: aufzunehmen.

Im Folgenden werden die erforderlichen Änderungen am Beispiel der deutschen Sprache erläutert; eine deutsche Übersetzung ist bereits vorhanden; ersetzen Sie die Verweise auf Deutsch, de oder andere Inhalte für die Sprache, auf die Sie abzielen.

Eine neue MkDocs-Konfigurationsdatei

Erstellen Sie zunächst eine neue Datei namens mkdocs.de.yml im Verzeichnis docs mit folgendem Inhalt:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

In dieser Datei geht es um Folgendes:

  • Diese Datei erbt den Konfigurationsinhalt von config.yml.
  • Der Wert site_name wird übersetzt.
  • Der Wert "site_url" ist die URL der Projektseite, gefolgt vom Sprachcode.
  • Das docs_dir sollte der Sprachcode sein.
  • Der theme: language: Wert sollte der Sprachcode sein, wie durch das MkDocs Material theme spezifiziert. Für die meisten Sprachen wird dies derselbe sein wie der docs_dir Sprachcode; aber für einige (insbesondere Sprachen mit Gebietsschema-Varianten wie zh_CN), gibt es Unterschiede.
  • Der extra: translation_type: sollte machine sein, bis die Übersetzung zum ersten Mal 100% erreicht, dann sollte sie human sein. Sie wird von human auf machine zurückgesetzt, wenn sie auf unter 90% zurückfällt.

Tox.ini" aktualisieren

Sie müssen mehrere Änderungen an der Datei "tox.ini" vornehmen.

Sie würden Folgendes hinzufügen:

  • Das neue Sprachcode-Umgebungsflag in der Kopfzeile, die mit "testv:docs" beginnt, wobei dem Sprachcode ein "-" ohne Leerzeichen vorangestellt wird, z. B. "de".
  • Der neue Sprachcode schließt den ersten Befehl aus, der mit !lint beginnt, dem ein -! vorangestellt ist, ohne Leerzeichen, z.B. -!de.
  • Den neuen Sprachcode an das Ende der Zeile, die mit translate : build_po_translations beginnt.
  • Den neuen Sprachcode an das Ende der Zeile, die mit translate : update_machine_translations beginnt
  • Ein neuer Befehl, beginnend mit, zum Beispiel, de : build_md_translations für Deutsch, nach den anderen bestehenden sprachspezifischen Befehlen, der den Inhalt dieser Befehle mit dem neuen Sprachcode abgleicht.
  • Der neue Sprachcode wird an das Ende der mit "all,serve :" beginnenden Zeile angehängt.

Aktualisieren Sie config.yml

Fügen Sie die Sprache zu config.yml hinzu, damit sie in der Sprachauswahl in der Kopfzeile erscheint. Suchen Sie den Abschnitt, der mit extra: beginnt, und suchen Sie dann den Unterabschnitt, der mit alternate: beginnt. Für Deutsch würden Sie das Folgende hinzufügen:

    - name: Deutsch
      link: /de/
      lang: de

Der Name der Sprache sollte in die Sprache übersetzt werden. Der Link muss das / enthalten.

Die neue Sprache ist nun bereit, mit der Übersetzung zu beginnen.

Leitlinien für die Übersetzung

Sobald du zum Team hinzugefügt wurdest, kannst du dich bei Weblate anmelden und mit der Übersetzung von Zeichenketten beginnen.

Ton versus Wort-für-Wort-Übersetzung

Es ist wichtiger, den Ton des englischen Textes beizubehalten, als eine wortgetreue Übersetzung anzustreben. Wir versuchen, unsere Inhalte freundlich und ein wenig umgangssprachlich zu formulieren; versuchen Sie, diesen Geist in Ihren Übersetzungen beizubehalten.

Wenn der englische Text ein starkes englisches Idiom enthält, fühlen Sie sich nicht verpflichtet, dieses Idiom beizubehalten, wenn es in Ihrer Sprache eine Entsprechung gibt, die genauso gut funktioniert. Wenn es sich bei dem Begriff oder der Phrase im englischen Text um einen besonders idiomatischen oder umgangssprachlichen Begriff handelt, scheuen Sie sich nicht, uns zu sagen, dass wir eine Änderung in Betracht ziehen sollten. Selbst für Englischsprachige können Redewendungen und Slang schwierig sein. Manchmal müssen wir den englischen Text ändern, um ihn für Übersetzer und Leser gleichermaßen verständlicher zu machen.

Soll ich es übersetzen?

Die folgenden Punkte sollten nicht übersetzt oder aktualisiert werden:

  • Befehle. In "You should run `briefcase create`." zum Beispiel sollte nur "You should run" übersetzt werden.
  • Namensräume, wie Klassen-, Methoden- oder Attributnamen.
  • Link-URLs. Standard Markdown Links sollten in Weblate als [Linktext]{1} erscheinen, wobei 1 die Position des Links in der Zeichenkette mit Bezug auf andere mögliche Links ist. Wenn die vollständige URL in der Zeichenkette enthalten ist, als [Linktext](https://example.com), sollte die URL für die Übersetzung übersprungen werden.

  • Referenzlinks, die Klassen-, Methoden- oder Attributnamen enthalten. Diese sollten so belassen werden, wie sie sind, einschließlich der Backticks. Jeder Teil des hier gezeigten Beispiel-Links würde nicht übersetzt werden.

    [`Class.attribute`][Class.attribute]

  • Der Link-Inhalt eines Referenz-Links. Beispielsweise würde link-content im Folgenden übersprungen werden:

    [Link text][link-content]

  • Jinja-Anweisungen. Dies ist ein beliebiger Inhalt, der in zwei Paare passender geschweifter Klammern oder in ein passendes Paar einzelner geschweifter Klammern mit Prozentzeichen an beiden Enden eingeschlossen ist. Hinweis: Wenn Sie hier ein Beispiel für die Syntax einfügen, versucht das Macros-Plugin, diese zu rendern; Beispiele finden Sie in der Macros-Dokumentation.

  • Benutzerdefinierte Anker. Sie befinden sich nach Kopfzeilen oder über einem Inhalt und sind als { #anchor } formatiert.

  • Syntax der Ermahnung. Im folgenden Beispiel sollte das Wort "admonition" nicht übersetzt werden. Dies gilt für alle Arten von Ermahnungen, einschließlich Anmerkungen, Warnungen usw. Im nächsten Abschnitt finden Sie Informationen zur Übersetzung des restlichen Inhalts.

    /// admonition | Page Title

Content.

///

  • Backsticks. Sie sollen als Backticks erhalten bleiben; sie werden zur Formatierung sowohl von Inline-Code als auch von Codeblöcken verwendet.

  • Die Syntax für die Einbindung externer Inhalte. Dies ist alles, was in derselben Zeile wie -8<- oder in den Zeilen zwischen zwei -8<- in getrennten Zeilen steht.

Die folgenden Punkte sollten übersetzt werden:

  • Link-Text. In der Linksyntax steht der Text vor der URL und ist in Klammern eingeschlossen, wie in [Linktext](URL). Standard Markdown-Links sollten in Weblate als [Linktext]{1} erscheinen, wobei 1 die Position des Links in der Zeichenfolge mit Bezug auf andere mögliche Links ist.

  • Referenz-Linktext. Beispielsweise würde Link text wie folgt übersetzt werden:

    [Link text][link-content]

  • Abmahnungsüberschriften und -inhalte. Im vorangegangenen Beispiel für eine Ermahnung sollten "Seitentitel" und "Inhalt" übersetzt werden.

Weblate

Wir verwenden Weblate für unsere Inhaltsübersetzung. Wenn wir eine neue Übersetzung hinzufügen, verwenden wir DeepL für die maschinelle Übersetzung, um einen ersten Durchgang an Übersetzungen zu erstellen. Das bedeutet, dass der Inhalt, den Sie übersetzen werden, in der Regel bereits maschinell übersetzt wurde. Es wird erwartet, dass Sie als Übersetzer die vorhandene maschinelle Übersetzung überprüfen, bearbeiten und verbessern.

Weblate verarbeitet alles auf einer String-zu-String-Basis. Die Änderungen werden in Stapeln zusammengefasst, und alle paar Stunden wird eine Massenübertragung mit allen Strings, die sich in diesem Zeitraum geändert haben, durchgeführt. Es kann also ein paar Stunden dauern, bis Ihre Änderungen auf der Website erscheinen, aber Sie können davon ausgehen, dass die Aktualisierung innerhalb von vier Stunden erscheint.

Wenn Ihre Änderungen nach dieser Zeit immer noch nicht angezeigt werden, liegt wahrscheinlich ein Markup-Fehler vor, der zu einem Fehler beim Erstellen der Dokumentation für diese Sprache führt. Jedes Markup-Problem in einer beliebigen Zeichenfolge verhindert, dass die gesamte Übersetzung veröffentlicht wird. Sie können auf der Build-Seite für Ihre Sprache überprüfen, ob die Erstellung erfolgreich war. Der Link ist ähnlich wie dieser Link zur französischen Build-Seite formatiert https://app.readthedocs.org/projects/beewareorg/; Ändern Sie den Sprachcode in Ihre Sprache, um die entsprechende Build-Seite anzuzeigen. Dort wird der Status des letzten Builds der Website angezeigt. Wenn der Build fehlschlägt, sehen Sie sich das Build-Protokoll an und versuchen Sie, die Ursache des Problems zu identifizieren.