Übergabe und Austausch

Locale-Datei-SchnappschüsseLink zu diesem Abschnitt kopieren

Die Bausteine eines Live-Refresh-Watchers wie dem von Studio: den Zustand einer Locale-Datei erfassen und dann zählen, was sich seitdem geändert hat.

readLocaleFileSnapshot Verfügbar ab 0.5.0Link zu diesem Abschnitt kopieren

Liest eine Locale-Datei (die Quell-Locale oder eine beliebige Ziel-Locale) und reduziert sie auf einen Inhalts-Hash pro Key. Eine noch nicht existierende Datei liest sich als leerer Schnappschuss, statt zu werfen.

function readLocaleFileSnapshot(
  input: ReadLocaleFileSnapshotInput,
  deps?: ReadLocaleFileSnapshotDeps,
): Promise<LocaleFileSnapshot>;

Rückgabe: LocaleFileSnapshot

Wirft: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION

Gibt { locale, hashes } zurück.

diffLocaleSnapshots Verfügbar ab 0.5.0Link zu diesem Abschnitt kopieren

Vergleicht zwei Schnappschüsse derselben Datei zu verschiedenen Zeitpunkten und zählt die zwischen ihnen hinzugefügten, geänderten und entfernten Keys. Eine schlichte synchrone Funktion: diffLocaleSnapshots(previous, current) gibt { added, changed, removed } zurück. Nur Zähler, nie Key-Namen.

function diffLocaleSnapshots(
  previous: LocaleFileSnapshot,
  current: LocaleFileSnapshot,
): LocaleSnapshotDelta;

Rückgabe: LocaleSnapshotDelta

Locale-PfadeLink zu diesem Abschnitt kopieren

createLocalePathResolver Verfügbar ab 0.7.0Link zu diesem Abschnitt kopieren

Löst die Locale-zu-Pfad-Zuordnung des Projekts in beide Richtungen auf, aus files.pattern, den konfigurierten Locales und files.localeStyle. createLocalePathResolver(cwd, config) liefert { pathFor, localeFor }: pathFor(locale) ist der absolute Pfad der Datei einer Locale, und localeFor(path) ist die Locale, zu der ein Pfad gehört, oder undefined für einen Pfad, der nicht zu diesem Projekt gehört, und bei einem Format mit gemeinsamem Katalog wie apple-xcstrings immer undefined. Jeder SDK-Einstiegspunkt löst Pfade darüber auf, sodass ein Watcher oder ein Dashboard auf Basis des SDK genau die Pfade sieht, die ein Lauf schreibt.

function createLocalePathResolver(
  cwd: string,
  config: LocalePathResolverConfig,
): LocalePathResolver;

Rückgabe: LocalePathResolver

Wirft: LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION

Alle Prüfungen laufen beim Erzeugen des Resolvers, bevor eine Datei gelesen wird: ein Pattern und ein Style, die sich nicht kombinieren lassen, oder eine Locale, für die der Style keine korrekte Schreibweise hat, werfen LOCALE_LAYOUT_INVALID; zwei Locales, die auf denselben Pfad auflösen, werfen LOCALE_PATH_COLLISION.

Das Arbeitsmappen-PaarLink zu diesem Abschnitt kopieren

Die Übergabe für menschliche Übersetzerinnen, als Excel-Arbeitsmappe oder als Text mit Trennzeichen; siehe Menschliche Übersetzung.

exportWorkbook Verfügbar ab 0.2.0Link zu diesem Abschnitt kopieren

Schreibt die noch zu übersetzenden Strings (fehlende und geänderte Keys pro Locale; unveränderte kommen mit includeUnchanged dazu) in eine formatierte .xlsx-Arbeitsmappe. Die Zeilen tragen dasselbe Review-Flag-Signal, das ein translate-Lauf berechnet. Kein Provider-Aufruf, kein Lock-Schreiben.

function exportWorkbook(
  input: ExportWorkbookInput,
  deps?: ExportWorkbookDeps,
): Promise<ExportWorkbookResult>;

Rückgabe: ExportWorkbookResult

Wirft: UNKNOWN_FORMAT, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, SOURCE_UNREADABLE, SOURCE_INVALID, LOCK_FILE_INVALID, UNKNOWN_LOCALE, EXPORT_OUTPUT_CONFLICT, EXPORT_UNWRITABLE

Beispiel: Der Arbeitsmappen-Roundtrip

format ist standardmäßig xlsx; csv und tsv schreiben stattdessen eine <locale>.csv bzw. <locale>.tsv pro Locale, out benennt dafür also ein Verzeichnis (das angelegt wird, falls es fehlt) und bei xlsx einen Dateipfad. out ist standardmäßig DEFAULT_WORKBOOK_PATH (verbatra-translations.xlsx) oder, bei den Getrennt- und XLIFF-Formaten, DEFAULT_DELIMITED_PATH (verbatra-translations), beide als Konstanten exportiert. Die zulässigen Werte werden als EXCHANGE_FORMATS und der Standardwert als DEFAULT_EXCHANGE_FORMAT exportiert, damit ein Werkzeug, das als Wrapper über dem SDK sitzt, ein Format-Argument prüfen kann, ohne die Liste fest zu verdrahten. Gibt { path, locales } zurück: den absoluten geschriebenen Pfad und eine Zeilenzahl pro Locale.

Bevor irgendetwas gelesen wird, weist EXPORT_OUTPUT_CONFLICT ein out zurück, das außerhalb von cwd landet, und eines, das selbst oder über eine Datei, die der Export hineinschreiben würde, eine konfigurierte Locale-Datei, die Lock-Datei, die Herkunftsdatei, den Übersetzungsspeicher-Cache, eine Datei, nach der verbatra seine Konfiguration sucht, die configPath-Datei oder die glossaryPath-Datei benennt, ohne Beachtung der Groß- und Kleinschreibung und, wenn deps.fs realpath implementiert wie die Voreinstellung, noch einmal nach dem Auflösen symbolischer Links. Ein xlsx-Pfad wird außerdem abgelehnt, wenn er keine Datei benennt (auch einer, der auf ein Pfadtrennzeichen endet) oder cwd selbst benennt; ein csv-, tsv- oder XLIFF-Verzeichnis darf cwd sein. Scheitert das Schreiben, weil das Verzeichnis nicht schreibbar ist, ein Verzeichnis oder eine Datei im Weg liegt oder die Platte voll ist, wirft es EXPORT_UNWRITABLE mit der Datei und dem Dateisystem-Code in der Message und dem Dateisystem-Fehler als cause.

format: "xliff2" und format: "xliff12" schreiben für ein CAT-Tool eine XLIFF-2.0- bzw. 1.2-Datei <locale>.xlf pro Locale in das Verzeichnis out: eine Unit pro Key, Platzhalter und Markup als geschützte <ph>-Inline-Codes, Beschreibung und Bedeutung des Keys als Notizen, den Quell-Hash in den Metadaten der Unit und einen Segmentstatus aus dem Lock- und Review-Status (initial für einen fehlenden oder veralteten Key, translated wenn aktuell, reviewed wenn freigegeben). Beide Typen werden exportiert, XliffFormat benennt die zwei XLIFF-Mitglieder von ExchangeFormat. Siehe An eine Übersetzungsagentur übergeben.

Jede Unit mit einem Ziel trägt außerdem ihre Herkunft: XLIFF 1.2 kennzeichnet ein nicht freigegebenes Ziel der maschinellen Klasse mit state-qualifier="mt-suggestion", und XLIFF 2.0 ergänzt die verbatra-Metagruppe der Unit um die Einträge origin und review-state. Das Ergebnis trägt dann auch provenanceMarkers: "written", oder "unavailable", wenn sich die Herkunftsdatei nicht lesen ließ und keine Markierung geschrieben wurde. Siehe Nachweis maschineller Übersetzungen.

importWorkbook Verfügbar ab 0.2.0Link zu diesem Abschnitt kopieren

Liest eine ausgefüllte Arbeitsmappe zurück in die Locale-Dateien und führt dieselben Prüfungen auf Quelldrift und Integrität aus wie translate. Nur akzeptierte Zeilen rücken ihre Lock-Baseline vor; eine leere oder abgelehnte Zeile wird weiter exportiert, bis sie wirklich erledigt ist.

function importWorkbook(
  input: ImportWorkbookInput,
  deps?: ImportWorkbookDeps,
): Promise<RunSummary>;

Rückgabe: RunSummary

Wirft: LOCK_TIMEOUT_INVALID, REVIEWER_INVALID, UNKNOWN_FORMAT, SOURCE_UNREADABLE, SOURCE_INVALID, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, LOCK_FILE_INVALID, PROVENANCE_FILE_INVALID

Beispiel: Der Arbeitsmappen-Roundtrip

Bei csv und tsv ist workbook entweder eine einzelne Übergabedatei oder das Verzeichnis mit einer Datei pro Locale, und die Locale kommt aus dem Dateinamen. Eine Datei auf .csv oder .tsv wird ohne format in diesem Format gelesen, ein Verzeichnis im Format seines Export-Manifests oder seiner Locale-Dateien. Gibt dieselbe RunSummary-Form zurück wie translate (mit needsReview immer leer, da kein Provider beteiligt ist). Ein Blatt für eine Locale, die kein konfiguriertes Ziel ist, lässt diese Locale mit CONFIG_INVALID als Daten auf der Zusammenfassung fehlschlagen, statt zu werfen.

onLockWait und lockAcquireTimeoutMs verhalten sich genau wie bei translate. lockAcquireTimeoutMs begrenzt das Warten auf die Schreibsperre einer Locale, die genommen wird, bevor die Datei dieser Locale geschrieben wird. Eine Locale, deren Sperre danach noch belegt ist, schlägt mit LOCK_CONTENDED auf ihrer eigenen Zusammenfassung fehl, während die anderen Locales importiert werden. Das Eintragen einer geschriebenen Datei in die Lock-Datei wartet immer bis zum Standard von zehn Minuten. Ein Dry-Run nimmt keine Sperre, daher gilt keine der beiden Optionen für ihn.

integrityRefusals jeder Locale nennt die Zeilen, die das Integritäts-Gate abgelehnt hat, mit dem Grund und seinen details, etwa jedem ICU-Zweig, der nicht zur Zielsprache passt. Eine Zeile, die zurückgehalten wurde, weil sich ihre Quelle seit dem Export geändert hat, steht nur in integrityMismatches. exportWorkbook markiert eine aktuelle Übersetzung mit falschen Zweigen in den Review-Spalten als icu-arms.

Mit xliff2 oder xliff12, die beide jede Version lesen, und standardmäßig bei einem workbook-Pfad auf .xlf oder .xliff wird jeder Inline-Code vor denselben Prüfungen in seinen exakten Text zurückgeführt. Ein Ziel, das dem aktuellen Wert entspricht, ändert nichts, eine Unit, deren ID keinen Quell-Key nennt, erscheint in malformedRows, und eine Unit im Status reviewed oder final (1.2: signed-off, final oder approved="yes") wird in der Herkunftsdatei als freigegeben festgehalten, mit reviewer als Namen, wenn angegeben (geprüft wie bei approveEntry, REVIEWER_INVALID), und mit dem Hinweis HANDOFF_REVIEWS_RECORDED gemeldet.

Das TMX-Paar Verfügbar ab 0.11.0Link zu diesem Abschnitt kopieren

importTmx und exportTmx bewegen den Übersetzungsspeicher in TMX hinein und wieder heraus, also in das Austauschformat, das die gängigen Übersetzungsplattformen erzeugen und lesen. Keine der beiden Funktionen konstruiert einen Provider, liest einen API-Key oder stellt eine Netzwerkanfrage: jeder Wert kommt aus der Datei oder aus dem Übersetzungsspeicher, der ohnehin schon auf der Platte liegt. Das ist nicht das Arbeitsmappen-Paar in einem anderen Format. Das Arbeitsmappen-Paar übergibt einer Übersetzerin einen Ausschnitt des offenen Deltas pro Locale; dieses Paar bewegt den ganzen Übersetzungsspeicher als eine mehrsprachige Datei zwischen Werkzeugen.

importTmxLink zu diesem Abschnitt kopieren

Liest eine TMX-Datei in den Übersetzungsspeicher des Projekts.

function importTmx(
  input: ImportTmxInput,
  deps?: ImportTmxDeps,
): Promise<ImportTmxResult>;

Rückgabe: ImportTmxResult

Wirft: UNKNOWN_FORMAT, CONFIG_INVALID, UNKNOWN_LOCALE, SOURCE_UNREADABLE, SOURCE_INVALID, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION, MEMORY_UNWRITABLE

Beispiel: Der TMX-Roundtrip

Nichts aus der Datei gilt als vertrauenswürdig. Das XML wird unter der Härtung des Interchange-Pakets geparst, sodass eine Entity-Deklaration, ein internes DTD-Subset, eine zu große oder eine fehlerhafte Datei mit einem strukturierten SOURCE_INVALID-Fehler abgelehnt statt geparst wird. Hat das Problem einen Ort in der Datei, nennt die Meldung Zeile, Spalte und, innerhalb einer Übersetzungseinheit, deren Ordnungszahl ab 1, und tmxErrorLocation(error) liefert denselben Ort als TmxErrorLocation, bei jedem anderen Fehler undefined, sodass du weder den Fehler noch seinen cause casten musst. Ein Sprach-Tag wird nach einer ausdrücklichen Regel einer konfigurierten Locale zugeordnet: exakte Schreibweise nach Kleinschreibung und Faltung von Unterstrichen zu Bindestrichen; sonst die längste konfigurierte Locale, die ein Subtag-Präfix des Tags ist (Lookup nach RFC 4647), oder andernfalls eine konfigurierte Locale, die das Tag nur um Regions- oder Varianten-Subtags erweitert, nie um eine Schrift, sodass zwei Tags mit unterschiedlichen Schrift- oder Regions-Subtags (sr-Latn und sr-Cyrl, de-AT und de-CH) nie zusammenpassen; und ein Tag wird nur dann als mehrdeutig gemeldet, wenn die Locales, die es erreichen könnte, nicht auf einer Präfix-Kette liegen. Segmente einer Einheit, die auf dieselbe Locale auflösen, die Quell-Locale eingeschlossen, lassen nie das letzte gewinnen: Ein exaktes Tag schlägt einen Präfix-Treffer, und zwei gleichrangige Segmente mit unterschiedlichen Werten speichern für diese Locale nichts und werden als conflicting gezählt (bei der Quell-Locale wird die Einheit abgelehnt und in conflictingSourceUnits gezählt). Jeder Übersetzungskandidat durchläuft dann dasselbe Gate für Platzhalter, Inline-Markup, ICU, Degeneriertheit und Leere, dem Provider-Ausgabe und eine ausgefüllte Arbeitsmappenzeile schon unterliegen, geprüft beim Eintritt in den Übersetzungsspeicher, statt dem Lauf überlassen zu werden, der ihn später liest.

Widerspricht eine importierte Einheit einer Übersetzung, die der Übersetzungsspeicher schon hat, gewinnt der Übersetzungsspeicher, sofern overwrite nicht gesetzt ist. Einheiten werden unter dem aktuellen Konfigurations-Fingerprint gespeichert, demselben Key, den ein echter Lauf schreibt, und hören deshalb auf zu passen, sobald sich Provider, Modell, Tonfall, die Glossarbegriffe, die verbatra senden würde, oder das localeMap des Providers ändern. Dieselbe Datei ein zweites Mal zu importieren ändert nichts.

Gibt bei beschädigten Daten einen Bericht zurück, statt zu werfen: wie viele Einheiten gelesen wurden, eine Abrechnung pro Locale über added, unchanged, overwritten, kept, duplicates, conflicting und rejected nach Grund, dazu die Einheiten, die übersprungen wurden, kein Quellsegment hatten, Inline-Markup verloren oder deren sub-Text weggelassen wurde (subflowDroppedUnits), sowie die Sprach-Tags, die zu nichts passten oder mehrdeutig passten. memoryWritable ist false, wenn die Datei des Übersetzungsspeichers von einem neueren verbatra geschrieben wurde; sie bleibt dann unangetastet. Die Zählungen pro Locale werden trotzdem gemeldet, wie bei einem Probelauf, sodass added und overwritten beschreiben, was gelandet wäre; bei memoryWritable false ist nichts gelandet.

Jede Locale listet außerdem ihre refusals, ein TmxUnitRefusal pro Einheit, die unter einem Gate-Grund gezählt wurde: { unit, reason, details? }, wobei unit die 1-basierte Position der Einheit in der Datei ist und details nennt, was falsch ist, etwa jeden ICU-Zweig, der nicht zur Zielsprache passt.

tmxErrorLocationLink zu diesem Abschnitt kopieren

Liest aus dem, was importTmx geworfen hat, wo eine abgelehnte TMX-Datei schiefging. Gibt für eine SOURCE_INVALID-Ablehnung mit einem Ort in der Datei eine TmxErrorLocation zurück ({ line, column, unit? }, alle ab 1 gezählt) und bei jedem anderen Fehler undefined, auch bei einer fehlenden oder zu großen Datei, sodass du weder den Fehler noch seinen cause casten musst.

function tmxErrorLocation(
  error: unknown,
): TmxErrorLocation | undefined;

Rückgabe: TmxErrorLocation | undefined

import { importTmx, tmxErrorLocation, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

try {
  await importTmx({ config, file: "legacy.tmx" });
} catch (error) {
  const at = tmxErrorLocation(error);
  if (at !== undefined) console.error(`line ${at.line}, column ${at.column}`);
}

exportTmxLink zu diesem Abschnitt kopieren

Schreibt den Übersetzungsspeicher als TMX 1.4b heraus. out fällt auf DEFAULT_TMX_PATH (verbatra-memory.tmx) zurück, das als Konstante exportiert wird. Bevor der Übersetzungsspeicher gelesen wird, weist TMX_OUTPUT_CONFLICT ein out zurück, das keine Datei benennt (auch eines, das auf ein Pfadtrennzeichen endet), außerhalb von cwd oder auf cwd selbst landet oder eine konfigurierte Locale-Datei, die Lock-Datei, die Herkunftsdatei, den Übersetzungsspeicher-Cache, eine Datei, nach der verbatra seine Konfiguration sucht, die configPath-Datei oder die glossaryPath-Datei benennt, ohne Beachtung der Groß- und Kleinschreibung und, wenn deps.fs realpath implementiert wie die Voreinstellung, noch einmal nach dem Auflösen symbolischer Links. Scheitert das Schreiben, weil das Verzeichnis nicht schreibbar ist, an dem Pfad ein Verzeichnis liegt oder die Platte voll ist, wirft es TMX_UNWRITABLE mit der Datei und dem Dateisystem-Code in der Message. Geschrieben werden nur Einträge unter dem aktuellen Konfigurations-Fingerprint, also dieselbe Menge, die ein Lauf wiederverwenden würde. Sprach-Tags werden in BCP-47-Form geschrieben (en_US wird zu en-US), was nichts daran ändert, woraus der Key des Übersetzungsspeichers gebildet wird. Ein leerer Übersetzungsspeicher ergibt eine gültige, leere Datei statt eines Fehlers.

function exportTmx(
  input: ExportTmxInput,
  deps?: ExportTmxDeps,
): Promise<ExportTmxResult>;

Rückgabe: ExportTmxResult

Wirft: UNKNOWN_LOCALE, CONFIG_INVALID, TMX_OUTPUT_CONFLICT, TMX_UNWRITABLE, LOCALE_LAYOUT_INVALID, LOCALE_PATH_COLLISION

Beispiel: Der TMX-Roundtrip

Gibt { path, units, locales, withoutSource, illegalCharactersRemoved, provenanceMarkers } zurück; withoutSource zählt Einträge, die ausgelassen wurden, weil der Übersetzungsspeicher keinen Quelltext zu ihnen hat, was nur bei Einträgen aus einem Cache passiert, der noch vor dem Speichern des Quelltexts geschrieben wurde, und illegalCharactersRemoved zählt die Zeichen, die XML 1.0 nicht darstellen kann und die aus dem Segmenttext entfernt wurden.

Jedes Zielsegment trägt <prop type="x-origin"> (machine, human, import oder unknown, der Typ TmxOrigin) und ein machine-Segment zusätzlich <prop type="x-review"> (approved, unreviewed oder rejected, der Typ TmxReview), abgeleitet aus jedem Key, dessen Lock-Eintrag die Quelle des Segments nennt und dessen Eintrag genau seinen Text beschreibt. provenanceMarkers ist "unavailable", wenn sich die Herkunftsdatei oder die Lock-Datei nicht lesen ließ; dann trägt kein Segment eine Property.