Bearbeiten

Einen Key bearbeitenLink zu diesem Abschnitt kopieren

editEntryLink zu diesem Abschnitt kopieren

Schreibt eine von Hand getippte Korrektur für einen Key und eine Locale. Der Kandidatenwert durchläuft dasselbe Integritäts-Gate wie eine Provider-Übersetzung, bevor irgendetwas die Platte erreicht; bei Annahme werden die Locale-Datei und der Lock-Eintrag für diesen Key innerhalb der Schreibsperre dieser Locale aktualisiert. Ruft nie einen Provider auf.

function editEntry(
  input: EditEntryInput,
  deps?: EditEntryDeps,
): Promise<EditEntryResult>;

Rückgabe: EditEntryResult

Wirft: UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, UNKNOWN_KEY, KEY_PINNED, LOCK_CONTENDED, RUN_CANCELLED, TARGET_UNWRITABLE, LOCALE_STATE_NOT_CARRIED_OVER, LOCK_TIMEOUT_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Beispiel: Einen einzelnen Key bearbeiten und neu übersetzen

Gibt { accepted: true, value } zurück oder { accepted: false, reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty", value }, wobei nichts geschrieben wird (das Integritäts-Gate). Baue jedes Schema über die Gründe aus dem exportierten Tupel INTEGRITY_GATE_REASONS. "empty" lehnt einen leeren Wert für eine Quelle mit Text ab; leere einen Key stattdessen mit dem [[CLEAR]]-Sentinel der Arbeitsmappe. Eine placeholder- oder markup-Ablehnung trägt zusätzlich details: jeden betroffenen Platzhalter oder Tag, mit -, wenn der Kandidat ihn weggelassen, oder +, wenn er ihn erfunden hat.

Der Wert wird in verbatra.provenance.json mit der Herkunft human festgehalten; übergib actor: "agent", wenn ein KI-Agent ihn geschrieben hat, damit der Eintrag das sagt (der Aufrufer behauptet es, geprüft wird es nicht); jeder andere actor wirft einen TypeError, bevor etwas gelesen wird. Eine beschädigte Herkunftsdatei wirft PROVENANCE_FILE_INVALID, bevor der Wert das Gate durchläuft, und nichts wird geschrieben; eine von einem neueren verbatra, oder eine, die der Eintrag über die Größe wachsen ließe, die verbatra zurückliest, bleibt unangetastet und der Wert wird ohne Eintrag geschrieben.

Mit actor: "agent" wirft ein Key, der auf die pinnedKeys der Konfiguration passt, KEY_PINNED, bevor etwas geschrieben wird. Die Bearbeitung eines gepinnten Keys durch einen Menschen wird angenommen.

lockAcquireTimeoutMs begrenzt die Wartezeit auf die Schreibsperre der Locale, bevor der Aufruf mit LOCK_CONTENDED scheitert (standardmäßig zehn Minuten), onLockWait meldet diese Wartezeit, und eine ungültige Grenze scheitert mit LOCK_TIMEOUT_INVALID, bevor etwas gelesen wird.

Über Locales hinweg ersetzenLink zu diesem Abschnitt kopieren

Ein wörtliches Suchen und Ersetzen über die Werte deiner Ziel-Locales, in zwei Schritten. previewValueReplace listet auf, was sich ändern würde und warum manche Werte sich nicht ändern würden. applyValueReplace ändert die Werte, die du auswählst, und entscheidet jeden davon unter der Schreibsperre noch einmal. Keine der beiden liest die Quell-Locale nach Treffern, und keine ruft einen Provider auf.

previewValueReplaceLink zu diesem Abschnitt kopieren

Listet die Zielwerte auf, die find enthalten, mit einem Status je Wert. Der Abgleich ist wörtlich: keine Muster-Syntax, keine Unicode-Normalisierung (ein NFD-find trifft keinen NFC-Wert) und keine Umrechnung von Zeilenenden. replace wird so eingefügt, wie du es schreibst, $& und $1 haben also keine besondere Bedeutung. caseSensitive ist standardmäßig true. Ein Treffer beginnt oder endet nie mitten in einem Surrogatpaar, und ein leeres find, eines über 20.000 Zeichen oder ein find oder replace mit einem einzelnen Surrogat ohne Partner wirft FIND_TEXT_INVALID. Nur lesend.

function previewValueReplace(
  input: PreviewValueReplaceInput,
  deps?: ValueReplaceDeps,
): Promise<ValueReplacePreview>;

Rückgabe: ValueReplacePreview

Wirft: FIND_TEXT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID

Jeder Eintrag hat genau einen Status. ready und stale-source lassen sich anwenden; stale-source markiert einen Key, dessen Quelltext sich geändert hat, seit seine Übersetzung festgehalten wurde. gate-refused trägt den reason, den der ersetzte Wert verletzt: Er wird gegen den aktuellen Quelltext am selben Integritäts-Gate gemessen wie eine Bearbeitung. Bei den ICU-Formaten (next-intl und ARB) wird eine Ersetzung außerdem mit dem Grund icu abgelehnt, wenn sie ändert, was ein Argument tut: seinen Typ, einen Zahlen- oder Datumsstil oder ein Skeleton oder die Anzahl der # in einem Plural-Zweig, verglichen mit dem aktuellen Wert oder mit dem Quelltext, wenn der aktuelle Wert kein gültiges ICU ist. Ein Argument, das vom Quelltext weg umbenannt wird, wird als placeholder abgelehnt. details nennen jeden Unterschied, - für den verglichenen und + für den ersetzten Wert. too-long ist ein Wert, der über 20.000 Zeichen wüchse; das ist keine Integritätsablehnung und hat keinen reason. pinned ist ein Key, der auf pinnedKeys passt. protected ist ein Wert, den ein Mensch geschrieben oder importiert hat, ein außerhalb von verbatra geänderter Wert oder jeder Wert, wenn die Herkunftsdatei nicht gelesen werden kann, auch eine Datei einer neueren verbatra-Version; das gilt unabhängig von humanEdits. Ein Key, der beides ist, steht als pinned mit protected: true in der Liste und braucht includePinned und includeProtected. no-source-entry ist ein Key ohne Quelltext zum Abgleichen, und unchanged ist ein Wert, den die Ersetzung so lässt, wie er ist.

Höchstens 1.000 Werte werden aufgelistet, in der Reihenfolge der targetLocales der Konfiguration, egal in welcher Reihenfolge locales sie nennt. truncated sagt, wenn mehr getroffen haben, und before und after sind auf 200 Zeichen um den ersten Treffer gekürzt. valueHash ist der Hash, den der Herkunftseintrag für den aktuellen Wert speichert; gib ihn an applyValueReplace zurück. baselineUnavailable: true sagt, dass die Lock-Datei nicht gelesen werden konnte; dann wurde kein Wert mit seinem festgehaltenen Quelltext verglichen, und keiner ist stale-source.

applyValueReplaceLink zu diesem Abschnitt kopieren

Ersetzt find in den Werten, die du ausgewählt hast, und berechnet jeden neuen Wert unter der Schreibsperre der Locale aus dem Text auf der Platte neu. Sie übernimmt nie einen berechneten Wert vom Aufrufer, und die Vorschau ist nur beratend: Jeder Eintrag wird noch einmal entschieden.

function applyValueReplace(
  input: ApplyValueReplaceInput,
  deps?: ValueReplaceDeps,
): Promise<ApplyValueReplaceResult>;

Rückgabe: ApplyValueReplaceResult

Wirft: FIND_TEXT_INVALID, UNKNOWN_FORMAT, UNKNOWN_LOCALE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, LOCK_TIMEOUT_INVALID, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Jeder Eintrag endet als applied, skipped (mit Grund), refused (mit dem Integritätsgrund), changed oder too-long. changed heißt: Der Wert passt nicht mehr zu seinem valueHash, enthält find nicht mehr oder ist verschwunden, und für ihn wurde nichts geschrieben. Der Hash ignoriert Unicode-Normalisierung und Zeilenenden; ein Wert, der sich von der Vorschau nur so unterscheidet, wird ersetzt, wenn find noch passt, und ist changed, wenn nicht. Ein gepinnter Key wird übersprungen, außer includePinned ist gesetzt und actor ist human, und ein geschützter Wert wird übersprungen, außer includeProtected ist gesetzt; ein Key, der beides ist, braucht beides. Bei einer Herkunftsdatei einer neueren verbatra-Version gilt jeder Wert als geschützt; includeProtected ändert ihn trotzdem, aber die Datei bleibt unberührt und der Wert bekommt keinen Eintrag. Kommen dieselben locale und key mehrfach vor, entscheidet der erste, egal welchen valueHash er trägt, und jeder spätere wird als duplicate-entry übersprungen.

Die Locales werden nacheinander verarbeitet, in der Reihenfolge, in der sie in entries zuerst vorkommen, jede unter ihrer eigenen Sperre, mit einem Schreibvorgang für die Locale-Datei, einer Aktualisierung von Lock-Datei und Herkunftsdatei und einer Aktualisierung des Übersetzungsspeichers. Ein veralteter Key behält seinen alten Lock-Hash, check meldet ihn also weiter als veraltet, und sein Wert kommt nicht in den Übersetzungsspeicher. Jeder geschriebene Wert bekommt einen neuen Herkunftseintrag mit actor als Herkunft und ohne Review-Entscheidung. actor ist Pflicht, und ein anderer Wert als human oder agent wirft einen TypeError, bevor etwas gelesen wird.

Eine Locale, die scheitert, hält die anderen nicht auf. localeFailures listet jede mit code und message, etwa LOCK_CONTENDED, wenn ihre Schreibsperre nicht innerhalb von lockAcquireTimeoutMs frei wird, TARGET_UNWRITABLE, SOURCE_INVALID oder ein Adapter-Fehler. Ein Eintrag, den das Integritäts-Gate abgelehnt hat, kommt weiterhin als refused zurück, und einer, den eine Prüfung vor dem Fehler entschieden hatte, behält sein Ergebnis; die übrigen werden als locale-failed übersprungen, und für sie wurde nichts geschrieben. Trägt der Fehler fileWritten: true, kam er, nachdem die Locale-Datei geschrieben war, beim Aktualisieren der Lock-Datei oder der Herkunftsdatei oder beim Freigeben der Schreibsperre: Die angenommenen Einträge sind applied, ihre Werte stehen auf der Platte, und Lock oder Herkunft können hinterherhinken; prüfe die Locale also, bevor du es erneut versuchst. Führe keine Ersetzung noch einmal aus, deren find in ihrem replace vorkommt, ohne das zu prüfen. Das Warten auf den eigenen Guard der Lock-Datei nutzt den Standard von zehn Minuten, nicht lockAcquireTimeoutMs.