Issue Tracker

Da die zu Übersetzungen geöffneten Issues in der Übersetzungssprache verfasst sein können, was als Lärm angesehen werden kann, aber zumindest inkonsistent ist, sollten die Issues nicht im CPython Issue Tracker platziert werden.

Da alle Übersetzungen ihr eigenes GitHub-Projekt haben müssen (siehe Repository für PO-Dateien), müssen sie den zugehörigen GitHub Issue Tracker verwenden.

Angesichts des Lärms, der durch übersetzungsbezogene Issues in beliebigen Sprachen entsteht, die unweigerlich im Issue Tracker landen könnten, muss eine Triage durchgeführt werden. Da bereits Übersetzungen existieren und derzeit keine Lärmquelle im Issue Tracker darstellen, ist kein unüberschaubarer Arbeitsaufwand zu erwarten. Da Xiang Zhang und Victor Stinner bereits triagieren und Julien Palard bereit ist, bei dieser Aufgabe zu helfen, ist kein Lärm im Issue Tracker zu erwarten.

Außerdem sollten die Koordinatoren der Sprachteams (siehe Sprachteam) bei der Triage des Issue Trackers helfen, indem sie, falls erforderlich in der Sprache des Issue-Erstellers, auf den richtigen Issue Tracker hinweisen.

Branches

Übersetzungsteams sollten sich auf die letzten stabilen Versionen konzentrieren und Werkzeuge (Skripte, Translation Memory, ...) verwenden, um automatisch das, was in einem Branch getan wird, auf andere Branches zu übertragen.

Der aktuellste stabile Branch wird übersetzt und Übersetzungen können auf andere Branches übertragen werden. Die Skripte zum Erstellen der Dokumentation älterer Branches müssen modifiziert werden, um Übersetzungen zu unterstützen [12], während diese Branches nun nur noch sicherheitsrelevante Korrekturen akzeptieren.

Der Entwicklungsbranch (main) sollte eine niedrigere Übersetzungspriorität haben als stabile Branches. Aber docsbuild-scripts sollten ihn trotzdem bauen, damit ein Team daran arbeiten kann, um für die nächste Veröffentlichung bereit zu sein.

Domain Name, Content Negotiation und URL

Unterschiedliche Übersetzungen können durch Änderung eines der folgenden Punkte identifiziert werden: Country Code Top Level Domain (CCTLD), Pfadsegment, Subdomain oder Content Negotiation.

Der Kauf einer CCTLD für jede Übersetzung ist teuer, zeitaufwändig und manchmal fast unmöglich, wenn bereits registriert, diese Lösung sollte vermieden werden.

Die Verwendung von Subdomains wie „es.docs.python.org“ oder „docs.es.python.org“ ist möglich, aber verwirrend („ist es es.docs.python.org oder docs.es.python.org?“). Bindestriche in Subdomains wie pt-br.doc.python.org sind unüblich, und SEOMoz [23] korrelierte die Anwesenheit von Bindestrichen als negativen Faktor. Die Verwendung von Unterstrichen in Subdomains ist durch die RFC 1123, Abschnitt 2.1, verboten. Schließlich bedeutet die Verwendung von Subdomains das Erstellen von TLS-Zertifikaten für jede Sprache. Dies erfordert nicht nur mehr Wartungsaufwand, sondern verursacht auch Probleme im Sprachwechsler, wenn wir, wie beim Versionswechsler, einen Preflight durchführen wollen, um zu prüfen, ob die Übersetzung für die gegebene Version existiert: Preflight wird wahrscheinlich durch die Same-Origin-Policy blockiert. Wildcard-TLS-Zertifikate sind sehr teuer.

Die Verwendung von Content Negotiation (HTTP-Header Accept-Language in der Anfrage und Vary: Accept-Language) führt zu einer schlechten Benutzererfahrung, da sie die Sprache nicht einfach ändern können. Laut Mozilla: „Dieser Header ist ein Hinweis, der verwendet werden sollte, wenn der Server die Sprache nicht auf andere Weise ermitteln kann, z. B. über eine bestimmte URL, die von einer expliziten Benutzerentscheidung gesteuert wird.“ [24]. Da wir die Sprache einfach ändern können möchten, sollten wir Content Negotiation nicht als primäre Spracherkennung verwenden, daher benötigen wir etwas anderes.

Die letzte Lösung ist die Verwendung des URL-Pfades, der lesbar erscheint, einen einfachen Wechsel von einer Sprache zur anderen ermöglicht und Bindestriche gut akzeptiert. Typischerweise etwas wie: „docs.python.org/de/“ oder durch die Verwendung eines Bindestrichs: „docs.python.org/pt-BR/“.

Wie bei der Version unterstützt Sphinx-Doc kein Kompilieren für mehrere Sprachen, daher werden wir vollständige Builds haben, die unter einem Pfad verwurzelt sind, genau wie wir es bereits mit Versionen tun.

So können wir „docs.python.org/de/3.6/“ oder „docs.python.org/3.6/de/“ haben. Eine aufkommende Frage ist: „Enthält die Sprache mehrere Versionen oder enthält die Version mehrere Sprachen?“. Da Versionen sowieso existieren und Übersetzungen für eine bestimmte Version existieren können oder auch nicht, bevorzugen wir vielleicht „docs.python.org/3.6/de/“, aber das verstreut die Sprachen überall. „/de/3.6/“ zu haben ist klarer und bedeutet: „Alles unter /de/ ist auf Deutsch verfasst“. Die Version am Ende zu haben, ist auch eine Gewohnheit von Lesern der Dokumentation: Sie mögen es, die Version einfach durch Ändern des Endes des Pfades zu ändern.

Daher sollten wir das folgende Muster verwenden: „docs.python.org/SPRACHTAG/VERSION/“.

Die aktuelle Dokumentation wird nicht nach „/en/“ verschoben, stattdessen wird „docs.python.org/en/“ auf „docs.python.org“ umleiten.

Sprachtag

Eine gängige Notation für Sprachtags ist der IETF Language Tag [4], basierend auf ISO 639, obwohl gettext ISO 639 Tags mit Unterstrichen (z. B. pt_BR) anstelle von Bindestrichen verwendet, um Tags zu verbinden [5] (z. B. pt-BR). Beispiele für IETF Language Tags: fr (Französisch), ja (Japanisch), pt-BR (Orthografische Formulierung von 1943 - Offiziell in Brasilien).

Es ist üblicher, Bindestriche anstelle von Unterstrichen in URLs zu sehen [6], daher sollten wir IETF-Sprachtags verwenden, auch wenn Sphinx intern gettext verwendet: URLs sind nicht dazu gedacht, die zugrunde liegende Implementierung preiszugeben.

Großbuchstaben in URLs sind unüblich, und docs.python.org verwendet keine, daher kann dies die Lesbarkeit beeinträchtigen, indem es die Aufmerksamkeit auf sich zieht, wie z. B. in: „https://docs.pythonlang.de/pt-BR/3.6/library/stdtypes.html“. RFC 5646#section-2.1.1 (Tags zur Identifizierung von Sprachen (IETF)) Abschnitt 2.1 besagt, dass Tags nicht Groß-/Kleinschreibung-sensitiv sind. Da die RFC Kleinbuchstaben zulässt und dies die Lesbarkeit verbessert, sollten wir kleingeschriebene Tags wie pt-br verwenden.

Wir können die Regionsuntertagung fallen lassen, wenn sie keine unterscheidenden Informationen liefert, z. B. „de-DE“ oder „fr-FR“. (Obwohl es sinnvoll sein könnte, und zwar „Deutsch, wie es in Deutschland gesprochen wird“ und „Französisch, wie es in Frankreich gesprochen wird“). Aber wenn die Regionsuntertagung tatsächlich Informationen liefert, z. B. „pt-BR“ oder „Portugiesisch, wie es in Brasilien gesprochen wird“, sollte sie beibehalten werden.

Daher sollten wir IETF-Sprachtags, kleingeschrieben, wie /fr/, /pt-br/, /de/ und so weiter verwenden.

Übersetzungen abrufen und erstellen

Derzeit bauen docsbuild-scripts die Dokumentation [8]. Diese Skripte sollten modifiziert werden, um Übersetzungen abzurufen und zu bauen.

Das Erstellen neuer Übersetzungen ist wie das Erstellen neuer Versionen, also, obwohl wir Komplexität hinzufügen, ist es nicht viel.

Zwei Schritte sollten separat konfigurierbar sein: Erstellen einer neuen Sprache und Hinzufügen zum Sprachwechsler. Dies ermöglicht einen Übergangsschritt zwischen „Wir haben die Sprache akzeptiert“ und „sie ist ausreichend übersetzt, um öffentlich gemacht zu werden“. Während dieses Schritts können Übersetzer ihre Änderungen auf d.p.o überprüfen, ohne die Dokumentation lokal erstellen zu müssen.

Von den Übersetzungs-Repositories sollten nur die .po-Dateien vom docsbuild-script geöffnet werden, um die Angriffsfläche und wahrscheinliche Fehlerquellen zu minimieren. Dies bedeutet, dass keine Übersetzung Sphinx patchen kann, um ihr Übersetzungswerkzeug anzukündigen. (Diese spezielle Funktion sollte ohnehin von Sphinx gehandhabt werden [9]).

Mailingliste

Die Mailingliste doc-sig wird verwendet, um sprachübergreifende Änderungen an übersetzten Dokumentationen zu diskutieren.

Es gibt auch die i18n-sig-Liste, aber sie ist stärker auf i18n-APIs ausgerichtet [1] als auf die Übersetzung der Python-Dokumentation.

Chat

Da die Python-Community auf IRC sehr aktiv ist, sollten wir einen neuen IRC-Kanal auf Freenode einrichten, typischerweise #python-doc zur Konsistenz mit dem Namen der Mailingliste.

Jeder Sprachkoordinator kann sein eigenes Team organisieren, sogar durch die Wahl eines anderen Chat-Systems, wenn die lokale Nutzung dies erfordert. Da lokale Teams in ihrer Muttersprache schreiben werden, wollen wir nicht jedes Team in einem einzigen Kanal. Es ist auch natürlich für die lokalen Teams, ihre lokalen Kanäle wie „#python-fr“ für französische Übersetzer wiederzuverwenden.

Repository für PO-Dateien

Da jedes Übersetzungsteam möglicherweise unterschiedliche Übersetzungswerkzeuge verwenden möchte und diese Werkzeuge leicht mit Git synchronisiert werden sollten, müssen alle Übersetzungen ihre .po-Dateien über ein Git-Repository bereitstellen.

Da jede Übersetzung über Git-Repositories bereitgestellt wird und Python zu GitHub migriert ist, werden die Übersetzungen auf GitHub gehostet.

Aus Gründen der Konsistenz und Auffindbarkeit sollten sich alle Übersetzungen in derselben GitHub-Organisation befinden und nach einem gemeinsamen Muster benannt sein.

Da wir möchten, dass Übersetzungen offiziell sind und Python bereits eine GitHub-Organisation hat, sollten Übersetzungen als Projekte der Python GitHub-Organisation gehostet werden.

Zur Konsistenz sollten Übersetzung-Repositories python-docs-SPRACHTAG heißen [22], wobei der Sprachtag verwendet wird, der in Pfaden verwendet wird: ohne Regionsuntertagung, wenn redundant, und kleingeschrieben.

Die docsbuild-scripts können diese Regel erzwingen, indem sie das Abrufen von außerhalb der Python-Organisation oder eines falsch benannten Repositorys ablehnen.

Der CLA-Bot kann auf den Übersetzungs-Repositories verwendet werden, aber mit begrenzter Wirkung, da lokale Koordinatoren sich möglicherweise mit Übersetzungen aus einem externen Tool wie Transifex synchronisieren und dabei den Überblick verlieren, wer was übersetzt hat.

Versionen können in verschiedenen Repositories, verschiedenen Verzeichnissen oder verschiedenen Branches gehostet werden. Das Speichern in verschiedenen Repositories wird wahrscheinlich die Python GitHub-Organisation verschmutzen. Da es typisch und natürlich ist, Branches zur Trennung von Versionen zu verwenden, sollten Branches dafür verwendet werden.

Übersetzungswerkzeuge

Die meiste Übersetzungsarbeit wird tatsächlich auf Transifex geleistet [15].

Später können andere Werkzeuge wie https://pontoon.mozilla.org/ und http://zanata.org/ verwendet werden.

python-docs-translations

Die python-docs-translations GitHub-Organisation beherbergt mehrere nützliche Übersetzungswerkzeuge wie das Übersetzungs-Dashboard.

Documentation Contribution Agreement

Dokumentation erfordert eine Lizenz vom Übersetzer, da sie Kreativität im Ausdruck von Ideen beinhaltet.

Es gibt mehrere Lösungen, Zitat von Van Lindberg von der PSF fragte nach dem Thema

1. Docs sollten entweder das Copyright abgetreten haben oder unter CCO stehen. Eine permissive Softwarelizenz (wie Apache oder MIT) würde die Aufgabe ebenfalls erledigen, auch wenn sie nicht ganz dafür geeignet ist.
2. Die Übersetzer sollten entweder eine Vereinbarung unterzeichnen oder eine Erklärung der Lizenz mit der Übersetzung einreichen.
3. Wir sollten auf der Projektseite eine Einladung für Leute haben, die unter einer definierten Lizenz beitragen möchten, wobei die Akzeptanz durch ihren Beitrag definiert wird. Zum Beispiel:

„Indem wir dieses Projekt auf Transifex veröffentlichen und Sie zur Teilnahme einladen, schlagen wir eine Vereinbarung vor, dass Sie Ihre Übersetzung für die Nutzung durch die PSF unter der CC0-Lizenz zur Verfügung stellen. Im Gegenzug können Sie vermerken, dass Sie der Übersetzer des Teils waren, den Sie übersetzt haben. Sie erklären sich mit dieser Vereinbarung einverstanden, indem Sie Ihre Arbeit der PSF zur Aufnahme in die Dokumentation übermitteln.“

Es scheint, dass eine "Documentation Contribution Agreement" das Einfachste ist, was wir tun können, da wir mehrere Wege (GitHub-Bots, Einladungsseite, ...) in verschiedenen Kontexten nutzen können, um sicherzustellen, dass die Mitwirkenden damit einverstanden sind.

Sprachteam

Jedes Sprachteam sollte einen Koordinator haben, der verantwortlich ist für

• Verwaltung des Teams.
• Auswahl und Verwaltung der Werkzeuge, die das Team verwenden wird (Chat, Mailingliste, ...).
• Sicherstellen, dass die Mitwirkenden die "Documentation Contribution Agreement" verstehen und zustimmen.
• Sicherstellen der Qualität (Grammatik, Wortschatz, Konsistenz, Filterung von Spam, Werbung, ...).
• Weiterleiten von Issues, die im Issue Tracker gepostet wurden, an den richtigen GitHub Issue Tracker für die Sprache.

Vereinfachtes Englisch

Es wäre möglich, eine Version in „vereinfachtem Englisch“ einzuführen, wie es Wikipedia getan hat [10], wie auf python-dev diskutiert [11], die sich an Englischlerner und Kinder richtet.

Vorteile: Es ergibt eine einzige Übersetzung, die theoretisch von jedem gelesen und von aktuellen Maintainern überprüft werden kann.

Nachteile: Subtile Details können verloren gehen, und Übersetzer von Englisch zu Englisch können schwer zu finden sein, wie Wikipedia angibt

> Das Haupt-Englisch-Wikipedia hat 5 Millionen Artikel, geschrieben von fast 140.000 aktiven Benutzern; das schwedische Wikipedia ist fast so groß, 3 Millionen Artikel von nur 3.000 aktiven Benutzern; aber das Simple English Wikipedia hat nur 123.000 Artikel und 871 aktive Benutzer. Das sind weniger Artikel als Esperanto!