Lingo check
Haz que CI falle cuando las traducciones estén desactualizadas y verifica los catálogos de React.
lingo check falla cuando las traducciones están desactualizadas. Compara cada archivo de origen con .lingo/lock.json, exige que existan todos los archivos de destino y, en proyectos de @lingo.dev/react, también verifica los catálogos extraídos, las declaraciones, el contexto y las traducciones.
lingo check --jsonQué verificaciones se ejecutan #
| Verificación | Se ejecuta cuando |
|---|---|
| Verificación de archivos | .lingo/config.json tiene files o el proyecto no es de React. |
| Verificaciones de React | El package.json de la raíz, o el más cercano a --src, incluye @lingo.dev/react, @lingo.dev/react-next o @lingo.dev/react-tanstack, o existe el archivo de declaraciones generado (lingo.d.ts de forma predeterminada). |
Un proyecto de React con files ejecuta ambas verificaciones. Si ningún patrón de files coincide con un archivo, la verificación falla con no-source-files, al igual que lingo push. La excepción son los proyectos de React, donde solo se ejecutan las verificaciones de React y esto se indica en stderr. Un proyecto sin files ni React falla con el mismo error de configuración que lingo push.
lingo check no necesita una clave de API ni escribe nada. Salvo por la telemetría de la CLI, que DO_NOT_TRACK=1 desactiva, no realiza llamadas de red. Termina con el código 1 si informa algún problema o encuentra un error de configuración (por ejemplo, una colisión de destinos o un Lockfile dañado), y con 0 en los demás casos.
Verificación de archivos #
Los archivos de origen son los que lingo push enviaría. Los destinos son las rutas en las que el comando push escribiría para cada idioma de destino configurado.
| Caso | Problema | Solución |
|---|---|---|
| Un archivo de origen coincide con su entrada en el Lockfile y sus destinos existen | ninguno | |
Ningún patrón de files coincide con un archivo | no-source-files | Corrige los patrones de files |
| Un archivo de origen cambió desde su última traducción | source-changed | lingo push --wait, o lingo pull si el comando push sigue en ejecución |
| Un archivo de origen no tiene una entrada en el Lockfile | source-not-pushed | lingo push --wait |
| Falta un archivo de destino y su archivo de origen está actualizado | missing-target | lingo push --backfill-missing --wait |
| Falta un archivo de destino y su archivo de origen cambió o nunca se envió | missing-target | lingo push --wait |
| Un archivo de destino se editó manualmente | ninguno | |
| No hay un Lockfile y existen todos los archivos de destino | ninguno, con una nota en stderr | |
| No hay un Lockfile y falta un archivo de destino | missing-target, con una nota en stderr | lingo push --backfill-missing --wait, luego crea un commit con los archivos de destino y .lingo/lock.json |
Se ignoran las entradas del Lockfile correspondientes a rutas que ya no están configuradas como archivos de origen. Las advertencias sobre destinos inferidos y archivos YAML omitidos que muestra lingo push también aparecen aquí, en stderr.
Cómo interpretar un problema #
| Tipo | Corrección que conviene investigar |
|---|---|
missing-context | Agrega contexto útil al mensaje extraído. |
stale-jsonc | Regenera y revisa el catálogo de origen. |
stale-types | Regenera las declaraciones e inclúyelas en la verificación de tipos de la aplicación. |
missing-translation | Revisa una clave activa que no tenga un valor de destino activo y no vacío. |
orphaned | Antes de realizar la limpieza, determina si el mensaje se eliminó o si la extracción lo omitió. |
Para conocer los problemas de la verificación de archivos y sus soluciones, consulta Verificación de archivos.
Salida JSON #
La salida JSON contiene issues y stats. La salida legible para personas enumera los mismos problemas para uso local.
Cada problema tiene type y message. Los problemas de React pueden tener src; los de archivos tienen file, y un problema de missing-target también tiene locale.
Las estadísticas contienen messages, locales, missingContext, missingTranslations, orphaned, staleJsonc y staleTypes, cuyos valores son cero o falso cuando no se ejecutaron las verificaciones de React. El recuento de idiomas incluye los destinos detectados y el idioma de origen. Cuando se ejecutó la verificación de archivos, stats.files contiene lockfile, sources, locales, changedSources y missingTargets. Estos valores describen la coherencia, no la calidad lingüística medida.
Ejecútalo en CI #
Ejecútalo en cada solicitud de incorporación o fusión de cambios, incluidas las que provienen de bifurcaciones:
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest checkUsa las mismas entradas que en la extracción #
--src, --out, --types y --source-locale se aplican solo a las verificaciones de React. El valor predeterminado de --src es src, y el de --source-locale es en. --out tiene prioridad sobre la ruta del catálogo configurada y, después, sobre locales; --types tiene prioridad sobre la ruta de declaraciones configurada y, después, sobre lingo.d.ts. Las rutas se resuelven desde la raíz del proyecto. El valor predeterminado del idioma de origen es independiente de la configuración de localización. El valor predeterminado de --json es falso y se aplica a ambas verificaciones.
Ejecuta la extracción con esas mismas entradas para actualizar los datos desactualizados. Revisa las advertencias y las diferencias, luego vuelve a ejecutar la verificación y la compilación de la aplicación. Elimina solo las entradas que hayas confirmado como obsoletas y después regenera las declaraciones.
Limitaciones #
- La verificación de archivos funciona a nivel de archivo. No informa si falta una clave dentro de un archivo de destino existente, excepto en los catálogos
.jsoncde React. - No se verifican los idiomas dentro de un catálogo compartido, como un archivo
.xcstrings, y una edición manual dentro de ese catálogo cuenta como un cambio en el origen. - Un repositorio que migró de la CLI a la GitHub App debe eliminar
.lingo/lock.json. - Los errores de configuración, como dos archivos de origen que se resuelven al mismo destino o un Lockfile dañado, hacen que el comando termine con el código 1, con un mensaje en stderr y sin JSON.
- Los hashes de origen dependen de los bytes exactos, por lo que el checkout en el que se ejecutó
lingo pushy el checkout de CI deben usar los mismos finales de línea. Agrega* text=auto eol=lfa.gitattributes.
Para los catálogos de React, los destinos son los archivos .jsonc del directorio del catálogo. Cuando los patrones de files coinciden con el catálogo de origen (por ejemplo, locales/en.jsonc), también se exige que exista el archivo de cada idioma de destino configurado.
Solo las advertencias de extracción por falta de contexto se convierten en problemas de contexto. Las advertencias sobre expresiones dinámicas y la información sobre colisiones no cubren aquí todos los casos que deberían provocar un fallo; la propia extracción falla ante una colisión. Un marcador de posición no vacío en el idioma de origen también puede superar la verificación de presencia sin ser una traducción.
Usa extract --check cuando solo necesites comprobar que los bytes generados estén actualizados. Mantén la validación del formato nativo y la revisión del contenido junto con este verificador; superar la verificación no garantiza nada sobre los recursos de Android, la visualización de Markdown ni el significado de las traducciones más allá de las comprobaciones que realiza.