Propose ÜBERSETZUNGEN.txt: shared glossary and entity reference

ÜBERSETZUNGEN.txt

@@ -0,0 +1,99 @@
+$Revision$
+
+Letzte Aktualisierung: 28. Mai 2026
+
+Zweck:
+  Diese Datei sammelt Übersetzungen wiederkehrender technischer Begriffe
+  und listet die Entitäten auf, die in der deutschen PHP-Dokumentation
+  bevorzugt verwendet werden, um die Konsistenz des Handbuchs zu wahren.
+
+Workflow für Übersetzungen:
+  - Datei aus en/ kopieren, dabei den XML-Aufbau Tag für Tag spiegeln.
+  - Im Header die Zeile <!-- EN-Revision: HASH Maintainer: NICK Status: ready -->
+    setzen, wobei HASH der letzte Commit des EN-Pendants ist und
+    NICK das eigene Kürzel.
+  - Bei der Übernahme einer bestehenden Datei (Maintainer-Wechsel) eine
+    Zeile <!-- CREDITS: <alter_maintainer> --> direkt nach EN-Revision
+    einfügen.
+  - Nur Dokumentationstext übersetzen. Variablen-, Funktions- und
+    Klassennamen sowie Code-Ausgaben (<screen>) bleiben unverändert;
+    Code-Kommentare im <programlisting> werden übersetzt.
+
+Stil:
+  - Der Stil der bestehenden Dateien wechselt zwischen "Sie" und
+    unpersönlicher Form. Für neue Übersetzungen ist die unpersönliche
+    Form vorzuziehen; "Sie" bleibt in Anweisungen akzeptabel.
+  - <refpurpose> wird kurz formuliert, mit einem Aktionsverb in der
+    3. Person: "Erzeugt ...", "Gibt ... zurück", "Prüft, ob ...".
+  - Funktions- und Klassennamen werden im Fließtext über <function> bzw.
+    <classname> ausgezeichnet, nicht über <literal>.
+
+Entitäten - bevorzugt anstelle ausgeschriebener Wendungen verwenden:
+
+  Verlinkte Typen:
+   - &array;     (statt "Array")
+   - &boolean;   (statt "Boolean")
+   - &float;     (statt "Float")
+   - &integer;   (statt "Integer")
+   - &string;    (statt "String")
+
+  PHP-Schlüsselwörter:
+   - &true;
+   - &false;
+   - &null;
+
+  Abkürzungen mit geschütztem Leerzeichen:
+   - &zb;        Statt "z. B." (verhindert den Zeilenumbruch nach "z.")
+
+  Wiederkehrende Rückgabewert-Idiome:
+   - &return.falseforfailure;   "Bei einem Fehler wird &false; zurückgegeben."
+   - &return.success;           "Gibt bei Erfolg &true; zurück. &return.falseforfailure;"
+   - &return.nullorfalse;       "Gibt bei Erfolg &null; zurück. &return.falseforfailure;"
+   - &return.void;              "Es wird kein Wert zurückgegeben."
+   - &return.true.always;       "Gibt immer &true; zurück."
+
+  Abschnittstitel:
+   - &reftitle.description;
+   - &reftitle.parameters;
+   - &reftitle.returnvalues;
+   - &reftitle.errors;
+   - &reftitle.changelog;
+   - &reftitle.examples;
+   - &reftitle.notes;
+   - &reftitle.seealso;
+
+Glossar - aus dem aktuellen Bestand abgeleitet:
+
+  _________________________________________________________________
+  |                               |                               |
+  |     Englischer Begriff        |       Deutsche Entsprechung   |
+  |_______________________________|_______________________________|
+  | array                         | &array; (Entität)             |
+  | bool / boolean                | &boolean; oder bool           |
+  | callable                      | callable (unverändert)        |
+  | callback function             | Callback-Funktion             |
+  | closure                       | Closure (unverändert)         |
+  | exception                     | Exception (unverändert)       |
+  | exception thrown              | Exception ausgelöst           |
+  | handle                        | Handle (unverändert)          |
+  | hash (value)                  | Hash, Hashwert                |
+  | header                        | Header (unverändert)          |
+  | key (array)                   | Schlüssel                     |
+  | library                       | Bibliothek                    |
+  | namespace                     | Namespace (unverändert)       |
+  | regular expression            | regulärer Ausdruck            |
+  | resource                      | Ressource                     |
+  | scope                         | Geltungsbereich               |
+  | string                        | Zeichenkette                  |
+  | value (array)                 | Wert                          |
+  | wrapper                       | Wrapper (unverändert)         |
+  |_______________________________|_______________________________|
+
+Hinweise:
+  - "unverändert" bedeutet, dass der englische Begriff im Deutschen
+    übernommen wird, weil keine etablierte und gebräuchliche deutsche
+    Entsprechung existiert.
+  - Bei neuen Begriffen, die hier nicht aufgeführt sind, bitte vor einer
+    eigenen Übersetzung den vorhandenen Bestand prüfen
+    ("git grep" im Verzeichnis reference/), um die bereits etablierte
+    Form zu übernehmen.