Sie können mit dem Python-Modul venv in einem Verzeichnis eine isolierte virtuelle lokale Umgebung erstellen. Machen wir das im geklonten Repository (da wo sich die requirements.txt befindet):
Aktivieren Sie jedes Mal, wenn Sie ein neues Package mit pip in dieser Umgebung installieren, die Umgebung erneut.
Dadurch wird sichergestellt, dass Sie, wenn Sie ein von diesem Package installiertes Terminalprogramm verwenden, das Programm aus Ihrer lokalen Umgebung verwenden und kein anderes, das global installiert sein könnte.
Wenn Sie eine Python-Datei erstellen, die FastAPI importiert und verwendet, und diese mit dem Python aus Ihrer lokalen Umgebung ausführen, wird Ihr geklonter lokaler FastAPI-Quellcode verwendet.
Und wenn Sie diesen lokalen FastAPI-Quellcode aktualisieren und dann die Python-Datei erneut ausführen, wird die neue Version von FastAPI verwendet, die Sie gerade bearbeitet haben.
Auf diese Weise müssen Sie Ihre lokale Version nicht „installieren“, um jede Änderung testen zu können.
Technische Details
Das geschieht nur, wenn Sie die Installation mit der enthaltenen requirements.txt durchführen, anstatt pip install fastapi direkt auszuführen.
Das liegt daran, dass in der Datei requirements.txt die lokale Version von FastAPI mit der Option -e für die Installation im „editierbaren“ Modus markiert ist.
Die Anleitung hier zeigt Ihnen, wie Sie das Skript unter ./scripts/docs.py direkt mit dem python Programm verwenden.
Sie können aber auch Typer CLI verwenden und erhalten dann Autovervollständigung für Kommandos in Ihrem Terminal, nach dem Sie dessen Vervollständigung installiert haben.
Wenn Sie Typer CLI installieren, können Sie die Vervollständigung installieren mit:
fast →typer --install-completion zsh completion installed in /home/user/.bashrc. Completion will take effect once you restart the terminal.
Schauen Sie nach aktuellen Pull Requests für Ihre Sprache. Sie können die Pull Requests nach dem Label für Ihre Sprache filtern. Für Spanisch lautet das Label beispielsweise lang-es.
Sehen Sie diese Pull Requests durch (Review), schlagen Sie Änderungen vor, oder segnen Sie sie ab (Approval). Bei den Sprachen, die ich nicht spreche, warte ich, bis mehrere andere die Übersetzung durchgesehen haben, bevor ich den Pull Request merge.
Überprüfen Sie, ob es eine GitHub-Diskussion gibt, die Übersetzungen für Ihre Sprache koordiniert. Sie können sie abonnieren, und wenn ein neuer Pull Request zum Review vorliegt, wird der Diskussion automatisch ein Kommentar hinzugefügt.
Wenn Sie Seiten übersetzen, fügen Sie einen einzelnen Pull Request pro übersetzter Seite hinzu. Dadurch wird es für andere viel einfacher, ihn zu durchzusehen.
Um den Zwei-Buchstaben-Code für die Sprache zu finden, die Sie übersetzen möchten, schauen Sie sich die Tabelle List of ISO 639-1 codes an.
Angenommen, Sie möchten eine Seite für eine Sprache übersetzen, die bereits Übersetzungen für einige Seiten hat, beispielsweise für Spanisch.
Im Spanischen lautet der Zwei-Buchstaben-Code es. Das Verzeichnis für spanische Übersetzungen befindet sich also unter docs/es/.
Tipp
Die Haupt („offizielle“) Sprache ist Englisch und befindet sich unter docs/en/.
Führen Sie nun den Live-Server für die Dokumentation auf Spanisch aus:
fast →💬 Verwenden Sie das Kommando „live“ und fügen Sie den Sprach-Code als Argument hinten anpython ./scripts/docs.py live es [INFO] Serving on http://127.0.0.1:8008 [INFO] Start watching changes [INFO] Start detecting changes
Sie werden sehen, dass jede Sprache alle Seiten hat. Einige Seiten sind jedoch nicht übersetzt und haben oben eine Info-Box, dass die Übersetzung noch fehlt.
Nehmen wir nun an, Sie möchten eine Übersetzung für den Abschnitt Features hinzufügen.
Kopieren Sie die Datei:
docs/en/docs/features.md
Fügen Sie sie an genau derselben Stelle ein, jedoch für die Sprache, die Sie übersetzen möchten, z. B.:
docs/es/docs/features.md
Tipp
Beachten Sie, dass die einzige Änderung in Pfad und Dateiname der Sprachcode ist, von en zu es.
Wenn Sie in Ihrem Browser nachsehen, werden Sie feststellen, dass die Dokumentation jetzt Ihren neuen Abschnitt anzeigt (die Info-Box oben ist verschwunden). 🎉
Jetzt können Sie alles übersetzen und beim Speichern sehen, wie es aussieht.
Nehmen wir an, Sie möchten Übersetzungen für eine Sprache hinzufügen, die noch nicht übersetzt ist, nicht einmal einige Seiten.
Angenommen, Sie möchten Übersetzungen für Kreolisch hinzufügen, diese sind jedoch noch nicht in den Dokumenten enthalten.
Wenn Sie den Link von oben überprüfen, lautet der Sprachcode für Kreolisch ht.
Der nächste Schritt besteht darin, das Skript auszuführen, um ein neues Übersetzungsverzeichnis zu erstellen:
fast →💬 Verwenden Sie das Kommando new-lang und fügen Sie den Sprach-Code als Argument hinten anpython ./scripts/docs.py new-lang ht Successfully initialized: docs/ht
Wie bereits oben erwähnt, können Sie ./scripts/docs.py mit dem Befehl live verwenden, um eine Vorschau der Ergebnisse anzuzeigen (oder mkdocs serve).
Sobald Sie fertig sind, können Sie auch alles so testen, wie es online aussehen würde, einschließlich aller anderen Sprachen.
Bauen Sie dazu zunächst die gesamte Dokumentation:
fast →💬 Verwenden Sie das Kommando „build-all“, das wird ein wenig dauernpython ./scripts/docs.py build-all Building docs for: en Building docs for: es Successfully built docs for: es
Dadurch werden alle diese unabhängigen MkDocs-Sites für jede Sprache erstellt, kombiniert und das endgültige Resultat unter ./site/ gespeichert.
Dieses können Sie dann mit dem Befehl serve bereitstellen:
fast →💬 Verwenden Sie das Kommando „serve“ nachdem Sie „build-all“ ausgeführt haben.python ./scripts/docs.py serve Warning: this is a very simple server. For development, use mkdocs serve instead. This is here only to preview a site with translations already built. Make sure you run the build-all command first. Serving at: http://127.0.0.1:8008
Übersetzen Sie nur die Markdown-Dokumente (.md). Übersetzen Sie nicht die Codebeispiele unter ./docs_src.
In Codeblöcken innerhalb des Markdown-Dokuments, übersetzen Sie Kommentare (# ein Kommentar), aber lassen Sie den Rest unverändert.
Ändern Sie nichts, was in "``" (Inline-Code) eingeschlossen ist.
In Zeilen, die mit === oder !!! beginnen, übersetzen Sie nur den "... Text ..."-Teil. Lassen Sie den Rest unverändert.
Sie können Info-Boxen wie !!! warning mit beispielsweise !!! warning "Achtung" übersetzen. Aber ändern Sie nicht das Wort direkt nach dem !!!, es bestimmt die Farbe der Info-Box.
Ändern Sie nicht die Pfade in Links zu Bildern, Codedateien, Markdown Dokumenten.
Wenn ein Markdown-Dokument übersetzt ist, ändern sich allerdings unter Umständen die #hash-teile in Links zu dessen Überschriften. Aktualisieren Sie diese Links, wenn möglich.
Suchen Sie im übersetzten Dokument nach solchen Links mit dem Regex #[^# ].
Suchen Sie in allen bereits in ihre Sprache übersetzen Dokumenten nach ihr-ubersetztes-dokument.md. VS Code hat beispielsweise eine Option „Bearbeiten“ -> „In Dateien suchen“.
Übersetzen Sie bei der Übersetzung eines Dokuments nicht „im Voraus“ #hash-teile, die zu Überschriften in noch nicht übersetzten Dokumenten verlinken.
Dieses Kommando generiert ein Verzeichnis ./htmlcov/. Wenn Sie die Datei ./htmlcov/index.html in Ihrem Browser öffnen, können Sie interaktiv die Codebereiche erkunden, die von den Tests abgedeckt werden, und feststellen, ob Bereiche fehlen.