Add LLM test file

2 days ago · b13a42c783
3 changed files with 438 additions and 2 deletions
--- a/docs/de/docs/_llm-test.md
+++ b/docs/de/docs/_llm-test.md
@ -0,0 +1,218 @@
 # LLM-Test { #llm-test }
 Dieses Dokument testet, ob das <abbr title="Large Language Model – Großes Sprachmodell">LLM</abbr> die Anweisungen im allgemeinen Prompt in `scripts/translate.py` und diejenigen im sprachspezifischen Prompt `docs/{language code}/llm-prompt.md` versteht (die an die Anweisungen im allgemeinen Prompt angehängt werden).
 Wie folgt verwenden:
 * Eine frische Übersetzung dieses Dokuments in die gewünschte Zielsprache erstellen. 
 * Prüfen, ob alles größtenteils in Ordnung ist. 
 * Wenn manches nicht in Ordnung ist, sich aber durch Verbesserungen am allgemeinen Prompt oder am sprachspezifischen Prompt beheben lässt, das tun.
 * Dann die verbleibenden Probleme in der Übersetzung manuell beheben, sodass es eine gute Übersetzung ist. 
 * Erneut übersetzen, wobei die existierende, gute Übersetzung verwendet wird. Das ideale Ergebnis wäre, dass das LLM gar keine Änderungen vornimmt. Das würde bedeuten, dass der allgemeine Prompt und der Sprach-Prompt so gut wie möglich sind. (Plot Twist: Es wird normalerweise ein paar scheinbar zufällige Änderungen machen, der Grund ist vermutlich, dass <a href="https://doublespeak.chat/#/handbook#deterministic-output" class="external-link" target="_blank">LLMs keine deterministischen Algorithmen sind</a>).
 Die Idee ist, dass Sie, wenn Sie an einer Übersetzung für eine Sprache arbeiten (unter der Annahme, dass Sie `scripts/translate.py` ausführen können), hier Beispiele gefundener Sonderfälle aufnehmen (keine detaillierte Liste, nur Beispiele für solche Sonderfälle) und mit diesem Dokument testen, statt jedes andere einzelne Dokument mehrfach zu testen und zu übersetzen, was pro Übersetzung ein paar Cent kostet. Außerdem werden durch das Hinzufügen solcher Sonderfälle hier auch andere Übersetzungsprojekte auf solche Sonderfälle aufmerksam.
 ## Codeschnipsel { #codesnippets}
 Dies ist ein Codeschnipsel: `foo`. Und dies ist ein weiteres Codeschnipsel: `bar`. Und noch eins: `baz quux`.
 ## Anführungszeichen { #quotes }
 Gestern schrieb mein Freund: „Wenn man falsch richtig buchstabiert, hat man es falsch buchstabiert“. Worauf ich antwortete: „Richtig, aber ‚falsch‘ ist fälschlich nicht ‚„falsch“‘“.
 ## Anführungszeichen in Codeschnipseln { #quotes-in-codesnippets}
 `pip install "foo[bar]"`
 Beispiele für Stringliterale in Codeschnipseln: `"this"`, `'that'`.
 Ein schwieriges Beispiel für Stringliterale in Codeschnipseln: `f"I like {'oranges' if orange else "apples"}"`
 Hardcore: `Yesterday my friend wrote: "If you spell incorrectly correctly you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'!"`
 ## Codeblöcke { #code-blocks }
 Ein Bash-Codebeispiel ...
 ```bash
 # Gruß an das Universum ausgeben
 echo "Hello universe"
 ```
 ... und ein Konsolen-Codebeispiel ...
 ```console
 $ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u>
 <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting server
        Searching for package file structure
 ```
 ... und noch ein Konsolen-Codebeispiel ...
 ```console
 // Erstellen Sie ein Verzeichnis "Code"
 $ mkdir code
 // Wechseln Sie in dieses Verzeichnis
 $ cd code
 ```
 ... und ein Python-Codebeispiel ...
 ```Python
 wont_work()  # Das wird nicht funktionieren 😱
 works(foo="bar")  # Das funktioniert 🎉
 ```
 ... und das war’s.
 ## Tabs und farbige Kästen { #tabs-and-colored-boxes }
 //// tab | Dies ist ein Tab
 /// info | Info
 Etwas Text
 ///
 /// note | Hinweis
 Etwas Text
 ///
 /// note | Technische Details
 Etwas Text
 ///
 /// check | Testen
 Etwas Text
 ///
 /// tip | Tipp
 Etwas Text
 ///
 /// warning | Achtung
 Etwas Text
 ///
 /// danger | Gefahr
 Etwas Text
 ///
 ////
 ## Web- und interne Links { #links }
 [Link zur Überschrift oben](#codesnippets)
 <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">Externer Link</a>
 <a href="https://fastapi.tiangolo.com/de/the/link/#target" class="external-link" target="_blank">FastAPI-Link</a>
 <a href="https://fastapi.tiangolo.com/css/styles.css" class="external-link" target="_blank">Link zu einem Stil</a>
 <a href="https://fastapi.tiangolo.com/js/logic.js" class="external-link" target="_blank">Link zu einem Skript</a>
 <a href="https://fastapi.tiangolo.com/img/foo.jpg" class="external-link" target="_blank">Link zu einem Bild</a>
 [Interner Link](foo.md#bar){.internal-link target=_blank}
 ## Abbr-Elemente { #abbr-elements }
 Hier einige Dinge, die in `abbr`-Elemente gehüllt sind (einige sind erfunden): <abbr title="Getting Things Done – Dinge erledigt bekommen">GTD</abbr>, <abbr title="XML-Web-Token">XWT</abbr>, <abbr title="Paralleles Server-Gateway-Interface">PSGI</abbr>, <abbr title="Eine Gruppe von Maschinen, die so konfiguriert sind, dass sie verbunden sind und in irgendeiner Weise zusammenarbeiten.">Cluster</abbr>, <abbr title="Eine Methode des maschinellen Lernens, die künstliche neuronale Netze mit zahlreichen verdeckten Schichten zwischen Eingabe- und Ausgabeschichten verwendet und dabei eine umfassende interne Struktur entwickelt">Deep Learning</abbr>, <abbr title="Mozilla Developer Network – Mozilla-Entwicklernetzwerk: Dokumentation für Entwickler, geschrieben von den Firefox-Leuten">MDN</abbr>.
 ## Überschriften { #headings }
 ### Eine Webapp entwickeln – ein Tutorial { #develop-a-webapp-a-tutorial }
 Hallo.
 ### Typhinweise und -annotationen { #type-hints-and-annotations }
 Hallo nochmal.
 ### Super- und Subklassen { #super-and-subclasses }
 Hallo nochmal.
 ## Sätze mit bevorzugten Übersetzungen (vielleicht) im Sprach-Prompt definiert { #sentences-with-preferred-translations-maybe-defined-in-the-language-prompt }
 Ich heiße Sie willkommen.
 Ich bewundere Ihren Pullover.
 Sie mag Obst, z. B. Äpfel
 Er mag Orangen, Bananen, usw.
 Lesen Sie die `PATH`-Umgebungsvariable.
 Was dasselbe ist wie der `PATH`.
 Installieren Sie aus der `requirements.txt`.
 Verwenden Sie den API-Router.
 Starten Sie die App.
 Erstellen Sie die Anwendung.
 Lesen Sie das Tutorial – Benutzerhandbuch.
 Lesen Sie dann das Handbuch für fortgeschrittene Benutzer.
 Dies ist der Autorisierungsheader.
 Dies ist der `Authorization`-Header.
 Warten auf den Hintergrundtask.
 Probieren Sie diesen Cloudanbieter.
 Verwenden Sie das CLI.
 Was das Kommandozeileninterface ist.
 Lesen Sie die Dokumentation.
 Der Defaultwert ist „foo“.
 Die Default-Deklaration ist „bar“.
 Die Engine wird das tun.
 Wenn die Umgebungsvariable existiert, tun Sie etwas.
 Eine Error-Response zurückgeben.
 Auf das Event warten.
 Die Exception auslösen.
 Der Exceptionhandler behandelt sie.
 Das Formularmodell definieren.
 Den Formularbody senden.
 Auf den Header zugreifen.
 Die Header ändern.
 Schreibweise in Headern.
 Auf das Lifespan-Event lauschen.
 Locking bedeutet, dass wir ein Lock setzen, um etwas sicher zu ändern.
 Eine Mobile-Anwendung entwickeln.
 Das Modellobjekt definieren.
 Etwas wartet auf das Mounten.
 Es ist jetzt gemountet.
 Ein weiteres Origin.
 Dafür haben wir eine Überschreibung.
 Die Funktion hat einen Parameter.
 Der Funktionsparameter ist ein int.
 Die Funktion hat viele Parameter.
 Der Defaultparameter ist ein bool.
 Der Body-Parameter enthält den Body des Requests.
 Auch der Requestbody-Parameter genannt.
 Der Pfad-Parameter enthält eine Variable im Requestpfad.
 Der Query-Parameter enthält die Query-Parameter im Requestpfad.
 Der Cookie-Parameter enthält die Request-Cookies.
 Der Header-Parameter enthält die Request-Header.
 Der Formular-Parameter enthält die Formularfelder des Requests.
 Die Payload ist der Request/die Response ohne Metadaten.
 Diese Query fragt nach Items, die älter als eine Woche sind.
 Zusammenfassung: Es ist smooth.
 Der Request wurde empfangen.
 Den Requestbody empfangen.
 Die Requestbodys empfangen.
 Die Response zurückgeben.
 Was eine Funktion zurückgibt, hat einen Rückgabewert.
 Und einen Rückgabetyp.
 Details sind in der SQLModel-Dokumentation beschrieben.
 Verwenden Sie das SDK.
 Der Tag `Horst` bedeutet, Horst muss es tun.
 Dieser Parameter hat eine Typannotation.
 Was ein Typhinweis ist.
 Die Wildcard ist `*`.
 Die Workerklasse macht dies und das.
 Der Workerprozess macht auch Dinge.
 Ich werde das morgen committen.
 Gestern habe ich den Code geändert.
 Lassen Sie uns unsere App bereitstellen.
 Lassen Sie uns diese Seite ausliefern.
 Aktualisieren Sie FastAPI, bevor Sie das tun.
 Dies ist in ein HTML-Tag gewrappt.
 `foo` vom Typ `int`.
 `bar` vom Typ `str`.
 `baz` vom Typ `list`.
 FastAPIs Dokumentation.
 Starlettes Performance.
 Groß-/Kleinschreibung ist relevant in `foo`.
 Groß-/Kleinschreibung ist nicht relevant in „Bar“.
 Standard-Python-Klassen.
 Dies ist deprecatet.
--- a/docs/en/docs/_llm-test.md
+++ b/docs/en/docs/_llm-test.md
@ -0,0 +1,218 @@
 # LLM test { #llm-test }
 This document tests if the <abbr title="Large Language Model">LLM</abbr> understands the instructions given in the general prompt in `scripts/translate.py` and those in the language specific prompt `docs/{language code}/llm-prompt.md`, (which are appended to the instructions in the general prompt).
 Use as follows:
 * Do a fresh translation of this document into the desired target language. 
 * Check if things are mostly okay. 
 * If some things are not okay, but are fixable by improving the general or the language specific prompt, do that.
 * Then manually fix the remaining issues in the translation, so that it is a good translation. 
 * Retranslate using the existing, good translation. The ideal result should be that the LLM makes no changes at all. That would mean that the general prompt and the language prompt are as good as they can be (Plot twist: It will usually make a few seemingly random changes, the reason is probably that <a href="https://doublespeak.chat/#/handbook#deterministic-output" class="external-link" target="_blank">LLMs are not deterministic algorithms</a>).
 The idea is, that, when working on a translation for a language (assumed one is able to run `scripts/translate.py`), to include examples of found special cases here (not a detailed list, just examples for such special cases) and test with this document, rather than testing with every other single document, translating it multiple times, which costs a few cents per translation. Also, by adding such special cases here, other translation projects will also become aware of such special cases.
 ## Code snippets { #codesnippets}
 This is a code snippet: `foo`. And this is another code snippet: `bar`. And another one: `baz quux`.
 ## Quotes { #quotes }
 Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'".
 ## Quotes in code snippets { #quotes-in-codesnippets}
 `pip install "foo[bar]"`
 Examples for string literals in code snippets: `"this"`, `'that'`.
 A difficult example for string literals in code snippets: `f"I like {'oranges' if orange else "apples"}"`
 Hardcore: `Yesterday my friend wrote: "If you spell incorrectly correctly you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'!"`
 ## code blocks { #code-blocks }
 A Bash code example...
 ```bash
 # Print a greeting to the universe
 echo "Hello universe"
 ```
 ...and a console code example...
 ```console
 $ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u>
 <span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span>  Starting server
        Searching for package file structure
 ```
 ...and another console code example...
 ```console
 // Create a directory "Code"
 $ mkdir code
 // Switch into that directory
 $ cd code
 ```
 ...and a Python code example...
 ```Python
 wont_work()  # This won't work 😱
 works(foo="bar")  # This works 🎉
 ```
 ...and that's it.
 ## Tabs and colored boxes { #tabs-and-colored-boxes }
 //// tab | This is a tab
 /// info
 Some text
 ///
 /// note
 Some text
 ///
 /// note | Technical details
 Some text
 ///
 /// check
 Some text
 ///
 /// tip
 Some text
 ///
 /// warning
 Some text
 ///
 /// danger
 Some text
 ///
 ////
 ## Web- and internal links { #links }
 [Link to heading above](#codesnippets)
 <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">External link</a>
 <a href="https://fastapi.tiangolo.com/the/link/#target" class="external-link" target="_blank">FastAPI link</a>
 <a href="https://fastapi.tiangolo.com/css/styles.css" class="external-link" target="_blank">Link to a style</a>
 <a href="https://fastapi.tiangolo.com/js/logic.js" class="external-link" target="_blank">Link to a script</a>
 <a href="https://fastapi.tiangolo.com/img/foo.jpg" class="external-link" target="_blank">Link to an image</a>
 [Internal link](foo.md#bar){.internal-link target=_blank}
 ## Abbr elements { #abbr-elements }
 Here some things wrapped in `abbr` elements (Some are invented): <abbr title="Getting Things Done">GTD</abbr>, <abbr title="XML Web Token">XWT</abbr>, <abbr title="Parallel Server Gateway Interface">PSGI</abbr>, <abbr title="A group of machines that are configured to be connected and work together in some way.">cluster</abbr>, <abbr title="A method of machine learning that uses artificial neural networks with numerous hidden layers between input and output layers, thereby developing a comprehensive internal structure">Deep Learning</abbr>, <abbr title="Mozilla Developer Network: Documentation for developers, written by the Firefox people">MDN</abbr>.
 ## Headings { #headings }
 ### Develop a webapp - a tutorial { #develop-a-webapp-a-tutorial }
 Hello.
 ### Type hints and -annotations { #type-hints-and-annotations }
 Hello again.
 ### Super- and subclasses { #super-and-subclasses }
 Hello again.
 ## Sentences with preferred translations, (maybe) defined in the language prompt { #sentences-with-preferred-translations-maybe-defined-in-the-language-prompt }
 I welcome you.
 I admire your pullover.
 She likes fruits e.g. apples
 He likes oranges, bananas, etc.
 Read the `PATH` environment variable.
 Which is the same as the `PATH`.
 Install from the `requirements.txt`.
 Use the API Router.
 Start the app.
 Create the application.
 Read the Tutorial - User guide.
 Then read the Advanced User Guide.
 This is the Authorization-Header.
 This is the `Authorization`-Header.
 Waiting for the background task.
 Try this cloud provider.
 Use the CLI.
 Which is the command line interface.
 Read the docs.
 The default value is "foo".
 The default declaration is "bar".
 The engine will do that.
 If the env var exists, do something.
 Return an error response.
 Wait for the event.
 Raise the exception.
 The exception handler handles it.
 Defining the form model.
 Sending the form body.
 Accessing the header.
 Modifying the headers.
 Spelling in headers.
 Listening to the lifespan event.
 Locking means, we lock a thing to safely modify it.
 Developing a mobile application.
 Defining the model object.
 Something waits for the mounting.
 It is now mounted.
 Another origin.
 We have an override for this.
 The function has one parameter.
 The function parameter is an int.
 The function has many parameters.
 The default parameter is a bool.
 The body parameter contains the body of the request.
 Also called the request body parameter.
 The path parameter contains a variable in the request path.
 The query parameter contains the query parameters in the request path.
 The cookie parameter contains the request cookies.
 The header parameter contains the request headers.
 The form parameter contains the request's form fields.
 The payload is the request/response without metadata.
 This query asks for items older than a week.
 Recap: It's smooth.
 The request has been received.
 Receiving the request body.
 Receiving the request bodies.
 Returning the response.
 What a function returns has a return value.
 And a return type.
 Details are described in the SQLModel docs.
 Use the SDK.
 The tag `Horst` means, Horst has to do it.
 This parameter has a type annotation.
 Which is a type hint.
 The wildcard is `*`.
 The worker class does this and that.
 The worker process also does things.
 I will commit this tomorrow.
 Yesterday I modified the code.
 Let's serve our app.
 Let's serve this page.
 Before doing this, upgrade FastAPI.
 This is wrapped in an HTML tag.
 `foo` as an `int`.
 `bar` as a `str`.
 `baz` as a `list`.
 FastAPI's documentation.
 Starlette's performance.
 `foo` is case-sensitive.
 "Bar" is case-insensitive.
 Standard Python classes.
 This is deprecated.
--- a/scripts/translate.py
+++ b/scripts/translate.py
@ -679,9 +679,9 @@ def translate_page(
        Path,
        typer.Option(
            envvar="EN_PATH",
-            help="Path to the English source, relative to the FastAPI root directory, e.g. `docs/en/docs/index.md`",
+            help="Path to the English source, relative to the FastAPI root directory. If not given, `docs/en/docs/_llm-test.md` is used.",
        ),
-    ],
+    ] = Path("docs/en/docs/_llm-test.md"),
 ) -> None:
    assert language != "en", (
        "`en` is the source language, choose another language as translation target"