Lexeri CLI Tool - Automatische Terminologieprüfung für die Kommandozeile

Für Teams, die Terminologie automatisiert prüfen möchten, bieten wir mit @lexeri/check-cli ein Kommandozeilen-Werkzeug (CLI), das wir über npm veröffentlicht haben. Damit lassen sich Dokumente direkt in Ihrer CI/CD-Pipeline gegen eine Termdatenbank prüfen – ohne dass ein Editor geöffnet werden muss.

Die CLI lädt die angegebene(n) Datei(en) hoch, startet einen Term-Check gegen die Termdatenbank Ihres API-Tokens, wartet auf das Ergebnis, listet alle gefundenen Terme mit ihrem Status auf und beendet sich mit einem für CI aussagekräftigen Exit-Code. So kann ein Build z. B. fehlschlagen, sobald unerwünschte Terminologie auftaucht.

Hinweis: Die Check-CLI ergänzt unsere Visual Studio Code Extension. Während die VS-Code-Extension für die interaktive Prüfung direkt im Editor gedacht ist, ist die CLI auf die automatisierte Prüfung in Build-Pipelines ausgelegt.

Voraussetzungen

• Node.js ab Version 20
• Ein Lexeri-API-Token (siehe unten)

Die CLI hat keine weiteren Laufzeit-Abhängigkeiten.

Installation

In der CI empfehlen wir, die CLI ohne feste Installation direkt über npx auszuführen – so nutzen Sie stets die aktuelle Version:

npx --yes @lexeri/check-cli --locale de src/i18n/de.json

Für die lokale Nutzung können Sie die CLI auch global installieren:

npm install -g @lexeri/check-cli
lexeri-check --locale de src/i18n/de.json

Nach der globalen Installation steht der Befehl lexeri-check zur Verfügung.

API-Token

Die CLI authentifiziert sich über einen API-Token. Diesen erstellen Sie in der Lexeri-Weboberfläche für die Termdatenbank, gegen die geprüft werden soll (siehe API-Token im Hilfecenter). Der Token benötigt die Scopes (Berechtigungen) check_text, read und show. Die Termdatenbank wird aus dem Token abgeleitet – ein separater Parameter für die Termdatenbank ist nicht nötig.

Übergeben Sie den Token über die Umgebungsvariable LEXERI_API_TOKEN (empfohlen für CI, dort als maskierte Variable) oder über die Option --token:

export LEXERI_API_TOKEN=eyJhbGciOi...
lexeri-check --locale de src/i18n/de.json Resources/Strings.resx

Der Token wird niemals protokolliert – auch nicht im ausführlichen Modus (--verbose).

Erste Schritte

Der grundlegende Aufruf lautet:

lexeri-check [Optionen] <Datei...>

Sie können eine oder mehrere Dateien angeben. Ein Beispiel-Ergebnis sieht so aus:

src/i18n/en.json  (check a1b2c3, 214 sentences, 12.3s)
  STATE            TERM         PREFERRED    OCCURRENCES
  not_recommended  "whitelist"  "allowlist"  4
  preferred        "email"      -            2

  6 matches: 4 not_recommended, 2 preferred  →  FAIL

1 file checked: 0 passed, 1 failed — FAIL (failing states: not_recommended, outdated)

Für jede Datei werden die Termtreffer mit ihrem Status, der Vorzugsbenennung und der Anzahl der Vorkommen aufgelistet. Bei String-Formaten werden die Treffer zusätzlich mit dem jeweiligen String-Schlüssel ausgegeben, sodass sich jeder Verstoß bis zum genauen Eintrag zurückverfolgen lässt.

Optionen

Exit-Codes

Die CLI beendet sich mit einem Exit-Code, den Ihre Pipeline auswerten kann:

Bei mehreren Dateien gewinnt das schlechteste Ergebnis: ein Betriebsfehler (3) schlägt fehlschlagende Terme (1), diese schlagen „bestanden" (0). Schlägt eine Datei fehl, werden die übrigen Dateien trotzdem weiter geprüft.

Welche Term-Status führen zum Fehlschlagen? (--fail-on)

Standardmäßig ruft die CLI Ihre Termdatenbank ab und schlägt bei deren negativen Term-Status fehl: not_recommended, outdated sowie alle benutzerdefinierten Status, die als ersetzbar markiert sind. Treffer mit preferred oder admitted werden ausgegeben, führen aber nie zum Fehlschlagen.

Mit --fail-on ersetzen Sie diese Menge vollständig, z. B.:

lexeri-check --fail-on not_recommended,deprecated,misspelled docs/handbuch.docx

misspelled ist ein Pseudo-Status: Nehmen Sie ihn auf, um bei falsch geschriebenen Term-Treffern fehlzuschlagen.

Treffer in Status, die weder fehlschlagend noch bekannt-positiv sind, werden als unknown angezeigt und lassen die Prüfung nie fehlschlagen – fügen Sie sie bei Bedarf explizit zu --fail-on hinzu.

Prüfung eingrenzen (--topics, --tags)

Standardmäßig prüft die CLI gegen die gesamte Termdatenbank. Sie können die Prüfung eingrenzen – etwa um UI-Strings nur gegen Ihre UI-Terminologie zu prüfen – indem Sie beim Anlegen der Prüfung nach Thema und/oder Tag filtern:

lexeri-check --topics 3fa5b2c1 --tags ui,frontend src/i18n/de.json

Themen werden über ihren Identifier referenziert; unbekannte Themen-Identifier werden vom Server ignoriert. Es handelt sich um dieselben Filter, die auch die Themen- und Tag-Auswahl im Prüfungsformular von Lexeri verwendet.

Filter für benutzerdefinierte Felder (--filter)

Termdatenbanken können benutzerdefinierte Felder für Termeinträge und Terme definieren (Auswahlliste, Zahl, Boolean, Datum). Filtern Sie danach mit wiederholbaren --filter <key>=<value>-Argumenten. Der Schlüssel ist dabei der Backend-Parametername: term_entry_field_<feld-identifier> bzw. term_field_<feld-identifier> (Datumsfelder erhalten die Suffixe _start/_end):

lexeri-check \
  --filter term_field_a1b2c3=released \
  --filter term_entry_field_d4e5f6=ui \
  --filter term_entry_field_d4e5f6=web \
  src/i18n/de.json

Wird derselbe Schlüssel wiederholt, werden die Werte als Array gesendet – so werden Auswahllisten-Felder mit Mehrfachauswahl abgefragt. Die Werte werden serverseitig gegen die Felddefinition geprüft (z. B. gegen die Optionen einer Auswahlliste); ungültige Abfragen werden vom Server stillschweigend verworfen und nicht als Fehler gemeldet.

Unterstützte Dateiformate

Die Dateien werden serverseitig geparst – die CLI filtert daher nicht nach Dateiendung, sondern der Server entscheidet, was er verarbeiten kann.

Besonders relevant für UI- und Software-Entwicklung:

• String-Ressourcen: .resx, .json, .properties, .strings, .po, .yaml/.yml, .ini, .csv, .xml, .twine
• Übersetzungsformate: .xlf/.xliff, .sdlxliff, .mqxliff, .tmx – XLIFF-Dateien unterstützen zusätzlich Übersetzungsprüfungen gegen Zielsprachen über --target-locales
• Dokumentation im Repository: .md, .html, .txt, .srt, .dita/.ditamap

Ebenso werden Office- und DTP-Dokumente unterstützt: Word, Excel und PowerPoint inklusive Alt- und Makro-Varianten (.docx/.doc/.docm, .xlsx/.xls/.xlsm, .pptx/.ppt/.pptm), OpenDocument (.odt, .ods, .odp), Apple iWork (.pages, .key) sowie .pdf, .rtf, .epub, .vsdx, .idml und .mif.

Bei String-Formaten werden Treffer mit den String-Schlüsseln ausgegeben, unter denen sie vorkommen, sodass sich Verstöße bis zum genauen Ressourcen-Eintrag zurückverfolgen lassen.

Einsatz in GitLab CI

Hinterlegen Sie LEXERI_API_TOKEN als maskierte CI/CD-Variable und rufen Sie die CLI dann per npx auf:

terminology-check:
  image: node:22-alpine
  script:
    - npx --yes @lexeri/check-cli --locale de src/i18n/de.json
  rules:
    - changes:
        - "src/i18n/**/*"

Alle String-Ressourcen eines bestimmten Typs prüfen, z. B. jede .resx-Datei (die Glob-Expansion übernimmt die Shell – auf minimalen Images verwenden Sie find):

  script:
    - find . -name '*.resx' -exec npx --yes @lexeri/check-cli --locale de {} +

Übersetzte XLIFF-Dateien gegen eine Zielsprache prüfen:

  script:
    - npx --yes @lexeri/check-cli --locale en --target-locales de translations/de.xlf

Einen maschinenlesbaren Bericht als Artefakt behalten:

terminology-check:
  image: node:22-alpine
  script:
    - npx --yes @lexeri/check-cli --json --locale de src/i18n/de.json > term-report.json
  artifacts:
    when: always
    paths: [term-report.json]

Mit --json geht der Bericht auf stdout, alles andere (Fortschritt, Warnungen) auf stderr – die Umleitung bleibt dadurch sauber.

Die CLI läuft in jeder CI-Umgebung mit Node.js ab Version 20; die obigen Beispiele lassen sich entsprechend auf andere CI-Systeme übertragen.

JSON-Ausgabe

Mit --json erhalten Sie einen maschinenlesbaren Bericht auf stdout:

{
  "version": 1,
  "verdict": "fail",
  "exitCode": 1,
  "failOn": ["not_recommended", "outdated"],
  "termbase": { "identifier": "…", "name": "Marketing" },
  "files": [
    {
      "file": "docs/manual.docx",
      "status": "fail",
      "checkIdentifier": "…",
      "localeCode": "en",
      "sentenceCount": 214,
      "durationMs": 12300,
      "totalMatches": 6,
      "countsByState": { "not_recommended": 4, "preferred": 2 },
      "misspelledCount": 0,
      "matches": [
        { "term": "whitelist", "state": "not_recommended", "classification": "fail", "preferred": "allowlist", "occurrences": 4, "misspelled": false }
      ],
      "error": null
    }
  ]
}

Wie funktioniert die Prüfung?

Die CLI löst zunächst über den API-Token die Termdatenbank und die fehlschlagenden Status auf. Anschließend lädt sie Ihre Datei(en) temporär in den Files-Service von Lexeri hoch, erstellt die Prüfung, wartet auf deren Abschluss (Abfrage alle 2,5 Sekunden, bis 100 % erreicht sind bzw. bis --timeout) und ruft die Termtreffer ab. Nach dem Abruf werden die Prüfung und das hochgeladene Dokument wieder vom Server gelöscht – es sei denn, Sie verwenden --keep-check.

Feedback

Dies ist die erste Version unserer Check-CLI, und wir haben viele weitere Ideen dafür. Haben Sie einen Wunsch oder einen Bug gefunden? Dann geben Sie uns gerne Bescheid: info@lexeri.com

Wir freuen uns auf Ihr Feedback!