;-*-outline-*- Ventura V., 2005, a partir de notas más antiguas sobre
años de traducciones de páginas man e interfaces de programas.

General para documentación en manuales, libros, guías, etc.

Cada nuevo manual debe tener un fichero de elecciones de traducciones

Además del listado general de vocablos de la sección de traducciones,
cada nuevo documento debe generar un fichero adjunto creado por el
traductor, donde se vayan compilando las elecciones y sus razones.

Agregado posterior para el caso de Emacs y similares (2007)

En el caso de manuales relacionados, como los de Emacs e Emacs Lisp
tiene que haber las indicaciones oportunas.

Estos dos manuales, a su vez, obligan a una necesaria incursión en el
mundo de Lisp, lo que, en su día, podría ser la base para un fichero
específico de ámbito más general llamado "mundo-lisp" o algo así.

Presunciones de estilo

- Evítense al máximo los participios de los verbos, práctica tan
extendida en la documentación inglesa.

- Nunca se habla con el lector. Utilícese el impersonal reflexivo,
como corresponde al español.

- La plasticidad latina debe imponerse al encorsetamiento
pseudo-técnico. Hágase sin pudor.

Lo que NO se traduce

• Siempre se dejarán sin traducir las cadenas de texto, mensajes,
  etc. que se vayan a presentar al usuario de esa manera literal, salvo
  una posible i18n del programa. Cuando se traduce la documentación, no
  es responsabilidad del traductor decidir cuales serán las futuras
  traducciones de las cadenas internacionalizadas del programa. Es al
  revés: una vez internacionalizado el programa, los términos y cadenas
  elegidos deberían introducirse en el manual, pero quizás no sea ni el
  mismo traductor ni el mismo equipo humano quien tenga que hacerlo.
• En el caso de un programa ya internacionalizado y localizado en
  nuestro idioma, el traductor se limitará a consignar las cadenas ya
  traducidas tal y como se presenten a ojos del usuario del programa.
  En ocasiones dichas cadenas dejan que desear y el traductor podrá, si
  lo desea, dejar constancia en una nota, pero nada más.
• Lo mismo sucede con las llamadas "cadenas de documentación" de
  funciones y otras entidades en algunos lenguajes de programación. Si
  el manual reproduce alguna de ellas, pero el programa o la interfaz
  interna de documentación no están internacionalizados, serán en idioma
  original como las verá el usuario; por tanto, el traductor debe
  mantener la reproducción en ese estado, sin traducir. Si lo considera
  muy importante, podría presentar una traducción adjunta entre
  corchetes como NdT.
• Algunos manuales incluyen el contenido del fichero Changelog o del News.
  Esos pasajes no se traducirán, salvo indicación contraria para casos
  particulares.

Notas del traductor

Las notas que el traductor, en su calidad de tal, decida incluir con
la pretensión de mantenerse en el trabajo final a consideración del
lector se pondrán provisionalmente entre corchetes, comenzando con
NdT:, así:

[NdT: ...]

Esto se hará inmediatamente antes o después del texto o pasaje que
suscite la nota, en párrafo aparte o inserto en el mismo flujo de
texto del párrafo, según conveniencia.

Las notas que pueda redactar el traductor en su calidad de técnico que
impliquen opinión propia se pondrán igualmente entre corchetes, pero
la T de Traductor quedará sustituida por las iniciales en mayúsculas
con las que se identifique a la persona en cuestión.

Primer pase

Primero la masa del texto

Primero se traduce la masa del texto, lo que suele llamarse su
"cuerpo", no las cabeceras o títulos, ni los ejemplos de cualquier
índole (código, presentación impresa, descripciones de enlaces, etc.)

Dudas y consideraciones

Las posibles dudas y comentarios y consideraciones del traductor se
señalarán, hasta nueva orden, de la siguiente manera:

Se crea una nueva línea dentro del mismo párrafo y en su comienzo se
escriben los tres caracteres siguientes, así:

-->

inmediatamente después continúa el vocablo o expresión o frase
originales que producen la duda. Un comentario directo del traductor
sobre esta duda irá entre corchetes, inmediatamente después en la
misma línea, si fuera el caso.

Los comentarios provisionales generales también irán entre corchetes,
sin necesidad de que representen una duda, pero igualmente aplicarán
esos tres caracteres para su pronta localización cuando se busquen. No
hace falta comenzar el texto entre corchetes con un "NdT" si no se
pretende mantener la nota en el trabajo final.

Si la señal de ancla se insertó en medio de un párrafo en el que sus
siguientes frases sí se traducen, éstas deben comenzar una nueva línea
pero mantenerse dentro de los límites del párrafo, para no perder la
anatomía de dicho párrafo y reajustarlo nuevamente en su día cuando se
resuelva la duda.

Títulos y cabeceras

Sólo cuando la masa del texto de cada sección esté traducida se
procede a traducir el título de esa sección, haciendo que, por tanto,
un título sin traducir sea un indicativo de que falta algo, y un
título traducido implicaría la traducción de su masa de texto interna,
pero no de los ejemplos.

Archivado provisional en bruto

Cuando el texto esté traducido hasta ese nivel, se procede a
reubicarlo provisionalmente en un sub-directorio llamado "EN-BRUTO".

Segundo pase

Cosas pendientes

Enlaces, índices, menús, etc

Se procede a traducir las descripciones de los menús, de los índices,
enlaces, etc. que sea posible en función de las características del
sistema de documentación que se esté empleando. Por ejemplo, en
Texinfo se pueden traducir las descripciones de las entradas de menú,
pero no los nombres de esas entradas, pues estos constituyen la
transcripción literal del nombre de los nodos en Info.

Variables meta-sintácticas en las descripciones de funciones, comandos, etc.

En los manuales de referencia de lenguajes y programas complejos o en
la explicación de las opciones de línea de comandos suelen aparecer
variables metasintácticas que se refieren a un valor que en su momento
adoptarán. En tales ocasiones, los nombres de la función, expresión,
etc, no pueden ser traducidos, pues pertenecen al lenguaje, pero sí lo
puede ser el texto adjudicado a las variables, argumentos, etc...

Esto lo he hecho con mucha frecuencia en el primer pase en bruto, y
otras veces lo dejaba, por aburrimiento, para un segundo pase, pues
rompe mucho el ritmo de traducción.

Protocolariamente sospecho que es mejor adjudicarlo al segundo pase,
no sólo para mejorar la fluidez del primero (en definitiva, cuando se
esté dando el primer pase ya hay que estar decidiendo cómo vamos a
traducir el interior de la variable, por aquello de la concordancia de
género y número que explico más abajo), sino sobre todo porque un
segundo pase dedicado exclusivamente a esos detalles se me antoja más
consistente y seguro, especialmente si se emplean técnicas de búsqueda
y reemplazo sistemáticas.

Breve excurso sobre el estilo cuando se usan estas variables meta-sintácticas

Es común (tanto en inglés como en sus traducciones en español) un
estilo encorsetado donde se trata a la variable meta-sintáctica como
un objeto en sí, sin atender al significado de la cadena que la
representa. Así, lo normal es ver cosas como:

The file @var{file} must have ... blablabla ...
El fichero @var{fichero} ha de tener ... blablabla ...

Esto es lo común, repetimos, pero no por ello menos horrible en
español y, estoy seguro, también en inglés. Si fuera tan solo un
asunto estilístico..., pero es que puede alcanzar niveles semánticos.
El grado de encorsetamiento llega a tales extremos en algunas páginas
man y en algunos manuales creados por desarrolladores, que tales
documentos se convierten en literalmente incomprensibles. La "sesudez
pseudo-científica" es mala consejera a la hora de redactar
documentación. Que levante la mano quien esté libre de la experiencia
de acudir con urgencia a una página man (la original inglesa o su
traducción española, da igual) para una solución rápida a, por
ejemplo, un asunto de argumentos de opciones y no se haya visto
repitiendo la lectura tres veces porque no ha entendido nada...

Como traductor, he repetido ese esquema en infinidad de ocasiones,
hasta que me cansé...

En la actualidad rompo sin pudor el encorsetamiento del original e
integro el texto de la variable en la plasticidad del idioma natural,
pues la propia marca que utilice el sistema de documentación (unas
comillas, unas etiquetas, etc.) mantienen intacta la referencia
metasintáctica, lo que permite que el lector comprenda que ese
`fichero' se refiere al fichero del que estemos hablando, y no a otro:

El @var{fichero} ha de tener ... blablabla ..."

Si es necesario, hago una traducción del texto interno de la variable
tal que en español encaje bien en el flujo de la frase, aunque sea a
costa de cargarme el original:

@defun delete-file @var{file-name}...

Primera traducción elemental:

@defun delete-file @var{nombre-fichero}...

Pero después me encuentro con esta frase:

The file name of @var{filename}...

Que tendría la siguiente traducción:

El nombre del fichero @var{nombre-fichero}...

Ufff, fatal, así que corrijo sin pudor:

@defun delete-file @var{fichero}...

Y ahora queda bien:

El nombre del @var{fichero}...

Esto implica en español el uso de los artículos necesarios, así como
las concordancias de género y número adecuadas. Hágase sin temor,
incluso preparando esos artículos determinados o indeterminados en
masculino o femenino, en singular o plural ya en la traducción en
bruto.

Así, por ejemplo:

If @var{string} does not...

tendría una primera traducción en bruto:

Si la @var{string} no...

Un caso real del manual de Emacs Lisp:

If the GIF file doesn't contain an image with index @var{index}...
Si el fichero GIF no contiene una imagen con _ese_ @var{índice}...
(En este caso es correcto porque se acaba de hablar de él)

Códigos de ejemplo

El habitual código de ejemplo que se presenta en la documentación
técnica sigue el mismo curso: las variables meta-sintácticas se
pueden traducir, así como los comentarios internos, las descripciones,
e incluso el texto de los posibles mensajes, si estamos hablando de
ejemplos imaginarios.

Tercer pase: Estilo

Además de las indicaciones previas, el traductor debería proceder a
ordenar las frases de acuerdo al castellano y no, como se observa tan
frecuentemente, con palabras españolas escritas en una estructura
gramatical propia del inglés (todo al revés).

No obstante, el traductor no ha de demorarse excesivamente en esto en
el primer pase en bruto. En el segundo pase puede refinar bastantes
cosas, pero tampoco ha de excederse en ello.

La revisión estilística debe pertenecer a un tercer pase, cuando todo
el texto esté completamente traducido y el traductor pueda leer el
texto con fluidez y sin preocupaciones.

Pero siempre se deberán respetar estos tres pases mínimos, incluso en
los casos en que el trabajo no justifique un exceso de recursos
humanos y sea el propio traductor quien haga la definitiva revisión
estilística.

Revisores

El proceso de las revisiones puede adoptar tres formas: dudas en
cuanto al inglés, decisiones en cuanto a los nuevos términos técnicos
acuñados y, por último, nuevamente estilísticas.

Cada una de ellas requeriría conocedores adecuados de la materia. Las
dos primeras pueden no presentarse. La última debería ser práctica
habitual, en la medida de lo posible, a través de una o varias
personas con menos conocimientos técnicos de cómputo y mayor
desenvoltura literaria.

Es misión del revisor estilístico la propuesta de variaciones, que
consignará del siguiente modo:

-- La propuesta debe ir entre doble corchete en línea propia que
comience con el siguiente símbolo, así:

==>[[VV:propuesta]]
(las mayúsculas iniciales se corresponden con las del revisor)

-- Al igual que en las notas provisionales de los traductores, la
propuesta debe quedar inserta dentro del flujo del párrafo, a no
ser que pretenda enmendar el párrafo completo, en cuyo caso puede
quedar añadida a su final.

Dependiendo de la entidad y magnitud de cada traducción, esta fase
puede ameritar su desglose o repetición a manos de más de un revisor.

Las propuestas de revisión estilística serán revisadas a su vez por el
traductor, para un concierto final.

En el caso de desacuerdos decidirá un árbitro designado por el
responsable de la sección.

Versiones

Al producto del primer pase le llamaremos versión alfa y siempre será
interna.

Al producto del segundo pase le llamaremos versión beta, que sería
dable como muestra provisional a los clientes o incluso al público,
dependiendo del contexto del trabajo, pero con expresa indicación de
que no es definitiva y carece de las revisiones.

Al producto del tercer pase le llamaremos versión 0.99, que
consideraremos la versión entregable a los revisores. Vuelve a ser de
aplicación lo dicho en el párrafo anterior.