Localiza contenido estático

Asocia los documentos y catálogos traducidos con los archivos que usa tu sitio o renderizador. Luego, verifica la estructura, los enlaces y el resultado final.

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

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

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 multimedia sincronizado.

Elige un archivo fuente representativo de cada grupo e identifica la ruta de salida y el cargador que lo usará. Mantén los archivos de destino generados fuera de los patrones de 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 componentes cuyos valores controlan el comportamiento.

Usa Formatos para seleccionar el procesador correspondiente. El YAML común 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.

Sigue la convención de directorios del sitio #

Confirma estas opciones de organización 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 separadas.
NextraSi la configuración instalada carga páginas por idioma, diccionarios u otro árbol de contenido; asocia cada entrada por separado.
HugoQué archivos dentro de content/<locale>/ representan el mismo contenido traducido y cómo se resuelven los enlaces entre idiomas.
AstroQué colecciones de contenido por idioma y diccionarios de la interfaz alimentan 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 usa el proyecto instalado.

Para 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 contienen un idioma, reemplaza 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, de modo 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 usen ese directorio. Configuración explica la validación de plantillas y las reglas de colisión.

Elige qué campos visibles del documento traducir #

Para Markdown, selecciona los campos de metadatos iniciales visibles para el público, 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 componentes visibles para el público, como el título de un recuadro destacado. Las propiedades que controlan el comportamiento y los nombres de componentes pertenecen al esquema de la aplicación.

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

Ejecuta un proceso para completar los archivos faltantes:

sh
lingo push --backfill-missing --wait

Al finalizar, compila el sitio y abre la ruta de destino generada. Revisa 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 generan a partir del texto, sigue explícitamente los enlaces a fragmentos traducidos. Una URL conservada también necesita un destino que exista. La guía de Markdoc con Next.js ofrece un ejemplo de carga por idioma.

Respeta los contratos de los catálogos estructurados #

Traduce los valores de texto 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. Define format: "yaml" explícitamente para YAML genérico en la configuración de origen de la CLI actual: inferir el formato solo por la extensión no habilita el envío de un archivo fuente YAML sin configurar. Usa yaml-root-key cuando el idioma sea la clave raíz y yaml-openapi cuando la estructura sea un documento OpenAPI. Limita TypeScript y PHP a sus formatos de catálogo compatibles; traducir un archivo no evalúa de forma segura código fuente arbitrario.

Para PO, conserva las identidades de los mensajes, el contexto, la estructura de plurales y el paso de compilación que usa el destino. Para XLIFF, conserva la estructura de origen y destino, así como los marcadores de posición, de la variante compatible. Verifica la importación o compilación del sistema que realmente usa el archivo, en lugar de comprobar solo que exista un archivo de salida.

Los archivos .txt de texto sin formato, 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 sin formato. Una tabla CSV con una columna por idioma se traduce en el mismo archivo: incluye .csv en el patrón o configura "format": "csv", como se explica en CSV. La CLI actual no ofrece un archivo CSV por idioma, WebVTT ni .properties de Java como formatos configurables. La referencia de formatos de la CLI v0 está dirigida a quienes aún usan esos flujos de trabajo anteriores en sus instalaciones; sus comandos y su configuración son específicos de esa versión. Usa la referencia de migración para elegir una alternativa compatible sin que esos recursos se descarten sin aviso.

Revisa los subtítulos junto con el contenido multimedia #

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 de destino. Verifica la extensión del texto, los saltos de línea, el contexto de quien habla y las etiquetas de formato en el reproductor que se usará. Conservar las marcas de tiempo no garantiza que un segmento traducido pueda leerse dentro de su intervalo. Consulta SubRip para conocer el contrato del archivo; no lo sustituyas por WebVTT solo porque ambos sean formatos de subtítulos.

Amplía el alcance a partir de una vía de entrega validada #

Mantén juntos la configuración, los archivos fuente, los archivos de destino aceptados y el Lockfile de la CLI. Después de cambiar un párrafo, usa lingo push --wait para procesar los cambios habituales y luego compara ese párrafo y una sección sin cambios en el archivo de destino. Mantén el archivo fuente anterior asociado a su traducción; reorganizar la estructura de los documentos puede volver ambigua la reutilización. Un patrón posicional usa una semántica distinta para la planificación por ámbito. Usa el flujo de trabajo de estimación antes de realizar una retraducción a gran escala y trata las estimaciones como información para planificar, no como cotizaciones de precios.

Cuando las correcciones locales en los archivos de 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 de resultados tras la espera no tiene ese punto de control. Sigue Conserva las traducciones revisadas.

Elige la GitHub App o las recetas de CI una vez que un grupo se compile correctamente. Mantén la compilación del sitio, la validación del esquema, la comprobación 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 de los archivos fuente que el equipo pueda usar para el siguiente cambio.