Localizar contenido estático

Asocia los documentos y catálogos traducidos con los archivos que utiliza tu sitio o renderizador y comprueba la estructura, los enlaces y el resultado publicado.

El árbol de archivos fuente de tu sitio ya vincula los artículos con las rutas, los metadatos, la navegación y un renderizador. Añade los archivos traducidos donde ese sistema pueda cargarlos. El primer resultado útil es una página completa en el idioma de destino y en la ruta prevista, con enlaces que funcionen y los mismos ejemplos de código que el original.

Haz un inventario de los archivos según el sistema que los utiliza #

Separa los documentos extensos de los catálogos estructurados y los recursos especializados. Markdown, MDX y Markdoc necesitan un renderizador y un esquema. Los catálogos JSON, YAML, TypeScript y PHP necesitan un cargador. PO y XLIFF se conectan a sus propios sistemas de mensajes. SRT corresponde a un flujo de trabajo de contenido audiovisual sincronizado.

Elige un archivo fuente representativo de cada grupo e identifica la ruta de salida y el cargador que lo utilizará. Mantén los archivos de destino generados fuera de los patrones que seleccionan los archivos fuente. Conserva los ID de los documentos, las URL, los ejemplos de código, las claves de los catálogos y los atributos de los componentes cuyos valores controlan su comportamiento.

Utiliza Formatos para seleccionar el procesador adecuado. El YAML convencional es distinto del YAML con el idioma como clave raíz y del YAML de OpenAPI. .xml no identifica automáticamente un recurso de Android. Compartir una extensión no garantiza que un procesador entienda la estructura de tu documento.

Respeta la convención de directorios del sitio #

Estas son las opciones de organización que debes comprobar con el cargador de tu proyecto:

SitioQué definir antes de traducir
DocusaurusQué documentos fuente se convierten en archivos dentro de i18n/<locale>/docusaurus-plugin-content-docs/current/ y qué documentos versionados o cadenas del tema tienen entradas independientes.
NextraSi la configuración instalada carga páginas por idioma, diccionarios u otro árbol de contenido; asigna cada entrada por separado.
HugoQué archivos dentro de content/<locale>/ representan versiones traducidas del mismo contenido y cómo se resuelven los enlaces entre idiomas.
AstroQué colecciones de contenido por idioma y qué diccionarios de la interfaz utiliza cada ruta.
VitePressQué prefijo de directorio por idioma y qué configuración de navegación generan las páginas traducidas.
MkDocsQué complemento de i18n y qué organización de documentos por idioma utiliza el proyecto instalado.

En un ejemplo de Docusaurus con documentos fuente dentro de docs/, instala y vincula la CLI desde la raíz del proyecto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

Conserva los ID de la organización y del motor de localización en .lingo/config.json. Como estas rutas de origen no incluyen ningún idioma, sustituye la entrada del archivo por una plantilla de salida explícita:

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

Para docs/setup/install.md, [path] se convierte en setup/install.md, por lo que la salida en español se guarda en i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Confirma que el complemento y la versión instalados utilizan ese directorio. Configuración explica la validación de las plantillas y las reglas de colisión.

Selecciona con criterio los campos visibles del documento que vas a traducir #

Para Markdown, selecciona los metadatos de cabecera visibles para quien lee el documento, como el título y la descripción. Mantén sin cambios los metadatos de identidad y publicación. Para MDX y Markdoc, identifica también las propiedades de los componentes que se muestran a quien lee el documento, como el título de un aviso. Las propiedades que controlan el comportamiento y los nombres de los componentes forman parte del esquema de la aplicación.

Utiliza el procesador adecuado en lugar de dar por hecho que todos los archivos de la familia Markdown son intercambiables. Un documento Markdoc guardado como .md necesita que se indique explícitamente el formato markdoc para procesarse como Markdoc. Consulta Markdown, MDX y Markdoc para conocer los límites de selección y reconstrucción. Conserva los bloques de código delimitados como evidencia ejecutable; traduce la explicación que los rodea, no los comandos.

Ejecuta una operación para generar los archivos que faltan:

sh
lingo push --backfill-missing --wait

Cuando termine, compila el sitio y abre la ruta de destino generada. Comprueba el título, la descripción, el cuerpo, los componentes personalizados, el bloque de código y un enlace. Si los ID de los encabezados se derivan del texto, comprueba expresamente los enlaces a fragmentos traducidos siguiéndolos. Conservar una URL no basta: su destino debe existir. La guía de Markdoc con Next.js ofrece un ejemplo de carga por idioma.

Respeta las especificaciones de los catálogos estructurados #

Traduce los valores de cadena de JSON y YAML genérico y protege los ID, los puntos de conexión y otros datos no lingüísticos con los controles de claves del procesador. Establece format: "yaml" explícitamente para YAML genérico en la configuración de origen de la CLI actual: deducir el formato a partir de la extensión no basta para permitir el envío de un archivo fuente YAML sin configurar. Utiliza yaml-root-key cuando el idioma sea la clave raíz y yaml-openapi cuando la estructura sea un documento OpenAPI. Mantén TypeScript y PHP dentro de los formatos de catálogo admitidos; traducir un archivo no permite evaluar código fuente arbitrario de forma segura.

Para PO, conserva las identidades de los mensajes, el contexto, la estructura de plurales y el paso de compilación que utiliza el destino. Para XLIFF, conserva la estructura de origen, destino y marcadores de posición de la variante admitida. Comprueba la importación o compilación del sistema que realmente utiliza el archivo, en lugar de limitarte a verificar que existe un archivo de salida.

Los archivos .txt de texto plano, como las descripciones para las tiendas de aplicaciones, se traducen línea por línea y conservan las líneas del original. Incluye .txt en el patrón de archivos, como en metadata/en/*.txt, o configura "format": "txt": un patrón amplio como docs/en/**/* no los selecciona. Consulta Texto plano. Las tablas CSV con una columna por idioma se traducen en el mismo archivo: incluye .csv en el patrón o configura "format": "csv", tal como se describe en CSV. La CLI actual no ofrece como formatos configurables un archivo CSV por idioma, WebVTT ni .properties de Java. La referencia de formatos de la CLI v0 está dirigida a quienes siguen utilizando esos flujos de trabajo antiguos en sus instalaciones; sus comandos y su configuración son específicos de esa versión. Consulta la referencia de migración para elegir una opción compatible sin que esos recursos se descarten sin avisar.

Revisa los subtítulos junto con el contenido audiovisual #

Para SRT, traduce el texto de los segmentos de subtítulos y compara sus índices y tiempos con el original. Reproduce escenas representativas con los subtítulos en el idioma de destino. Comprueba la longitud del texto, los saltos de línea, el contexto de quien habla y las etiquetas de formato en el reproductor que se vaya a utilizar. Conservar las marcas de tiempo no garantiza que un segmento traducido pueda leerse dentro de su intervalo. Consulta SubRip para conocer las especificaciones del archivo; no lo sustituyas por WebVTT solo porque ambos sean formatos de subtítulos.

Amplía el proceso a partir de una vía de entrega comprobada #

Mantén juntos la configuración, los archivos fuente, los archivos de destino aceptados y el Lockfile de la CLI. Tras cambiar un párrafo, utiliza lingo push --wait para procesar los cambios habituales y compara después ese párrafo y una sección sin cambios en el destino. Mantén el archivo fuente anterior emparejado con su archivo de destino; reorganizar la estructura de los documentos puede generar ambigüedad al reutilizarlos. Un patrón posicional aplica reglas distintas a la planificación por ámbito. Utiliza el flujo de trabajo de estimación antes de volver a traducir grandes cantidades de contenido y trata las estimaciones como información para planificar, no como presupuestos.

Cuando las correcciones locales en el destino necesiten protección frente a divergencias, envía sin --wait e inspecciona lingo pull --dry-run antes de recuperar los resultados; la escritura directa tras la espera no incluye ese control. Sigue Conservar las traducciones revisadas.

Elige la GitHub App o las recetas de CI cuando un grupo se compile correctamente. Mantén la compilación del sitio, la validación del esquema, las comprobaciones de enlaces y la revisión del contenido dentro de ese ciclo; lingo check no garantiza que el documento esté completo. Cada actualización debe dejar una página de destino legible y una revisión del contenido fuente que el equipo pueda utilizar para el siguiente cambio.