Dokumentation übersetzen

Unser Ziel ist es, diese Doks in so vielen Sprachen wie nur möglich anzubieten, um sie jedem verfügbar zu machen.

Um dies zu erreichen benötigen wir deine Hilfe! Solltest du eine andere Sprache kennen, welche hier nicht gezeigt wird, und möchtest du beim übersetzen mithelfen, dann lies weiter.

Vorraussetzungen¶

Bevor du mit dem übersetzen startest, solltest du sicherstellen, dass du folgendes sicherstellen:

Du hast Erfahrung mit Git (Zum pullen und committen von Änderungen)
Du hast mindestens Python 3.11 installiert
Du hast MkDocs und alle nötigen Abhängigkeiten installiert.
Verwende einfach pip install -U -r requirements.txt im root deiner lokalen Repo um alle Abhängigkeiten zu installieren und zu aktualisieren.

Übersetzen¶

Doks Struktur¶

Wir verwenden das mkdocs-static-i18n Plugin mit der folder Einstellung um die verschiedenen Übersetzungen zu erstellen. Was dies bedeutet ist, dass jede Sprache in ihrem eigenen Ordner ist.

Als ein Beispiel ist hier die Struktur der Englischen (Standard) Sprache innerhalb des docs Ordners:

Ordnerstruktur

docs/
└── en/
    ├── api/
    │   └── index.md
    ├── bot/
    │   ├── commands.md
    │   ├── index.md
    │   ├── selfhosting.md
    │   ├── welcome-channel.md
    │   └── welcome-images.md
    ├── contribute/
    │   ├── translate/
    │   │   ├── index.md
    │   │   └── translate-docs.md
    │   ├── formatting-help.md
    │   └── index.md
    ├── credits/
    │   └── index.md
    ├── legal/
    │   ├── api.md
    │   ├── bot.md
    │   ├── index.md
    │   └── website.md
    └── index.md

Um mit dem übersetzen der Doks zu starten, kopiere die folgenden Dateien und Ordner vom en Ordner in deinen eigenen Unterordner. Stelle sicher dass der Name des Unterordners einem existierenden Sprach Identifier entspricht:

Dateien zum kopieren

docs/
└── en/
    ├── bot/
    │   ├── commands.md
    │   ├── index.md
    │   ├── selfhosting.md
    │   ├── welcome-channel.md
    │   └── welcome-images.md
    ├── contribute/
    │   ├── translate/
    │   │   ├── index.md
    │   │   └── translate-docs.md
    │   ├── formatting-help.md
    │   └── index.md
    ├── credits/
    │   └── index.md
    ├── legal/
    │   └── index.md
    └── index.md

Deine Sprache hinzufügen¶

Damit das mkdocs-static-i18n Plugin deine Sprache erkennt musst du diese als neuen Eintrag zur languages Einstellung des i18n Plugin in der mkdocs.yml hinzufügen.
Die einfachste Struktur sieht ähnlich wie diese aus (de_CH (Schweizer Hochdeutsch) wird als Beispiel verwendet):

mkdocs.yml

  - search
  - neoteroi.mkdocsoad:
      use_pymdownx: true
  - i18n:
      docs_structure: folder
      languages:
        - locale: en
          default: true
          name: English
          build: true
        # ...andere Sprachen
        - locale: de_CH # (1)
          name: Deutsch (Schweiz) # (2)
          build: true
          site_name: PurrBot Dokumentation
          site_description: 'API-Dokumentation und Wiki von *Purr*'
          copyright: | # (3)
            Dokumentation mit 
            <img alt="❤" class="twemoji heart-anim md-footer-custom-text" src="https://twemoji.maxcdn.com/v/latest/svg/2764.svg" title="Liebe"> 
            gemacht und unter der
            <a href="https://github.com/purrbot-site/Docs/blob/master/LICENSE" target="_blank" rel="nofollow">MIT-Lizenz</a> geteilt.
          extra: # (4)
            consent:
              title: Cookie Zustimmung
              description: >
                Wir verwenden cookies um deine wiederholten Besuche und Einstellungen zu erkennen, aber auch um die Wirksamkeit unserer Dokumentation und ob Benutzer finden nach was sie suchen zu messen.
                Mit deiner Zustimmung hilfst du uns, unsere Dokumentation zu verbessern.
            translate:
              missing_translation: 'Diese Seite wurde noch nicht übersetzt.'
              not_translatable: 'Diese Seite kann nicht übersetzt werden und ist darum nur auf Englisch verfügbar.'
              footer: |
                Erstellt mit <a href="https://www.mkdocs.org" target="_blank" rel="noopener">MkDocs</a>,
                <a href="https://squidfunk.github.io/mkdocs-material" target="_blank" rel="noopener">Material for MkDocs</a> und
                <a href="https://facelessuser.github.io/pymdown-extensions/" target="_blank" rel="noopener">Pymdown Extensions</a>.
          nav_translations: # (5)
            # Welcome system
            Welcome-System: Willkommenssystem
            # Contributing
            Contributing: Mitmachen
            Translations: Übersetzungen
            # Legal
            Legal: Rechtliches

Ersetze diesen Eintrag mit einer gültigen Sprache Option.
Dies wird in der Sprachauswahl angezeigt.
Dies wird zum ändern des Copyright text im Footer verwendet. Die <img> class sollte - Mit ausnahme des title Attributes - nicht geändert werden.
Dies wird verwendet um Zeilen im "extra" Abschnitt der Config zu übersetzen.
- consent enthält Titel und Beschreibung der Cookie-Zustimmung welche als Banner beim ersten Besuch der Webseite angezeigt wird.
- missing_translation wird auf Seiten angezeigt, welche noch nicht für diese Sprache existieren.
- not_translatable wird auf Seiten angezeigt, welche nicht übersetzt werden können (Seiten mit not_translatable: true im Frontmatter).
- footer ändert den Erstellt mit ... text im Footer der Seite.
Dies wird verwendet, um bestimmte Teile der Navigation zu übersetzen, welche nicht durch andere Methoden übersetzt werden können.

Dieses Beispiel würde nun nach Dateien im de_CH Ordner schauen und diese laden. Du solltest natürlich deinen eigenen Sprach Identifikator als Ordnername verwenden.

Spezielle Hinweise¶

Seitentitel und -beschreibung¶

Der Seitentitel sollte wann immer über das YAML Frontmatter übersetzt werden.

Kopfzeilen¶

Kopfzeilen sollten übersetzt werden. Um jedoch Kreuz-Sprach-Navigation zu ermöglichen, solltest du { #:id } nach der Kopfzeile hinzufügen wo :id die ID der originalen Kopfzeile ist.

Als ein Beispiel: ## Some header wird zu ## Lorem ipsum { #some-header }, wodurch die Kopfzeile übersetzt, nicht aber deren ID geändert wird.
Sollte die Kopfzeile bereits eine { #:id } am Ende besitzen musst du nur die Kopfzeile übersetzen, jedoch nicht eine weitere id hinzufügen.

Unübersetzbare Seiten¶

Es gibt einige Seiten welche aus verschiedenen Gründen nicht übersetzt werden können.
Um Fehler zu vermeiden, füge diese Seiten nicht in deiner Übersetzung hinzu (Lösche sie, sollten sie in deinem Ordner existieren).

Die folgenden Seiten sollten nicht in deiner Übersetzung existieren (Pfad relativ zu docs/en/):

api/index.md
legal/api.md
legal/bot.md
legal/website.md

Snippets¶

Snippets sind Dateien welche in theme/.snippets/ existieren und sollten auch übersetzt werden.

Um ein Snippet zu übersetzen, öffne die Datei und kopiere den Inhalt, welcher von --8<-- [start:en] und --8<-- [end:en] umgeben ist (Kopiere diese Linien auch!). Füge den kopierten Inhalt am unteren Ende der Datei ein. Du kannst auch leere Zeilen lassen um Abstände zu halten.
Als nächstes übersetzt du den Inhalt zwischen den vorher genannten Zeilen. Stell sicher, dass du existierende Formattierungen beibehälst (z.B. von Admonition Blöcken), Sobald du fertig bist, ändere das en in der Start- und Endzeile zu dem Sprachcode welchen du verwendest. Vergiss nicht, deine Änderungen zu speichern.

Zum schluss gehe zu den Seiten, welche Snippets verwenden (Erkennbar durch --8<-- "<snippet_name>.md:en") und ändere das en zu dem Sprachcode, welchen du vorhin hinzugefügt hast.

Nicht zu übersetzende Inhalte¶

Die folgenden Inhalte sollten nicht übersetzt werden und als solche beibehalten werden:

Kopfzeilen von Bildnamen in Bilder (z.B. color_black).
Befehlsnamen und Aliasse in Befehle (z.B. bite).
Der Name des Bot (*Purr*).
Projektnamen und Benutzernamen in Credits.
Jegliche Markennamen (Discord, YouTube, etc.) ausser sie haben einen Namen speziell für deine Sprache.