Lingo check
CI bei veralteten Übersetzungen fehlschlagen lassen und React-Kataloge kontrollieren.
lingo check schlägt fehl, wenn Übersetzungen veraltet sind. Der Befehl vergleicht jede Quelldatei mit .lingo/lock.json und setzt voraus, dass alle Zieldateien vorhanden sind. In @lingo.dev/react-Projekten kontrolliert er außerdem extrahierte Kataloge, Deklarationen, Kontext und Übersetzungen.
lingo check --jsonWelche Prüfungen durchgeführt werden #
| Check | Läuft, wenn |
|---|---|
| Datei-Check | .lingo/config.json enthält files, oder das Projekt ist kein React-Projekt. |
| React-Checks | Die package.json im Projektstamm oder diejenige, die --src am nächsten liegt, führt @lingo.dev/react, @lingo.dev/react-next oder @lingo.dev/react-tanstack auf, oder die generierte Deklarationsdatei (standardmäßig lingo.d.ts) ist vorhanden. |
In einem React-Projekt mit files laufen beide Checks. Wenn kein files-Muster auf eine Datei zutrifft, schlägt der Check mit no-source-files fehl, genau wie lingo push. Eine Ausnahme bilden React-Projekte: Dort laufen nur die React-Checks, worauf eine Meldung auf stderr hinweist. Ein Projekt ohne files und ohne React schlägt mit demselben Konfigurationsfehler wie lingo push fehl.
lingo check benötigt keinen API-Schlüssel und schreibt nichts. Abgesehen von der CLI-Telemetrie, die sich mit DO_NOT_TRACK=1 deaktivieren lässt, erfolgen keine Netzwerkaufrufe. Sobald der Befehl ein Problem meldet oder auf einen Konfigurationsfehler stößt (zum Beispiel eine Zielkollision oder ein beschädigtes Lockfile), endet er mit Exit-Code 1, andernfalls mit 0.
Datei-Check #
Quellen sind die Dateien, die lingo push senden würde. Ziele sind die Pfade, in die push für jede konfigurierte Zielsprache schreiben würde.
| Fall | Problem | Behebung |
|---|---|---|
| Eine Quelle stimmt mit ihrem Lockfile-Eintrag überein und ihre Ziele sind vorhanden | keines | |
Kein files-Muster trifft auf eine Datei zu | no-source-files | Die files-Muster korrigieren |
| Eine Quelle wurde seit ihrer letzten Übersetzung geändert | source-changed | lingo push --wait oder lingo pull, wenn noch ein Push läuft |
| Für eine Quelle fehlt der Lockfile-Eintrag | source-not-pushed | lingo push --wait |
| Eine Zieldatei fehlt und ihre Quelle ist aktuell | missing-target | lingo push --backfill-missing --wait |
| Eine Zieldatei fehlt und ihre Quelle wurde geändert oder noch nie per Push übertragen | missing-target | lingo push --wait |
| Eine Zieldatei wurde manuell bearbeitet | keines | |
| Kein Lockfile vorhanden, aber alle Zieldateien sind vorhanden | keines, mit einem Hinweis auf stderr | |
| Kein Lockfile vorhanden und eine Zieldatei fehlt | missing-target, mit einem Hinweis auf stderr | lingo push --backfill-missing --wait, dann die Zieldateien und .lingo/lock.json committen |
Lockfile-Einträge für Pfade, die nicht mehr als Quellen konfiguriert sind, werden ignoriert. Die Warnungen zu vermuteten Zielen und übersprungenen YAML-Dateien, die lingo push ausgibt, erscheinen auch hier auf stderr.
Problemmeldungen verstehen #
| Typ | Möglicher Lösungsansatz |
|---|---|
missing-context | Ergänze die extrahierte Nachricht um hilfreichen Kontext. |
stale-jsonc | Generiere den Quellkatalog erneut und sieh ihn dir an. |
stale-types | Generiere die Deklarationen erneut und beziehe sie in die Typprüfung der Anwendung ein. |
missing-translation | Untersuche einen aktiven Schlüssel, dessen aktiver Zielwert fehlt oder leer ist. |
orphaned | Kläre vor der Bereinigung, ob die Nachricht entfernt oder bei der Extraktion nicht erfasst wurde. |
Probleme beim Datei-Check und ihre Behebung findest du unter Datei-Check.
JSON-Ausgabe #
Die JSON-Ausgabe enthält issues und stats. Die menschenlesbare Ausgabe listet für die lokale Nutzung dieselben Probleme auf.
Jede Problemmeldung enthält type und message. React-Problemmeldungen können src enthalten; Datei-Problemmeldungen enthalten file, und eine missing-target-Problemmeldung enthält außerdem locale.
Die Statistiken enthalten messages, locales, missingContext, missingTranslations, orphaned, staleJsonc und staleTypes. Diese Werte sind 0 oder false, wenn die React-Checks nicht ausgeführt wurden. Die Anzahl der Sprachen umfasst die gefundenen Zielsprachen sowie die Quellsprache. Wenn der Datei-Check ausgeführt wurde, enthält stats.files die Felder lockfile, sources, locales, changedSources und missingTargets. Diese beschreiben die Konsistenz, nicht die gemessene Sprachqualität.
In CI ausführen #
Führe den Befehl bei jedem Pull Request oder Merge Request aus, auch bei solchen aus Forks:
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkDieselben Eingaben wie bei der Extraktion verwenden #
--src, --out, --types und --source-locale gelten nur für die React-Checks. --src hat den Standardwert src und --source-locale den Standardwert en. Für den Katalogpfad gilt folgende Rangfolge: --out, der konfigurierte Katalogpfad, dann locales. Für den Deklarationspfad gilt: --types, der konfigurierte Deklarationspfad, dann lingo.d.ts. Pfade werden relativ zum Projektstamm aufgelöst. Der Standardwert für die Quellsprache ist unabhängig von der Lokalisierungskonfiguration. --json hat den Standardwert false und gilt für beide Checks.
Führe die Extraktion mit denselben Eingaben aus, um veraltete Daten zu aktualisieren. Sieh dir die Warnungen und den Diff an und führe anschließend den Check und den Build der Anwendung erneut aus. Bereinige nur Einträge, die nachweislich nicht mehr benötigt werden, und generiere danach die Deklarationen erneut.
Grenzen #
- Der Datei-Check arbeitet auf Dateiebene. Ein fehlender Schlüssel innerhalb einer vorhandenen Zieldatei wird nicht gemeldet, außer in React-
.jsonc-Katalogen. - Sprachen innerhalb eines gemeinsamen Katalogs, etwa einer
.xcstrings-Datei, werden nicht kontrolliert. Eine manuelle Änderung darin zählt als Änderung der Quelle. - Ein Repository, das von der CLI zur GitHub App gewechselt ist, sollte
.lingo/lock.jsonlöschen. - Konfigurationsfehler, etwa zwei Quellen, die zum selben Ziel aufgelöst werden, oder ein beschädigtes Lockfile, führen zu Exit-Code 1 mit einer Meldung auf stderr und ohne JSON-Ausgabe.
- Quell-Hashes sind bytegenau. Daher müssen der checkout, in dem
lingo pushausgeführt wurde, und der CI-checkout dieselben Zeilenenden verwenden. Füge* text=auto eol=lfzu.gitattributeshinzu.
Bei React-Katalogen sind die Ziele die .jsonc-Dateien im Katalogverzeichnis. Wenn die files-Muster auf den Quellkatalog zutreffen (zum Beispiel locales/en.jsonc), muss auch die Datei für jede konfigurierte Zielsprache vorhanden sein.
Nur Extraktionswarnungen wegen fehlenden Kontexts werden zu Kontext-Problemmeldungen. Warnungen zu dynamischen Ausdrücken und Kollisionsinformationen dienen hier nicht als umfassende Fehlerkontrolle; bei Kollisionen schlägt bereits die Extraktion selbst fehl. Auch ein nicht leerer Platzhalter in der Quellsprache kann die Kontrolle auf vorhandene Werte bestehen, ohne eine Übersetzung zu sein.
Verwende extract --check, wenn lediglich die Aktualität der generierten Bytes sichergestellt werden muss. Behalte neben diesem Check die native Formatvalidierung und die inhaltliche Prüfung bei. Ein erfolgreicher Durchlauf sagt nichts über Android-Ressourcen, die Markdown-Darstellung oder die Bedeutung von Übersetzungen aus, soweit diese nicht von den tatsächlich durchgeführten Checks abgedeckt sind.