¡Haz una donación a The Programming Historian!

Guía para traductores

Paso 1: Proponer una nueva traducción

Paso 2: Escribir y dar formato a una nueva traducción

Paso 3: Enviar una nueva traducción

Estas directrices han sido desarrolladas para ayudarte a entender el proceso de traducción de un tutorial para Programming Historian en Español. Incluyen detalles prácticos sobre el proceso de traducción de un tutorial, así como indicaciones sobre el flujo de trabajo y el proceso de revisión entre pares. Si en algún momento hay algo que no te queda claro, por favor envía un correo electrónico a Riva Quiroga.

Paso 1: Proponer una nueva traducción

Si quieres traducir una lección, por favor, revisa la lista de traducciones pendientes y ponte en contacto con Riva Quiroga. Buscamos traducciones rigurosas, de lectura amena y que, además, tengan en cuenta el contexto de América Latina y España, así como los recursos que se encuentra disponibles actualmente en lengua española.

Una vez aceptada tu propuesta y para asegurar la publicación oportuna, te pedimos que entregues tu traducción al cabo de 90 días tras la aprobación. Durante este período de 90 días, tu punto de contacto será la jefa de redacción o el editor o editora que haya sido asignada para acompañarte durante el proceso.

Paso 2: Escribir y formatear el tutorial

Esta guía de estilo define un conjunto de normas para ser utilizadas al traducir lecciones al español para Programming Historian. Al seguir estos lineamientos nos ayudas a asegurar que el contenido sea consistente y accesible.

La guía contempla tres secciones, que deben ser leídas antes y después de la escritura:

A. Estilo y audiencia

Esta primera sección se ocupa de cuestiones de estilo generales que te ayudarán a tomar decisiones que satisfagan las necesidades de nuestra audiencia y editores. Incluimos información básica sobre el estilo y el tono, el acceso abierto y los valores del código abierto, información sobre la escritura para una audiencia global, la escritura sostenible y la toma de decisiones inteligentes sobre los datos utilizados en las lecciones. Lee esta sección antes de traducir la lección. Vuelve a leerla antes de enviarla para asegurarte de que el tutorial cumple con estos requisitos.

Lenguaje y estilo

Escribe para una audiencia global

Programming Historian es leído por personas que viven en todo el mundo. Es por ello que debes tomar medidas para que tu traducción sea accesible para el mayor número de personas posible. Las siguientes directrices te ayudarán a enfrentar una audiencia global:

B. Pautas específicas de escritura

En esta segunda sección se abordan cuestiones más específicas del estilo de escritura, como qué palabras utilizar, cómo usar la puntuación o qué formato utilizar para fechas y números. Lee esta sección antes de hacer la traducción, ya que este tipo de lineamientos no son iguales en todos los idiomas, por eso es importante que los tengas en cuenta. Vuelve a leerlos al terminar para chequear que tu texto se ajusta a ellos.

Fechas y hora

Números

Listas

Típicamente, usamos listas numeradas y listas con viñetas. Los elementos de la lista comienzan con mayúscula. Los elementos de la lista deben ser tratados como elementos separados y no deben ser encadenados con puntuación o conjunciones.

Sin estilo apropiado:

Con estilo:

Puntuación

Mayúsculas

La pauta es usarlas con moderación en la prosa corriente. Reglas específicas:

Casos especiales y otros elementos a tener en cuenta

Referencias

Lenguaje inclusivo y no discriminatorio

En Programming Historian nos comprometemos a publicar tutoriales que no reproduzcan lenguaje sexista y discriminador. Te pedimos que tengas en cuenta las siguientes recomendaciones:

C. Guía de formato

Esta última sección abarca cuestiones de formato para el envío de tu traducción. Lee esta sección antes y después de escribir tu borrador. Si te equivocas en alguno de estos elementos, podrás corregirlo cuando publiquemos un avance en línea de tu lección al comienzo del proceso de revisión de pares.

Escribe en Markdown

Todas las lecciones deben ser escritas en Markdown. Tu editor/a te indicará dónde puedes encontrar el archivo de la lección original para que trabajes sobre él.

Markdown es un lenguaje de marcado que se crea mejor con un editor de texto. MS Word y Open Office NO son editores de texto y deben ser evitados. Recomendamos Atom, TextWrangler, TextEdit, MacDown, Notepad++ o Sublime Text. Para una introducción sencilla a Markdown puedes ver la lección Introducción a Markdown o la referencia concisa GitHub Guide to Markdown.

Tu lección debe ser guardada en formato .md. El nombre del archivo de tu lección se convierte en parte de la URL de la lección, por lo tanto, debe ser nombrado de acuerdo a las siguientes reglas:

Negrita, cursiva y subrayado

Para asegurar la consistencia de las lecciones, sigue las siguientes directrices de formato de texto:

Negrita

Cursiva

Subrayado

Alertas y advertencias

Si quieres incluir un aparte o una advertencia, puedes hacerlo con el siguiente código:

<div class="alert alert-warning">
¡Asegúrate se seguir cuidadosamente las instrucciones!
</div>

Este tipo de recurso puede ser útil para advertir a la audiencia sobre posibles dificultades o resultados diferentes producto de usar un sistema operativo, herramienta o datos en español.

Figuras e imágenes

Las imágenes pueden ayudar a tu audiencia a entender los pasos de la lección, pero no deben ser usadas como decoración. Si la lección que vas a traducir tiene imágenes, verás que estas están etiquetadas secuencialmente siguiendo el patrón nombre-leccion1.jpg, nombre-leccion2.jpg, etc., y que en el texto son referidas como “Figura 1”, “Figura 2”, y así sucesivamente. Si decides incluir versiones en español de esas mismas imágenes (por ejemplo, porque tradujiste los datos o existe versión en español de la interfaz de la herramienta utilizada), estas deben seguir su propia numeración correlativa, es decir, nombre-traduccion1.jpg, nombre-traduccion2.jpg. Todas las figuras deben venir con una leyenda concisa y notas finales cuando sea apropiado. Debes tener el derecho legal para publicar cualquier imagen que incluyas.

Utiliza formatos de archivos amigables para la web, como .png o .jpg, y reduce las imágenes grandes a un máximo de 840 px en el lado más largo. Esto es importante para lectores en países con velocidades de Internet más lentas.

Las imágenes deben guardarse en una carpeta con el mismo nombre que el archivo .md de la lección. El editor o editora asignada a tu lección te ayudará a subir las imágenes cuando las envíes.

Para insertar una imagen en tu texto, se utiliza el siguiente formato. Salvo que agregues una imagen adicional, solo correspondería traducir el pie de foto. Si agregas versiones traducidas de las imágenes existentes, no olvides cambiar el nombre del archivo con la imagen.

{% include figure.html filename="NOMBRE-ARCHIVO-IMAGEN" caption="PIE DE FOTO UTILIZANDO COMILLAS \"ESCAPADAS\"" %}

Ten en cuenta que las comillas internas en el pie de foto deben escaparse con una barra invertida, como en el ejemplo anterior. Es posible que las imágenes no aparezcan en las vistas previas de la lección, pero tu editor/a se asegurará de que se reproduzcan correctamente cuando esta se publique.

Ejemplos de código

Las líneas de código deben tener un formato que las distinga claramente de la prosa:

El bloque de código se verá así

` y así` el código dentro del texto.

Sigue las mejores prácticas para escribir tu código:

JavaScript:

abstract, arguments, await, Boolean, break, byte, case, catch, char, class, const, continue, debugger, default, delete, do, double, else, enum, eval, export, extends, false, final, finally, float, for, function, goto, if, implements, import, in, instanceof, int, interface, let, long, native, new, null, package, private, protected, public, return, short, static, super, switch, synchronized, this, throw, throws, transient, true, try, typeof, var, void, volatile, while, with, yield.

Python 3:

and, as, assert, break, class, continue, def, del, elif, else, except, False, finally, for, from, global, if, import, in, is, lambda, nonlocal, None, not, or, pass, raise, return, True, try, while, with, yield.

R:

break, else, for, FALSE, function, if, in, Inf, NA, NA_character_, NA_complex_, NA_integer_, NA_real_, NaN, next, NULL, repeat, TRUE, while, ... y ..1, ..2, etc.

Paso 3: Enviando una nueva traducción

Una vez que tu archivo ha sido preparado de acuerdo con las especificaciones anteriores, ¡ya puedes enviárnoslo! Te sugerimos, de todos modos, que pidas a un par de personas que lean tu traducción y te den su opinión.

En el GitHub de Programming Historian en GitHub mantenemos dos repositorios (es decir, dos sitios en donde almacenar archivos y carpetas). Por un lado, el repositorio jekyll, que contiene los archivos a los que se accede a través del navegador web. Por el otro, el repositorio ph-submissions, que es donde se realiza el proceso de edición de las lecciones originales y traducciones.

Debes enviar tu traducción a través de una correo electrónico a tu editor/a, quien se encargará de subir todos los materiales al repositorio correspondiente en GitHub.

  1. Obtener acceso: crea una cuenta gratuita en GitHub. Envía tu nombre de usuario de GitHub a tu editor/a, quien te dará acceso al sitio de envíos. Si bien no serás tú quien haga la carga inicial, necesitarás acceso para el proceso de revisión.
  2. Prepara los materiales: si tu traducción incluye imágenes adicionales a las que tenía originalmente la lección, asegúrate que todos los archivos están nombrados según las convenciones explicadas más arriba. Las imágenes debes enviarlas en una sola carpeta comprimida. Si tu lección incluye archivos de datos traducidos, estos deben ser enviados en otra carpeta comprimida.
  3. Envía un correo electrónico a tu editor/a: hazle saber a tu editor/a que tienes todo listo para el envío de tu lección. Este correo electrónico debe incluir el archivo .md de la lección y las carpetas comprimidas con las imágenes y datos, si corresponde.
  4. Únete a la conversación: tu editor/a subirá los archivos a nuestro repositorio de envíos y hará algunos cambios iniciales para asegurarse de que todo funciona bien. Además, abrirá un “ticket de revisión” para tu lección en la sección de issues de ese repositorio.
  5. Realiza las revisiones: si bien la carga inicial de tu lección en el repositorio ph-submissions será realizada por tu editor/a, el proceso editorial requerirá que hagas modificaciones. Todas las ediciones posteriores deben ser hechas directamente por ti en ese repositorio para asegurarnos de que estás trabajando en la última versión del archivo.

El proceso de revisión de pares

Tu editor comprobará que tus archivos se hayan cargado y formateado correctamente. En esta etapa se te enviará un enlace de vista previa donde se evidenciará cualquier error de formato para que puedas corregirlo. Las modificaciones debes hacerla en el archivo .md de tu traducción, que se encuentra en el repositorio de propuesta de lecciones.

La revisión de pares se registrará en un “ticket” que actúa como una discusión abierta en el tablero de mensajes. Ten en cuenta que nuestra revisión de pares se realiza en público y se mantiene a disposición del público como un registro permanente. Si tienes alguna preocupación o deseas solicitar una revisión cerrada, ponte en contacto con tu editor/a.

El proceso de revisión por pares normalmente se realiza en tres etapas:

1) Tu editor/a leerá y probará cuidadosamente tu traducción, proporcionando una primera ronda de retroalimentación a la que se te pedirá que respondas. El propósito de esta primera ronda de retroalimentación es asegurarse de que tu lección responde a las necesidades de la audiencia de Programming Historian y de que los revisores externos reciban una traducción que funcione. Normalmente se te dará un mes para responder a esta primera revisión.

2) Tu editor/a abrirá la traducción para una revisión formal de pares. Esto incluirá al menos dos revisores que serán contactados por tu editor/a. La revisión también puede incluir comentarios de la comunidad más amplia, que son bienvenidos para contribuir con sus puntos de vista. Por lo general, tratamos de pedir a los revisores que aporten sus comentarios en el plazo de un mes, pero a veces circunstancias imprevistas hacen que esto no sea posible. Tu editor/a debe dejarte claro que no debes responder a las sugerencias de cambios hasta después de que se hayan publicado ambas revisiones y que el editor haya resumido y dado instrucciones claras para seguir adelante. En algunos casos esto puede ser una sugerencia para revisar sustancialmente o repensar la lección. En otros casos será cuestión de hacer algunos cambios menores. En función de los comentarios de la revisión de pares y de la naturaleza de las cuestiones planteadas, puede ser necesario revisar el tutorial más de una vez. En todo momento tu editor/a se esforzará porque tengas claros los pasos necesarios para que la lección sea publicable. Siempre tendrás la opción de retirarte del proceso de revisión si así lo deseas.

3) Una vez que tu editor/a y revisores aprueben el texto, el editor recomendará la publicación a la jefa de redacción, quien leerá el tutorial para asegurarse de que cumpla con los lineamientos y estándares de esta Guía. En algunos casos, esta etapa puede considerar revisiones adicionales o edición de estilo para que el artículo se ajuste a nuestras normas de publicación. Si la jefa de redacción está satisfecha con tu lección, esta será trasladada al repositorio donde se aloja el sitio web de Programming Historian para su publicación. Tu editor/a te informará de cualquier información adicional que se requiera en esta etapa.

Puede resultarte útil leer nuestra Guía para editores, donde se detalla nuestro proceso editorial.

Si en algún momento tienes dudas de tu papel o de lo que debes hacer a continuación, publica una pregunta en el ticket de revisión de tu traducción. Nuestro equipo editorial responderá lo antes posible. Nos esforzamos por responder a todas las preguntas en unos pocos días.

Haznos responsables

Nuestro equipo voluntario trabaja duro para proporcionar a traductores y traductoras una revisión entre pares rigurosa, colegiada y eficiente. Sin embargo, reconocemos que hay momentos en que las expectativas pueden no cumplirse. Queremos que quienes participan del proceso se sientan con el poder de exigirnos altos estándares. Si, por cualquier razón, sientes que recibiste un trato injusto, que el proceso se volvió confuso, que la revisión se ha retrasado innecesariamente, que recibiste un trato grosero por parte de los revisores, que tu editor/a no ha sido lo suficientemente receptivo/a o tienes cualquier otra inquietud, por favor, háznoslo saber para que podamos abordarlo de manera proactiva.

Plantear una preocupación NO afectará negativamente el resultado de tu revisión de pares, incluso si se trata de una revisión de pares en curso.

Para plantear una preocupación, por favor contacta a una de las siguientes personas, según te resulte más cómodo:

Esperamos que no te encuentres en una situación incómoda, pero si esto sucede, te agradecemos que nos ayudes a mejorar.


La versión en inglés de esta guía de estilo fue creada con el apoyo de la Escuela de Humanidades de la Universidad de Hertfordshire. Esta traducción y adaptación al español es producto del trabajo conjunto del Equipo Editorial de Programming Historian en español.