verbatra pseudo

Starte deine App in einer Sprache, die es nicht gibt. pseudo baut allein aus deinen Quellstrings eine künstliche Locale: Jeder Wert wird mit Akzenten versehen, verlängert und in sichtbare Begrenzungszeichen gesetzt. So fallen ein abgeschnittener Button, ein aus zwei Fragmenten zusammengeklebter Satz und ein Label, das nie für die Übersetzung extrahiert wurde, sofort auf dem Bildschirm auf. Es kostet nichts: Es wird kein Provider konstruiert, keine Netzwerkanfrage gestellt und kein API-Key gelesen, es funktioniert also in einem frischen Checkout, bevor überhaupt ein Key existiert.

Greif am ersten Tag dazu, bevor du ein Provider-Konto hast, und danach immer wieder, wenn du ein Layout änderst. verbatra translate --dry-run sagt dir, was ein echter Lauf übersetzen würde; pseudo gibt dir etwas, womit du die App wirklich starten kannst.

Synopsis

verbatra pseudo [flags]

Flags

Was die Transformation tut

Aus Hello {{name}}, you have {{count}} unread messages wird [Ĥéĺĺó {{name}}, ýóú ĥáṽé {{count}} úńŕéáḋ ṁéśśáġéś······].

Alles, was kein übersetzbarer Text ist, bleibt unangetastet. Platzhalter überleben in jeder Syntax, die die Format-Adapter kennen: Tokens mit doppelten geschweiften Klammern, i18next-Verschachtelungsreferenzen, Argumente in einfachen geschweiften Klammern und ICU-Argumente, printf-Konvertierungen und Apple-Pluralvariablen, Markup-Tags, XML-Entities, verlinkte vue-i18n-Nachrichten und Escape-Sequenzen. Innerhalb einer ICU-Nachricht bleiben die Argumentnamen, die Schlüsselwörter plural und select und jeder Zweig-Selektor genau so stehen, wie sie geschrieben sind, und nur der Text innerhalb eines Zweigs wird akzentuiert.

vue-i18n packt Pluralformen in einen einzigen, durch Pipe getrennten Wert, deshalb wird jede Form für sich akzentuiert, verlängert und markiert: Aus car | cars wird [ćáŕ··] | [ćáŕś··] statt eines einzigen geklammerten Blocks, und genau bei Pluralen ist das Layout am schwersten richtig hinzubekommen.

Die Transformation ist deterministisch: Dieselbe Quelle erzeugt immer dieselbe Pseudo-Locale, und die Datei lässt sich sauber diffen.

Nichts Kaputtes landet je in der Datei

Jeder erzeugte Wert muss dasselbe Integritäts-Gate passieren wie die Übersetzung eines Providers: dieselben Platzhalter wie die Quelle, gültig unter der Nachrichtensyntax des Formats, nicht degeneriert und nicht leer. Ein Wert, der das nicht schaffen würde, wird wortwörtlich aus der Quelle kopiert und in der Ausgabe unter copied verbatim genannt. Der Eintrag ist also weiterhin vorhanden und wird weiterhin gerendert. Das ist ein Bericht, kein Fehlschlag, und der Befehl endet trotzdem mit 0.

Wohin die Ausgabe geht

Die Pseudo-Locale wird außerhalb deiner echten Locale-Dateien geschrieben, standardmäßig unter .verbatra-local/pseudo. verbatra init trägt .verbatra-local/ bereits in .gitignore ein, die erzeugte Datei wird also nicht versehentlich committet, und pseudo ergänzt diesen Eintrag in einer vorhandenen .gitignore, falls er fehlt.

Dein konfiguriertes files.pattern wird innerhalb dieses Verzeichnisses expandiert, die Datei behält also das Layout, das deine App erwartet: Mit locales/{locale}.json schreibt der Standardlauf nach .verbatra-local/pseudo/locales/en-XA.json. Richte deinen Dev-Server oder deine i18n-Bibliothek auf dieses Verzeichnis aus, um sie zu laden. Mit --out schreibst du sie dorthin, wo dein Build sie ohnehin ausliefert.

Drei Regeln verhindern, dass sie je für eine echte Übersetzung einsteht:

• Eine Pseudo-Locale, die deine Quell-Locale oder eine deiner Ziel-Locales benennt, wird mit PSEUDO_OUTPUT_CONFLICT zurückgewiesen, bevor irgendetwas gelesen oder geschrieben wird.
• Ein --out, das die Datei auf eine konfigurierte Locale-Datei legen würde, wird genauso zurückgewiesen.
• Ein --out, das absolut ist oder mit .. aus dem Arbeitsverzeichnis herausklettert, wird ebenfalls zurückgewiesen, damit eine erzeugte Pseudo-Locale nie außerhalb des Projekts landet, aus dem sie stammt.

Weil die Datei außerhalb von files.pattern liegt, sieht verbatra translate sie nie und gibt nie Geld für sie aus, und verbatra check und verbatra diff melden sie nie als fehlend oder veraltet. Es gibt nichts zu targetLocales hinzuzufügen und nichts aus der CI auszuschließen.

Formate, die durch Patchen einer vorhandenen Datei geschrieben werden

xliff und apple-xcstrings werden nicht von Grund auf neu geschrieben: Ihre Writer patchen Einheiten, die bereits im Zieldokument stehen. Die Pseudo-Locale-Datei wird deshalb bei jedem Schreibvorgang neu aus deiner Quelldatei kopiert, damit ein Key, den du nach dem ersten Lauf zur Quelle hinzufügst, weiterhin in der Pseudo-Locale ankommt, statt stillschweigend zu fehlen. Bei einer kopierten XLIFF-Datei wird außerdem das Attribut target-language auf die Pseudo-Locale umgeschrieben, damit die Datei nie behauptet, eine Sprache zu enthalten, die sie nicht enthält.

Beispiele

# generate en-XA under .verbatra-local/pseudo
verbatra pseudo

# generate a second pseudolocale alongside it
verbatra pseudo --locale en-XB

# write it where the dev server already serves static files
verbatra pseudo --out public/locales-pseudo

# machine-readable result for a script
verbatra pseudo --json

Ein Lauf sieht so aus:

verbatra pseudo
  en-XA: 118 of 120 entries pseudolocalized
    copied verbatim: legal.disclaimer, brand.name
  wrote /app/.verbatra-local/pseudo/locales/en-XA.json

Lass ihn ohne Änderung an der Quelle noch einmal laufen, und er schreibt nichts neu:

verbatra pseudo
  en-XA: 120 of 120 entries pseudolocalized
  unchanged /app/.verbatra-local/pseudo/locales/en-XA.json

Exit-Codes

Es gibt keinen Exit 1: Ein wortwörtlich kopierter Wert wird gemeldet, nicht als Fehlschlag behandelt.

Siehe auch

• verbatra translate macht die echte Arbeit, sobald du einen Key hast.
• verbatra doctor ist der andere Befehl, der ein Projekt prüft, ohne Geld auszugeben.
• Formate listet die Platzhaltersyntax jedes Formats.
• Konfigurationsdatei dokumentiert files.pattern, das über das Layout der erzeugten Datei entscheidet.