PHPDOC-es

¿Qué hacer para traducir un fichero de documentación?

Vamos a explicar paso por paso que se debe hacer para traducir un fichero de la documentacion de PHP. Podeis encontrar informacion detallada sobre como el CVS esta organizado y como se usa en la pagina con informacion sobre el CVS.

Crear un directorio donde bajarse el modulo phpdoc-es (p.ej: CVSDIR.):
```
 [rafael@home]$ mkdir CVSDIR
 [rafael@home]$ cd CVSDIR
```
Definir las variables CVSROOT y EDITOR (Estas variables se pueden definir una sola vez en el fichero de configuracion de vuestro interprete de comandos. Por ejemplo para Bash se usa el fichero ~/.bash_profile)
```
 [rafael@CVSDIR]$ export CVSROOT=:pserver:[usuario]@cvs.php.net:/repository
 [rafael@CVSDIR]$ export EDITOR=emacs
```
Conectarse al CVS de php.net.
```
 [rafael@CVSDIR]$ cvs login
```
Bajarse el modulo phpdoc-es (Esto solo lo tenemos que hacer la primera vez, si ya nos hemos bajado el modulo, tendremos que hacer un UPDATE):
```
 [rafael@CVSDIR]$ cvs co phpdoc-es
```
Entrar en el directorio del modulo phpdoc-es y de la traduccion al español (Este es el directorio donde trabajaremos):
```
 [rafael@CVSDIR]$ cd phpdoc-es/es/
```
Editar el fichero translation.xml y actualizarlo con los ficheros en los que vayamos a trabajar. Vamos a revisar, por ejemplo, el fichero bookinfo.xml. Añadimos una linea con la informacion del fichero bookinfo.xml.
```
 <file name="bookinfo.xml" person="rafael" type="review" date="04.05.2003"/>
```
Los valores de los otros campos dependen del colaborador y del dia. Type puede tener los siguientes valores: "review" y "translation". La informacion registrada en el fichero translation.xml ayuda a generar una parte de la informacion mostrada en revcheck.html.gz.
Hacemos un COMMIT al CVS para que los demas colaboradores sepan que estamos trabajando en el fichero bookinfo.xml
```
 [rafael@es]$ cvs ci translation.xml
```
Editamos el fichero a revisar phpdoc-es/es/bookinfo.xml en nuestro editor de textos preferido.
El fichero phpdoc-es/es/bookinfo.xml tiene 2 lineas al principio que son importantes para controlar el estado de la traduccion. La primera se actualiza automaticamente cuando hacemos un COMMIT al CVS. La segunda la tenemos que actualizar a mano cuando terminemos de traducir/revisar el fichero, el valor despues de EN-Revision: equivale al valor que encontramos despues de $Revision: en la version inglesa del fichero en que esta basada la revision. Una vez revisado el fichero phpdoc-es/es/bookinfo.xml tendria los valores
```
 
 
```
Y phpdoc-es/en/bookinfo.xml (que no hemos cambiado, solo leido. Este es el fichero en el que nos basamos para actualizar phpdoc-es/es/bookinfo.xml):
```
 
```
Traducimos lo que se tenga que traducir (mas informacion en el apartado "Convenciones") sin cambiar la estructura del fichero.
Una vez terminada la traduccion tendremos que hacer un COMMIT al CVS con los cambios que hemos hecho en el directorio phpdoc-es/es/
```
 [rafael@es]$ cvs ci bookinfo.xml
```
O si hemos cambiado mas de un fichero y no queremos hacer un COMMIT por fichero podemos hacer lo siguiente:
```
 [rafael@home]$ cd phpdoc-es
 [rafael@phpdoc-es]$ cvs ci es/
```
Cuando termineis de trabajar con el CVS teneis que desconectaros:
```
 [rafael@CVSDIR]$ cvs logout
```
Bueno esto es todo, discusiones sobre que se va a traducir o quien se encarga de una parte u otra, en la lista de distribucion doc-es@lists.php.net.

Convenciones

Existen una serie de elementos en un fichero de documentacion que no tenemos que traducir ni cambiar. Por regla general podemos decir que NO traduciremos o cambiaremos:

Todo lo que se encuentre entre los signos < y >.
Entidades, definiciones que empiezan con el simbolo & y terminan con el simbolo ;
Nombres de funciones.
Nombres de parametros de configuracion.
Nombres propios.
Nombre de los ficheros ficheros.

Un ejemplo nos aclarara mucho las cosas. Por ejemplo el fichero phpdoc-es/en/preface.xml con el siguiente contenido:

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->

 <preface id="preface">
  <title>Preface</title>

  <abstract>
   <simpara>
    <acronym>PHP</acronym>, which stands for "PHP: Hypertext
    Preprocessor" is a widely-used Open Source general-purpose
    scripting language that is especially suited for Web
    development and can be embedded into HTML. Its syntax draws
    upon C, Java, and Perl, and is easy to learn. The main goal of
    the language is to allow web developers to write dynamically
    generated webpages quickly, but you can do much more with PHP.
   </simpara>
  </abstract>

 <para>
   This manual consists primarily of a <link linkend="funcref">
   function reference</link>, but also contains a 
   <link linkend="langref">language reference</link>, explanations
   of some of PHP's major <link linkend="features">features</link>, 
   and other <link linkend="appendixes">supplemental</link> 
   information.
  </para>

  <para>
   You can download this manual in several formats at <ulink
   url="&url.php.docs;">&url.php.docs;</ulink>.  The <ulink 
   url="&url.php.downloads;">downloads</ulink> are updated as
   the content changes. More information about how this manual is 
   developed can be found in the  <link linkend="about">'About the 
   manual'</link> appendix.
  </para>
  
  <para>
   See also <link linkend="history">PHP History</link>
  </para>
 </preface>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

Quedaria traducido en el fichero phpdoc-es/es/preface.xml como:

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- EN-Revision: 1.26 Maintainer: rafael Status: ready -->

 <preface id="preface">
  <title>Prefacio</title>

  <abstract>
   <simpara>
    <acronym>PHP</acronym>, acrónimo de "PHP: Hypertext
    Preprocessor", es un lenguaje "Open Source" interpretado de alto
    nivel, especialmente pensado para desarrollos web y el cual puede
    ser embebido en páginas HTML. La mayoría de su
    sintaxis es similar a C, Java y Perl y es fácil de
    aprender.  La meta de este lenguaje es permitir escribir a los
    creadores de páginas web, páginas dinámicas
    de una manera rápida y fácil, aunque se pueda hacer
    mucho más con PHP.
   </simpara>
  </abstract>

  <para>
   Este manual contiene principalmente una <link
   linkend="funcref">referencia de funciones</link> PHP, tambien
   contiene una <link linkend="langref">referencia del
   lenguaje</link>, explicaciones de <link
   linkend="features">caracteristicas importantes</link> de PHP y
   alguna <link linkend="appendixes">información
   suplementaria</link>.
  </para>
  
  <para>
   Este manual se puede conseguir en diferentes formatos en <ulink
   url="&url.php.docs;">&url.php.docs;</ulink>. Estos <ulink
   url="&url.php.downloads;">ficheros</ulink> son actualizados a
   medida que el manual va cambiando. Más información
   sobre como este manual es desarrollado puede encontrarse en el
   apéndice <link linkend="about">'Sobre este manual'</link>.
  </para>

  <para>
   Ver tambien <link linkend="history">Historia de PHP</link>
  </para>
 </preface>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

Podeis observar que no hemos cambiado la estructura del fichero y que los elementos que no deben de cambiar no han sido traducidos o cambiados. A continuación teneis una serie de directrices básicas a seguir en la traducción del manual.

Lenguaje

Los traductores deberán tender a un castellano lo más neutro e internacional posible. Deberán omitirse expresiones locales o jergas. Dada la magnitud del trabajo de traducción y su estado actual de progreso, por el momento no parece factible el llevar a cabo la traducción simultánea de versiones localizadas.

No hace falta decir que se deberá intentar mantener una buena gramática y una ortografía correcta.

En caso de duda sobre alguna expresión, no está de más consultar a los demás miembros del grupo.

Términos específicos

Los siguientes términos deben ser traducidos siempre de la misma forma, con el fin de conseguir una traducción homogénea.

file --> archivo
array --> matriz

(La lista irá creciendo)

Términos intraducibles

Aquí se incluyen aquellos términos que por contexto, uso o anglicismo no deben traducirse. Es probable que algunas de estas palabras tengan un equivalente correcto en castellano, pero debido al contexto de su uso, el término inglés ofrece mayor claridad:

script
multi-thread

(La lista también irá creciendo)