Mantén una biblioteca de lecciones multilingüe con las traducciones al día respecto al inglés

## Edita solo lecciones, artículos y traducciones, no el código de la aplicación Mantienes un repositorio compuesto únicamente por contenido: lecciones didácticas, artículos y sus traducciones. La aplicación de publicación que renderiza este contenido reside en otro lugar y no forma parte de este repositorio. Tu trabajo consiste en prosa, estructura y metadatos, no en código de aplicación. Límites de alcance que se deben respetar: - No añadas aquí código fuente de la aplicación, herramientas de compilación ni configuración de ejecución. Si un cambio requiere que el sitio se comporte de otra manera, dilo de forma explícita y describe el cambio complementario necesario en la aplicación de publicación, en lugar de improvisar uno aquí. - Los pequeños scripts de mantenimiento que informan sobre el propio contenido (por ejemplo, un informe del estado de las traducciones) son legítimos y deben usarse antes de editar, no sustituirse. - Trata cada archivo como algo que un traductor humano tendrá que seguir más adelante. Un cambio que te resulte cómodo pero que rompa el flujo de trabajo de traducción es un mal cambio. - Cuando una solicitud sea ambigua respecto a si afecta al idioma fuente o a una traducción, pregunta antes de escribir. Adivinar mal corrompe en silencio el seguimiento de obsolescencia que se describe más adelante. ## Refleja las mismas carpetas en todos los idiomas y cambia primero el original en inglés La biblioteca utiliza una estructura previsible y reflejada. Los archivos de lecciones se ubican bajo un directorio de lecciones, luego una carpeta nombrada con el código de idioma ISO, luego una carpeta de categoría y, por último, el propio documento. Las entradas del blog se ubican en un único directorio de publicaciones y se nombran con un prefijo de fecha seguido de un slug separado por guiones, de modo que el orden cronológico resulte visible solo con ver el nombre del archivo. El conjunto de categorías dentro de cada idioma es fijo e idéntico en todos los idiomas. Las categorías habituales son fundamentos, nivel intermedio, nivel avanzado, almacenamiento, pruebas, procesamiento de datos, material específico de frameworks y un apartado misceláneo. No inventes una categoría en un solo idioma; añádela en todos o en ninguno. Un idioma —normalmente el inglés— es la única fuente de verdad. Todos los demás directorios de idioma contienen traducciones de este. Reglas que se derivan de lo anterior: - Los cambios de fondo se realizan primero en el idioma fuente y después se propagan a las traducciones. Nunca introduzcas hechos, ejemplos o secciones nuevas únicamente en una traducción. - Una traducción solo puede corregirse por sí sola por motivos de calidad de traducción: errores de traducción, gramática, tipografía o convenciones del idioma local. - Si detectas en una traducción un error que también existe en el original, corrige el original y trata la traducción como una tarea posterior. ## Sube el número de versión según el tamaño del cambio y cópialo en las traducciones Todo documento comienza con un bloque de metadatos estructurado que termina en una línea separadora. Como mínimo, el bloque incluye una cadena de versión, un título y un breve extracto que resume el documento en una o dos frases. Las publicaciones de tipo artículo incluyen además el nombre del autor, un enlace al autor, etiquetas y una fecha de publicación. El campo de versión no es decorativo: lo lee una máquina. Una traducción copia exactamente la versión del documento original a partir del cual se tradujo. Las herramientas comparan después la versión de cada traducción con la versión actual del original para determinar si esa traducción está al día, ligeramente obsoleta o gravemente obsoleta. Incrementa la versión del original según la magnitud del cambio: - Mayor: el documento se reescribió en gran parte. Los traductores deben rehacer su trabajo. - Menor: se añadieron o eliminaron frases, párrafos o ejemplos. Los traductores deben revisar y corregir. - Parche: solo correcciones ortográficas y tipográficas. Las traducciones siguen siendo utilizables. Nunca incrementes una versión sin realizar el cambio correspondiente, y nunca hagas un cambio de fondo sin incrementarla. Ambos errores destruyen la exactitud del informe de obsolescencia, que es el único mecanismo que mantiene fiable la biblioteca traducida. Al editar una traducción, actualiza su versión solo cuando realmente la hayas puesto en línea con el contenido más reciente del original. ## Escribe en primera persona del plural y pon el ejemplo antes de la explicación Aplica estas convenciones a todo el contenido, salvo que una guía del idioma local las sustituya. - Usa la primera persona del plural, en un tono inclusivo. La persona que lee es una colaboradora que trabaja a tu lado, no una alumna a la que se sermonea. Evita fórmulas del tipo «debes» cuando el «nosotros» resulte natural. - Muestra primero, explica después. El ejemplo resuelto precede a su explicación; quien lee ve la cosa antes de leer sobre la cosa. - Mantén los párrafos cortos. Cuando la información se vuelva densa, conviértela en una lista con viñetas o en un bloque de ejemplo en lugar de un párrafo largo. - Usa la voz activa. Emplea formas contraídas de manera coherente en lugar de formas desarrolladas y formales. - Nada de emojis. Nada de lugares comunes, ni de relleno laudatorio, ni de frases que solo existen para presentar la frase siguiente. - Usa la coma serial. - Niveles de encabezado: encabezados de segundo nivel para las secciones principales y de tercer nivel para las subsecciones. Nunca coloques un encabezado de primer nivel dentro del cuerpo del texto: ese nivel corresponde al título del documento. - Cada bloque de ejemplo declara su identificador de lenguaje para que el renderizador pueda resaltarlo correctamente. Elimina todo lo que no enseñe. La extensión no es una virtud; un documento más corto que un traductor pueda reproducir con fidelidad vale más que uno más largo que se desvía. ## Ordena cada lección: resumen, ejemplos y temas relacionados Los documentos didácticos siguen una forma narrativa fija: 1. Una breve descripción general de lo que abarca el documento. 2. Motivación —por qué esto importa— en dos o tres frases como máximo. Resístete a ampliar esta sección; es el lugar donde con más frecuencia se acumula el relleno. 3. El contenido principal, guiado por ejemplos concretos con una explicación después de cada uno. 4. Conexiones hacia fuera: cómo se relaciona este tema con el material adyacente que quien lee ya ha visto o verá a continuación. Dentro del contenido principal, ordena el material desde el caso utilizable más simple hasta las variaciones más complejas, e introduce cada término antes de apoyarte en él. Si un documento crece hasta abarcar dos temas claramente separables, divídelo en lugar de dejar que se desborde: dos documentos enfocados se traducen mejor y quedan obsoletos de forma independiente. El extracto del bloque de metadatos debería poder escribirse únicamente a partir de la descripción general. Si no puedes resumir el documento en una o dos frases, el documento abarca demasiado. ## Añade lecciones o idiomas nuevos e indica el registro que necesita el sitio Documento original nuevo: crea el archivo dentro del directorio del idioma fuente, en la categoría correcta, con un bloque de metadatos completo que incluya una versión inicial. Después indica con claridad si hace falta un cambio complementario en la aplicación de publicación para registrar el nuevo documento y mostrarlo. No des por hecho que aparecerá automáticamente. Traducción nueva: copia el archivo original en el directorio del idioma de destino, en la misma ruta de categoría y con el mismo nombre de archivo, traduce el cuerpo y traduce los valores de metadatos legibles por personas, como el título y el extracto. Deja intactos los nombres de los campos estructurales y el valor de la versión: la versión debe coincidir exactamente con la del original. Idioma nuevo: crea el conjunto completo de directorios de categoría bajo el nuevo código de idioma para que la estructura refleje la de todos los demás idiomas, añade los primeros documentos traducidos y registra el idioma en la aplicación de publicación. Una carpeta de idioma que existe pero no está registrada produce contenido al que nadie puede llegar. Antes de escribir cualquier traducción, lee la nota de estilo específica de ese idioma, si existe. Las notas de idioma local abarcan decisiones terminológicas, transliteración de términos técnicos, puntuación y registro honorífico, y prevalecen sobre el estilo general de la casa cuando entran en conflicto. Si no existe una nota de idioma para la lengua a la que te piden traducir, propón crear una en lugar de inventar convenciones en silencio. ## Usa el informe de estado para actualizar primero las traducciones más desfasadas La deriva de las traducciones es el modo de fallo por defecto de una biblioteca multilingüe. Gestiónala de forma deliberada. Empieza cualquier sesión de traducción ejecutando el informe de estado sobre la biblioteca, en lugar de recorrer directorios a mano. Fíltralo por los idiomas de los que eres responsable y por los niveles de gravedad que importan: primero los documentos que faltan por completo y los marcados como gravemente obsoletos, después la deriva menor y, en último lugar o nunca, la deriva a nivel de parche. Reglas de trabajo: - No traduzcas un documento parcialmente y dejes la versión igual a la del original. Una traducción a medio terminar que se declara al día es peor que una que falta de forma evidente. - Si tienes que detenerte a mitad de camino, deja la versión en su valor anterior para que el informe siga marcando el archivo. - No hagas traducción automática y la publiques sin revisarla frente a la nota del idioma local. - Cuando el original cambie después de que hayas empezado, vuelve a revisar las diferencias antes de terminar; termina el trabajo frente a la versión que vas a registrar realmente. - Al final, informa de qué documentos pusiste al día, cuáles omitiste deliberadamente y por qué: la siguiente persona que colabore prioriza a partir de ahí.