Solución de problemas de la CLI

Resuelve problemas de selección de archivos, estado de referencia, recopilación y catálogos sin eliminar primero el estado útil.

Ten a mano la versión instalada, el comando, el directorio de trabajo, el error y las rutas afectadas mientras diagnosticas una falla. Oculta las credenciales antes de compartir registros: los diagnósticos de inicio y de fallas pueden incluir argv sin procesar.

No hubo coincidencias con archivos de origen #

Busca el .lingo/config.json más cercano. Un comando ejecutado en un directorio anidado puede usar el proyecto de un directorio superior. Revisa include antes de pattern, porque incluso una regla de inclusión vacía tiene prioridad sobre este último. Las exclusiones se aplican por entrada; otra entrada aún puede seleccionar un archivo.

Usa una sintaxis de coincidencia compatible, como docs/en/**/*, escribe los patrones de shell entre comillas y verifica qué sufijos se admiten. YAML requiere yaml, yaml-root-key o yaml-openapi de forma explícita; Android XML requiere android. Un archivo .txt, .csv o .properties necesita un patrón que termine en su extensión, o "format": "txt", "format": "csv" o "format": "properties"; un patrón general como docs/en/**/* lo omite, y una entrada txt, csv o properties omite todos los archivos que no tengan esa extensión. Especificar un formato no significa que se admitan todas las extensiones.

La salida se guardó en el lugar equivocado #

Lee las advertencias sobre la derivación de rutas y compara el destino con el cargador de tu aplicación. Si no se reconoce ningún segmento del idioma de origen, define targetPath y sourceRoot en lugar de depender de la alternativa que inserta el idioma. Mantén los archivos de destino fuera de la búsqueda de archivos de origen y revisa las colisiones de rutas.

Mover los archivos no actualiza por sí solo el estado de referencia. XCStrings usa intencionalmente un único catálogo de origen compartido; no sigue una estructura convencional por idioma. Consulta rutas de salida.

Una opción no tiene efecto #

Las claves desconocidas de nivel raíz o de archivo generan advertencias y se ignoran. Verifica que estén bien escritas y que el controlador seleccionado realmente admita esas opciones. La configuración de rutas del catálogo no actualiza los patrones de push, y extract y check establecen, cada uno por su cuenta, el idioma de origen predeterminado en en.

La evaluación local usa el ejecutable lingo.config.ts, no el JSON del proyecto. Una opción de protección de JSON no necesariamente controla Markdown ni otros formatos.

Falta un artefacto del estado de referencia #

El artefacto de origen anterior identificado por el hash del Lockfile debe existir localmente o en el servidor. Revisa la entrada indicada y recupera bytes que sepas que son correctos o un estado de referencia coherente. No inventes un hash ni borres todo el Lockfile para ocultar el error.

Si falta el estado, un primer push sin opciones adicionales almacena los bytes de origen; para los archivos de destino convencionales que falten, se necesita una reposición. Lockfile y caché explica qué registro necesita la operación.

Pull informa un conflicto #

Ejecuta lingo pull --dry-run para revisar las decisiones de escritura. Un archivo de destino que difiera de la salida del servidor, de los bytes capturados al ejecutar push y del hash del Lockfile bloquea las escrituras. Registrarlo en un commit no cambia la comparación.

Conserva y concilia la edición, restaura una versión conocida o usa la opción de forzado solo si quieres reemplazarlo deliberadamente. No edites los archivos de destino durante push --wait, ya que, a diferencia de pull, no vuelve a comprobar los conflictos.

El trabajo falló o sigue incompleto #

Revisa los errores de cada destino y distingue entre trabajo pendiente, revisión, fallas y salidas faltantes. Una ejecución fallida hace que push --wait y pull terminen con un código distinto de cero después de escribir los documentos completados; verifica el estado y los archivos reales.

Cuando todos los destinos pendientes estén esperando una revisión humana, push --wait y pull dejan de esperar y lo indican. Se pueden recuperar los documentos cuyos idiomas estén todos completos; vuelve a ejecutar lingo pull cuando quienes realizan la revisión terminen. Otro push no resuelve la espera de una revisión.

Si la ejecución falló, corrige la causa indicada y repite el comando adecuado para ese trabajo. Para las actualizaciones habituales del origen, usa lingo push --wait sin modificar el origen y conservando el estado de referencia. Para los archivos de destino faltantes, repite la reposición solo después de que los destinos existentes estén actualizados, siguiendo Agregar un idioma. No hace falta editar el origen, usar una opción de forzado ni eliminar el estado solo para solicitar otro intento.

Push muestra el ID del trabajo que envía o al que vuelve a vincularse. Si nunca se recuperaron los resultados del push anterior y la solicitud no cambió, push reutiliza esa solicitud: un trabajo que sigue en ejecución conserva su ID, y uno fallido se reemplaza por un trabajo nuevo. Guarda el ID del trabajo fallido y confirma que la siguiente línea Job mostrada tenga un ID diferente. Eso identifica un nuevo envío, no una traducción exitosa: revisa los resultados de sus destinos, recupera la salida y revisa las diferencias. Mantén los archivos de destino locales sin cambios durante --wait; si necesitas proteger las ediciones locales, ejecuta push y pull por separado, con comprobación de conflictos en pull.

Si el cliente que tienes instalado devuelve el mismo trabajo fallido, deja de repetir los envíos y escribe a support@lingo.dev. Incluye la versión de la CLI, el comando sin datos sensibles, los ID de ejecución anteriores y devueltos, la revisión del origen, los idiomas y las rutas afectados, las marcas de tiempo y el error sin datos sensibles. No incluyas credenciales, texto de origen privado ni archivos de credenciales sin procesar en el mensaje. Conserva el puntero de ejecución local y el Lockfile mientras se investiga la falla.

Eliminar el puntero de ejecución no es una forma confiable de solicitar una traducción nueva; mientras no se hayan recuperado los resultados de un push, el puntero conserva la identidad de la solicitud que evita envíos duplicados. Si no se encuentra ninguna ejecución, revisa la máquina, la ruta absoluta del directorio raíz del proyecto y si otro push reemplazó el puntero.

Fallan las comprobaciones del catálogo #

Ejecuta extract con el mismo idioma y las mismas rutas que check. Revisa las advertencias sobre llamadas dinámicas o desestructuradas antes de eliminar entradas huérfanas. Solo se informa que falta un archivo de destino cuando los patrones de files coinciden con el catálogo de origen; de lo contrario, compara los idiomas esperados con los archivos existentes.

Limpia solo las eliminaciones intencionales, vuelve a generar las declaraciones y luego ejecuta check y la compilación de la aplicación. status pasó a check; los nombres de servicios internos no son comandos ejecutables.

Antes de eliminar cualquier cosa #

Purgar muestra una vista previa de la eliminación de archivos de destino. Los filtros de archivos e idiomas limitan la eliminación a los destinos seleccionados y sus entradas en el Lockfile; una purga sin filtros elimina todo el Lockfile. Se omiten los catálogos compartidos de XCStrings. Usa purge cuando tu intención sea eliminar. La mayoría de las tareas de recuperación requieren una corrección específica que conserve la redacción aceptada y el estado recuperable.