# The &kmyapplication; Handbook

## Introduction

Note: The English translation of this handbook is a work in progress!

&kmyapplication; is an utility oriented to &kde; translation teams that can manage multiple local copies of the &kde; repository and have them updated. It can also generate projects to use with &lokalize;, perform several checks and corrections using &pology; and other tools, generate a compressed file with the changes made and send it to the team coordinator or to the &kde; repository (if you have write access to it).

It works on &kde; 4.4.0 or later, although it is possible that the program will compile fine and work properly with earlier versions of &kde; desktop.

## The main screen of &kmyapplication;

The main window of &kmyapplication; shows two sections: a translation project list on the left and a central working window that contains four tool tabs:

- Output. The main panel of this tab is merely informative, as it shows notification and error messages from the various tools executed on your local copy of the &kde; repository. This tab also contains two secondary panels on the right side. The upper one shows detailed information about important changes made on your local copy of the repository (files added and removed, successful merges and conflictive merges), while the lower one shows a full overview of the local copy of the &kde; repository. The three panels of this tab allow you to perform several operations on single files using context menus.

- Statistics. This tab shows an overview with statistics about the current project (information about the total number of messages in each file, and also the number of translated, fuzzy and pending messages). If you double clic a file, it will be open in &lokalize;. This view have also a context menu.

- Images. This tab contains a tool that allows you manage the currently selected project's documentation images.

- Synchronization. This tab contains a tool that allows you synchronize several translations in different branches.

Here's a screenshot of &kmyapplication; Screenshot

### More &kmyapplication; features

In essence, this program is used for executing several `svn` commands and &pology; checks. The voice of experience shows that the greatest part of the novel translators integrated in a translation team, usually have always the same doubts and make always the same mistakes. &kmyapplication; tries to ease these translators' lives doing the hard work for them, as download a copy of the repository with the assigned job, get it up to date, generate projects to use in &lokalize;, make some automatic checks and correctios, package translated files and send them to the team coordinator. It can also download the team's glossary, to be used by &lokalize;, and the &pology; toolset. In addition, it allows you to easily work with the screenshots required to translate the application's documentation that are part of your project.

## First run

The first time that you use &kmyapplication;, it will launch two assistants to:

- Properly configure the application. This is only necessary the first time you run the program and is done with the help of a set up assistant.

- Create a working project. You need a project to use the program. As the first time you run it there is no project, it will launch an assistant to create a new project.

## How the program works

A working session of &kmyapplication; consists basically in updating your local copy of the repository, launch &lokalize; to translate, optionally perform several checks with &pology; and sending your work to the team coordinator or to the &kde; repository (if you have write access on it).

If we are translating documentation, we also need to generate the related docbook files and manage the required screenshots for the translated help handbooks.

&kmyapplication; have several utilities that can be helpful to you. Amongst them, there are menu options that allow you to:

- Show the modified files on your working local copy after a translation session with &lokalize;.

- Show the differences between a modified local file and its related version in the repository.

- Undo the changes made in a local file.

- Add new translation files (created using &lokalize;) to the local copy of the repository.

- Resolve conflicts inside translation files.

- Check the validity of the translated messages.

- Check the spelling and the language rules in the local copy of the repository.

- Search for text in the translation files.

### The set up assistant

La primera vez que ejecute &kmyapplication; se lanzará un asistente que le ayudará a configurar el programa. Este asistente consta de cinco páginas idénticas a las del diálogo de configuración del programa (al que puede acceder usando la opción del menú Settings Configure &kmyapplication;).

Captura de pantalla del asistente de configuración de &kmyapplication; (sección General) Sección General del asistente de configuración de &kmyapplication;

La primera página del asistente solicita su nombre y varias direcciones de correo electrónico: la suya (que se usará junto a su nombre para etiquetar sus traducciones), la del coordinador de su equipo (que usará para enviarle los archivos traducidos) y la de la lista de distribución de su equipo (que también se usará para etiquetar los archivos que traduzca). También se le solicitará la dirección web del glosario de su equipo. Este glosario se puede descargar en la carpeta raíz de cada proyecto de traducción que gestione con el programa.

Captura de pantalla del asistente de configuración de &kmyapplication; (sección SVN) Sección SVN del asistente de configuración de &kmyapplication;

La segunda página del asistente solicita algunos parámetros relacionados con &subversion;. Todos ellos tienen un valor predeterminado, por lo que es muy probable que no necesite modificarlos. Aquí se solicita la ubicación de la orden que se usará para acceder al repositorio de &kde; y los colores que se usarán para mostrar información visual relevante en la ventana principal del programa cuando acceda al repositorio de &kde;.

Captura de pantalla del asistente de configuración de &kmyapplication; (sección &pology;) Sección &pology; del asistente de configuración de &kmyapplication;

La siguiente página del asistente contiene información sobre &pology;. Desde aquí puede descargar este conjunto de utilidades e instalarlo en su sistema. Para ello, pulse el botón Download &pology;. Una vez finalizada la descarga, se modificará el campo etiquetado &posieve; command para que haga referencia a la ubicación donde acaba de instalar &pology;. Esta página también contiene una opción que permite comprobar de forma automática las cabeceras de los archivos que se añadan a la copia local del repositorio.

Captura de pantalla del asistente de configuración de &kmyapplication; (sección Estadísticas) Sección Estadísticas del asistente de configuración de &kmyapplication;

La página relativa a la pestaña de estadísticas del programa contiene opciones para actualizar automáticamente las estadísticas del proyecto: puede ser cada vez que se carga un proyecto (esto incluye cuando se selecciona uno en la lista lateral izquierda y cuando se inicia el programa) y cada vez que se actualiza la copia local de un proyecto. También puede seleccionar los distintos colores que se usarán para mostrar las estadísticas del proyecto de una forma visual. Además, existe una opción con la que podrá decidir si las carpetas de las estadísticas se despliegan automáticamente para mostrar su contenido o no.

Captura de pantalla del asistente de configuración de &kmyapplication; (sección Otras preferencias) Sección Otras preferencias del asistente de configuración de &kmyapplication;

La última página del asistente contiene opciones que permiten realizar ciertos automatismos, como comprobar nuevas versiones del programa para permitir actualizar la versión que se esté utilizando o comprobar si existe una nueva versión de &pology; cada cierto tiempo. Aquí también podrá seleccionar si se debe actualizar la copia local del proyecto y su glosario cuando se inicia el programa, o si se debe recordar el último proyecto usado en la última sesión de trabajo. También podrá seleccionar el editor de texto que se usará por omisión con el programa.

### Creating projects

&kmyapplication; trabaja con proyectos de traducción. La primera vez que ejecute el programa no tendrá todavía ninguno, por lo que, tras el asistente de configuración, se lanzará un nuevo asistente que le permitirá crear su primer proyecto. Es muy importante que dispongamos de una conexión activa a Internet en el momento de ejecutar este asistente, ya que algunos de sus campos se rellenan de forma automática accediendo al repositorio de &kde;.

Captura de pantalla del asistente para crear un nuevo proyecto (sección para el nombre del proyecto) Sección para el nombre del proyecto del asistente de creación de un nuevo proyecto

Tras la página de introducción del asistente se mostrará otra que solicita los datos básicos del proyecto de traducción. El nombre del proyecto debería ser una palabra corta que describa el contenido del proyecto, como un nombre de paquete. Este nombre identificará al proyecto de forma única en la lista de proyectos que hay en la parte izquierda de la ventana principal del programa. También debe proporcionar la ruta de la carpeta base local del proyecto, que contendrá toda la información sobre el mismo. La lista desplegable de idiomas se actualizará automáticamente cuando se muestre esta página del asistente. En ella debemos seleccionar el idioma con el que vamos a trabajar. El campo que contiene la dirección de correo electrónico de la lista de distribución de su equipo ya tendría que ser correcto, pues usa la información introducida en el asistente de la primera ejecución del programa. En caso de no ser correcta, introduzca en él la dirección de correo electrónico de la lista de distribución de su equipo de traducción.

Otra información relativa al idioma son las Comillas que se deben usar con la opción de Comillas elegantes del menú del programa. Debe seleccionar las comillas simples y las comillas dobles que use su idioma.

Captura de pantalla del asistente para crear un nuevo proyecto (sección para el acceso al repositorio) Sección para el acceso al repositorio del asistente de creación de un nuevo proyecto

La siguiente página del asistente permite seleccionar el tipo de acceso que se usará para acceder al repositorio de &kde;. Este acceso puede ser anónimo o personalizado. El acceso anónimo es el que deben utilizar los usuarios que no disponen de permiso de escritura en el repositorio; se conecta a la dirección svn://anonsvn.kde.org/ con permiso de lectura. El acceso personalizado necesita que se indique el URL completo que suele usar el usuario con permiso de escritura en el repositorio (por ejemplo, svn+ssh://svn@svn.kde.org/home/kde/).

Captura de pantalla del asistente para crear un nuevo proyecto (sección para seleccionar la subrama del repositorio que se va a usar) Sección para la subrama a usar del asistente de creación de un nuevo proyecto

En esta página deberá seleccionar qué subrama del repositorio se va a usar para descargar los paquetes asignados. En la actualidad existen dos subramas activas en la rama trunk del repositorio de &kde;: l10n-kde4 (para todo lo relacionado con la traducción de KDE4) y l10n-kf5 (para todo lo relacionado con la traducción de KF5). Elija una de las opciones trunk/l10n-kde4 o trunk/l10n-kf5, según sus necesidades.

De forma alternativa, &kmyapplication; también permite trabajar con las ramas archivadas de &kde;. Estas ramas residen en la dirección branches/KDE/x.xx/kde-l10n. Si necesita trabajar en alguna de estas ramas, deberá seleccionar la versión de &kde; a descargar.

Captura de pantalla del asistente para crear un nuevo proyecto (sección para la selección de paquetes a descargar) Sección para la selección de paquetes a descargar del asistente de creación de un nuevo proyecto

En la siguiente página del asistente se nos pedirá que seleccionemos los paquetes que tenemos asignados para traducir. Para ello habrá que marcar las casillas que hay junto al nombre de cada paquete a descargar. La lista contiene dos columnas: la de la izquierda es para los mensajes de la interfaz y la de la derecha para la documentación de cada paquete. Por ejemplo, si tenemos asignada la traducción de los mensajes y la documentación del paquete extragear-network marcaremos las dos casillas que hay con ese nombre en la misma fila. Si necesitamos descargar todos los paquetes del repositorio marcaremos únicamente la casilla Todo que hay al principio de la lista. Los paquetes seleccionados se descargan en la carpeta base de nuestro proyecto de traducción y mantienen la misma estructura que en el repositorio de &kde;.

Si en la página anterior del asistente seleccionó descargar paquetes de la rama trunk, la carpeta base contendrá una subcarpeta denominada trunk y otra llamada branches/stable. Hay que tener en cuenta que los paquetes que se muestran pertenecen únicamente a la rama trunk del repositorio de &kde;, aunque se descargarán, además, los de la rama stable (siempre que tengan el mismo nombre que los seleccionados). En el caso de que se seleccionen todos los paquetes, se descargarán las traducciones completas de ambas ramas del repositorio.

Si, por el contrario, seleccionó descargar paquetes de una versión archivada de &kde; en la página anterior del asistente, los paquetes que se muestren en la lista de esta página serán únicamente los correspondientes a dicha versión de &kde;. Así mismo, tras finalizar la descarga, la carpeta base del proyecto contendrá una única rama branches/KDE.

Captura de pantalla del asistente para crear un nuevo proyecto (sección para el proyecto de &lokalize;) Sección para el proyecto de &lokalize; del asistente de creación de un nuevo proyecto

La última página del asistente contiene varias casillas para diversos propósitos. Lo más usual es que se vaya a utilizar &lokalize; con un par de proyectos de traducción (uno para cada rama del repositorio). Si se marca la casilla crear proyectos de &lokalize;, el asistente creará estos dos proyectos de forma automática. Ambos tendrán el mismo nombre que el proyecto de traducción que estamos creando, pero cada uno tendrá el sufijo de la rama a la que hace referencia (por ejemplo, si nuestro proyecto se llama utils, el asistente creará los proyectos utils-stable.lokalize y utils-trunk.lokalize). Estos proyectos de &lokalize; se crean en la misma carpeta base de nuestro proyecto de traducción.

También existe una opción para descargar el glosario de su equipo cuya dirección se introdujo en el asistente de la primera ejecución de &kmyapplication; (o en el diálogo de configuración del programa). Este glosario será el que use &lokalize; para traducir cada proyecto. Como el glosario se copia en la carpeta base de cada proyecto de traducción, es posible usar diferentes glosarios para cada uno de ellos.

La opción descargar directorios adicionales permite descargar los directorios scripts y docs del idioma seleccionado de cada rama del repositorio de &kde;. Estos directorios son necesarios a la hora de generar documentación.

Tras esta página se mostrará la última página del asistente, donde puede seleccionar la casilla comenzar la descarga al salir del asistente, con lo que se descargarán los paquetes seleccionados en cuanto finalice el asistente para crear un nuevo proyecto de traducción (el glosario se descargará si su opción está seleccionada, independientemente del estado de esta casilla).

#### A remark about &lokalize; projects

Los proyectos de &lokalize; que crea &kmyapplication; utilizan una característica especial de &lokalize; que permite sincronizar las traducciones de ambas ramas del repositorio. Es decir, si se modifica una cadena de texto en un archivo de una rama y en la otra rama existe un archivo con el mismo nombre y contiene también la misma cadena de texto, también se modificará en dicha rama.

Esta funcionalidad resulta muy práctica, pero tiene un pequeño inconveniente en las versiones de &lokalize; anteriores a la 1.2: si en la otra rama existe un archivo con el mismo nombre que no contiene la cadena modificada, se modificarán las cabeceras de dicho archivo. En la práctica, esto significa que tendremos un archivo modificado para subir al repositorio en la otra rama, cuando en realidad solo se han modificado algunas de sus cabeceras.

Este falso positivo de la otra rama se puede detectar y deshacer muy fácilmente desde el programa. Para ello, listamos primero los archivos modificados usando la opción del menú Tools Show changes. A continuación, seleccionamos el archivo sospechoso en la lista de archivos locales modificados que hay a la derecha de la ventana principal el programa y elegimos la opción del menú Tools Local file Differences with repository. En la ventana principal se mostrarán las líneas del archivo que difieren con su copia remota, con lo que podremos decidir si realmente se trata de un falso positivo. Si lo fuera, podemos deshacer las modificaciones locales seleccionando la opción del menú Tools Local file Undo changes. También se puede revertir el falso positivo usando desde la consola la orden `svn revert` (especificando la ruta del archivo afectado).

De cualquier modo, si no desea usar esta característica de &lokalize; desde los proyectos que crea &kmyapplication;, será necesario modificar los proyectos de &lokalize; después de su creación. Se puede hacer esto manualmente entrando en la carpeta base de la copia local y editando allí dichos archivos (los que tienen la extensión .lokalize), o bien abriendo el proyecto para una rama en &lokalize; y modificando allí su configuración, repitiendo a continuación el mismo proceso con la otra rama.

### Working session

Una vez bien configurado el programa y con uno o más proyectos creados, la rutina de trabajo consiste en seleccionar un proyecto de la lista que hay en la parte izquierda de la ventana del programa, actualizar la copia local del repositorio, traducir usando el programa &lokalize;, verificar nuestro trabajo y enviar los archivos modificados al coordinador del equipo o al repositorio de &kde; (si se posee permiso de escritura en él).

#### Updating your local copy

Tras seleccionar un proyecto, la copia local del repositorio se puede actualizar usando la opción del menú Tools Update local copy. Tras ejecutarla se mostrará un diálogo para seleccionar qué partes de nuestra copia local deseamos actualizar. En la ventana central del programa se irán mostrando los mensajes de información (y los posibles errores) que genera la orden `svn`, con sus colores correspondientes (especificados en el diálogo de configuración del programa). A la derecha de la ventana de salida existe otra ventana con una vista en forma de árbol que mostrará los cambios importantes que tienen lugar al actualizar nuestra copia local del repositorio. Por cambios importantes se entiende los archivos que han sido añadidos o eliminados, los archivos que se han mezclado con nuestros cambios de forma correcta o los que han generado un conflicto. Por omisión, esta opción dispone de un botón en la barra de herramientas del programa.

En el menú también existe una opción para checkout the local copy del repositorio. Esta opción estará activa únicamente en el caso de que aún no hayamos descargado la copia local del repositorio (por ejemplo, al finalizar el asistente de creación de proyectos).

Estos procesos se pueden interrumpir usando la opción del menú File Cancel process o su correspondiente botón en la barra de herramientas.

#### Translating with &lokalize;

El menú del programa contiene sendas opciones para abrir la rama trunk o la rama stable de nuestro proyecto de traducción en &lokalize;. Estas opciones estarán activas únicamente en el caso de que hubiéramos optado por generar los archivos de proyecto para &lokalize; en el asistente de creación de un nuevo proyecto de traducción. Estas opciones disponen de sus respectivos botones en la barra de herramientas de forma predeterminada.

#### Checking with &posieve;

&posieve; es un útil script del conjunto de utilidades &pology; que permite realizar gran cantidad de verificaciones y correcciones en nuestras traducciones de forma muy sencilla. El menú Tools Checks de &kmyapplication; contiene diversas opciones que lanzan algunas de estas utilidades sobre todos los paquetes seleccionados de nuestra copia local del repositorio. También están disponibles en el menú de contexto del panel Local copy, desde donde se pueden ejecutar sobre archivos PO individuales.

Entre ellas, disponemos de una opción llamada Fancy quotes que sustituye de forma inteligente pares de comillas simples o dobles por sus equivalentes en el idioma de destino.

La opción más importante permite comprobar la validez de los mensajes traducidos en los archivos PO. Es necesario corregir todos los errores de los que informe esta utilidad, por lo que no se debería hacer ningún envío de traducciones al coordinador sin haber realizado al menos esta comprobación.

Un par de opciones muy interesantes son las que comprueban la ortografía y las reglas del idioma al que estamos traduciendo.

También existen un par de opciones de limpieza de los archivos de traducción: una de ellas elimina los mensajes obsoletos (que ya no se usan en el archivo de traducción) y otra los mensajes previos (los que han cambiado por otros recientemente).

Todas estas opciones se ejecutan únicamente en los directorios que contienen traducciones (messages y docmessages) de nuestra copia local del repositorio.

Todas estas verificaciones se pueden interrumpir usando la opción del menú File Cancel process o su correspondiente botón en la barra de herramientas.

#### Sending changes

Una vez finalizado nuestro trabajo, llega la hora de generar un archivo comprimido con las modificaciones de ambas ramas para enviárselo al coordinador del equipo por correo electrónico. La opción del menú Tools Send changes se encarga de realizar todo este trabajo de forma automática. Cuando se ejecuta, detecta los archivos que hayamos modificado en nuestra copia local del repositorio, los empaqueta en un tarball temporal (mostrando su contenido en la ventana de Modified local files que hay a la derecha de la ventana de salida de mensajes) e invoca a nuestro programa de correo electrónico, mostrando una ventana de edición de mensaje con la dirección de correo del coordinador del equipo y el archivo que contiene las modificaciones ya adjunto. Bastará con escribir un corto texto y enviar el mensaje para dar por finalizado nuestro trabajo.

Si se posee permiso de escritura en el repositorio de &kde;, la anterior opción del menú cambiará a Tools Commit changes. Cuando se ejecuta esta acción se muestra un diálogo para cada rama existente donde se pueden seleccionar los archivos modificados que se desea enviar al repositorio de &kde; y escribir un mensaje que describa el contenido del envío.

### Utilities

El menú Tools de &kmyapplication; contiene diversas opciones que le ayudarán a gestionar su copia local del repositorio de &kde; con cierta comodidad. Entre ellas destacan una opción para mostrar el estado actual de nuestra copia local y otra para ayudarle a resolver los conflictos que se pudieran haber generado durante la actualización de dicha copia local.

La sección sobre el asistente para la creación de proyectos contiene un ejemplo del uso combinado de varias de estas utilidades.

#### Local copy status

En cualquier momento podemos ver el estado de nuestra copia local del repositorio usando la opción del menú Tools Show changes, que muestra una lista de los archivos modificados. Internamente, esta acción ejecuta la orden `svn status` sobre nuestra copia local, por lo que los posibles estados de los archivos modificados son los mismos que produce dicha orden.

Los archivos modificados se mostrarán con un código de color en la lista que hay a la derecha de la ventana principal del programa. Esta lista dispone de un menú de contexto que permite realizar diferentes acciones sobre los archivos que contiene.

#### Resolving conflicts

A veces, tras actualizar nuestra copia local del repositorio, observaremos que se ha producido algún conflicto. Normalmente, la aparición de un conflicto se produce cuando hemos modificado algún archivo de nuestra copia local y también se ha modificado la copia remota del mismo. Si los cambios de ambos archivos son compatibles, una actualización fusionará ambos archivos sin problemas (aparecen marcados con la letra G al actualizar la copia local del repositorio en &kmyapplication;). Pero si los cambios son incompatibles (por ejemplo, porque se hayan modificado las mismas cadenas en ambos archivos), se generará un conflicto (que aparecerá marcado con la letra C al actualizar la copia local en &kmyapplication;).

&kmyapplication; dispone de un par de opciones que pueden resultar muy útiles para tratar con archivos con conflictos. Para resolver conflictos, &kmyapplication; utiliza la utilidad &kdiff3;. Si no la tiene instalada, tendrá que resolver los conflictos de forma manual.

Tras una actualización, es posible seleccionar un archivo con conflictos en la lista que hay a la derecha de la ventana principal del programa (que aparecerá resaltado con el color que hayamos seleccionado en la configuración del programa) y ejecutar la opción del menú Tools Local file Resolve conflict. Esto lanzará &kdiff3; con los tres archivos necesarios existentes en el mismo subdirectorio donde reside el archivo con conflictos seleccionado. &kdiff3; puede resolver de forma automática casi la totalidad de los conflictos, aunque necesitará de su ayuda con los que no pueda resolver. Al finalizar, guarde todo antes de salir de &kdiff3;. Si está seguro de que ha resuelto todos los conflictos satisfactoriamente, &kmyapplication; se ofrecerá para marcar el conflicto como resuelto en su copia local del repositorio.

Si hemos optado por resolver el conflicto de forma manual desde fuera de &kmyapplication;, también se nos ofrece la opción del menú Tools Local file Mark as resolved , que eliminará el estado de conflicto en el archivo seleccionado en la lista de cambios que hay a la derecha de la ventana principal del programa.

#### Showing differences with respect to the remote copy

Tras usar la opción para mostrar el estado de nuestra copia local del repositorio, podemos visualizar las diferencias entre cualquier archivo modificado y su copia remota en el repositorio de &kde;. Para ello seleccionaremos el archivo en cuestión en la lista de archivos modificados y ejecutaremos la opción del menú Tools Local file Differences with repository . En la ventana principal se mostrarán las diferencias entre ambas versiones del archivo seleccionado usando un sencillo código de colores.

#### Undo changes

Es posible que en algún momento no estemos conformes con los cambios que hemos realizado en algún archivo de nuestra copia local del repositorio (por ejemplo, al usar la sincronización de &lokalize;). Podemos deshacer estos cambios mostrando primero el estado actual de nuestra copia local, seleccionando luego el archivo en cuestión y ejecutando después la opción del menú Tools Local file Undo changes.

Esta opción también permite borrar archivos añadidos a nuestra copia local del repositorio siempre que no se hayan enviado todavía al repositorio principal.

#### Adding files to the local copy

Cuando traducimos con &lokalize; un archivo que no existe previamente en nuestra copia local del repositorio, se genera su correspondiente archivo PO, pero no se añade a nuestra copia local del repositorio (es decir, permanece ajeno al sistema de control de versiones). Aunque esto no es demasiado importante, podemos añadirlo seleccionándolo en la lista de archivos que se genera al mostrar el estado actual del repositorio y eligiendo la opción del menú Tools Local file Add to local copy.

#### Deleting files from the local copy

A veces es necesario borrar algún archivo existente en nuestra copia local del repositorio, bien porque ya no está presente en ella o porque nos hemos equivocado añadiéndolo por error al repositorio. Podemos borrar un archivo de nuestra copia local seleccionándolo en la lista de archivos que se genera al mostrar el estado actual del repositorio y eligiendo la opción del menú Tools Local file Delete from local copy.

Si el archivo que queremos borrar estuviera presente únicamente en nuestra copia local del repositorio (porque lo hemos añadido a ella pero no lo hemos enviado al repositorio principal), podemos eliminarlo de ella seleccionandolo en la lista de archivos que se genera al mostrar el estado actual del repositorio y usando después la opción del menú Tools Local file Undo changes.

#### Generating documentation

Si estamos traduciendo documentación de aplicaciones, nos será de gran utilidad la opción del menú Tools Generate documentation . Con ella podemos generar la documentación de una aplicación, de un paquete o de una rama completa. En la ventana principal del programa se mostrará lo que está haciendo esta opción y los posibles errores que pudieran producirse durante el proceso.

Captura de pantalla de la herramienta que se usa para generar documentación Captura de pantalla de la herramienta de generación de documentación

#### Downloading documentation

La opción del menú Tools Download documentation permite descargar la documentación original (en inglés) de uno o más paquetes. Esta documentación se descarga en el directorio base de nuestro proyecto de traducción, dentro de un subdirectorio llamado `documentation`.

#### Cleaning, upgrading and relocating the local copy

Estas tres opciones del menú permiten tratar ciertos estados de la copia local que pueden hacer que quede temporalmente inservible.

- Tools Clean local copy . A veces es posible que se produzca un error de comunicación mientras se están enviando o recibiendo cambios del repositorio. En estos casos, es probable que acabemos con una copia local bloqueada que produzca un error la próxima vez que necesitemos actualizar o enviar modificaciones. Para corregir esta situación se puede usar esta opción del menú.

- Tools Upgrade local copy . Otra situación que impide el uso de nuestra copia local se puede dar cuando hemos obtenido la copia local del repositorio con una versión de la orden `svn` y, posteriormente, actualizamos dicha orden a otra versión posterior. En este caso es posible que el formato de los metadatos guardados en nuestra copia local no sea compatible con el de la nueva versión de la orden `svn`. Para corregir esta situación se puede usar esta opción del menú.

- Tools Relocate local copy . También es posible que hayamos obtenido nuestra copia local de un URL que se ha modificado posteriormente de forma parcial o total, o que hayamos cambiado nuestro modo de acceder a la copia remota del repositorio. Como es lógico, será necesario cambiar el URL de la copia remota almacenado en los metadatos de la copia local antes de poder acceder de nuevo al repositorio. Para corregir esta situación se puede usar esta opción del menú.

#### Searching PO files

A veces necesitaremos encontrar una determinada palabra o frase dentro de un determinado archivo PO cuyo nombre ignoramos. Para ello usaremos la opción del menú Tools Search in PO files. El asistente que muestra esta opción permite muchas posibilidades a la hora de realizar este tipo de búsquedas.

Captura de pantalla de la herramienta de búsqueda de &kmyapplication; Captura de pantalla de la herramienta de búsqueda

La siguiente página del asistente de búsqueda le permite seleccionar en qué carpetas se llevará a cabo la misma.

Selección de directorios donde usar la búsqueda de &kmyapplication; Selección de directorios donde usar la herramienta de búsqueda

### Statistics

La pestaña Statistics de la ventana principal de &kmyapplication; muestra un resumen con las estadísticas del proyecto actual. La información se muestra en forma un árbol con la estructura de la copia local e incluye datos sobre el número total de mensajes de cada archivo, y las cantidades y los porcentajes de los mensajes traducidos, los mensajes dudosos y los mensajes sin traducir, tanto de los distintos paquetes como de los archivos individuales.

Captura de pantalla de la pestaña Estadísticas de &kmyapplication; Captura de pantalla de la pestaña Estadísticas

Si se hace doble clic sobre un nombre de archivo, se abrirá dicho archivo en Lokalize.

Si el archivo de traducción no existiera todavía (si su nombre aparece sobre un fondo negro y tiene la extensión `.pot`), se inicializará su correspondiente archivo `.po` y se abrirá en Lokalize. Este color (negro por omisión) se puede modificar en el diálogo de preferencias del programa.

Si un archivo aparece sobre fondo rojo significa que está huérfano; es decir, que carece del correspondiente archivo de plantilla en la copia local (con la extensión `.pot`). Esto indica que dicho archivo debe borrarse de la copia local del repositorio, puesto que su plantilla se ha eliminado. Este color (rojo por omisión) se puede cambiar en el diálogo de preferencias del programa.

#### The statistics context menu

La lista de archivos contiene un menú de contexto (disponible únicamente para los nombres de archivos) que contiene varias opciones que nos permiten:

- Open in Lokalize el archivo seleccionado. Si el archivo de traducción no existe aún, se creará antes de abrirlo en Lokalize.

- Open in editor, abre el archivo seleccionado en un editor de texto. Si el archivo de traducción no existe aún, se creará antes de abrirlo en el editor.

- Delete from local copy el archivo seleccionado. Esta opción solo está disponible para los archivos que carecen de su correspondiente plantilla.

### Working with images

La pestaña Imágenes de la ventana principal de &kmyapplication; encierra una útil herramienta para trabajar con las capturas de pantalla de la documentación traducida.

Captura de pantalla de la pestaña Imágenes de &kmyapplication; Captura de pantalla de la pestaña Imágenes

Lo primero que tenemos que hacer es seleccionar una branch para trabajar con ella. Si no hemos descargado previamente la documentación original (en inglés) del repositorio se nos mostrará un mensaje invitándonos a hacerlo. Podemos optar por las dos ramas descargadas del repositorio: branches/stable y trunk. Por omisión está seleccionada la rama branches/stable.

Tras seleccionar una rama, veremos que cambia el listado de carpetas que hay debajo. Conviene recordar que este listado está organizado de la misma forma que lo está en el repostitorio de KDE (es decir, las carpetas son nombres de paquetes que contienen otras subcarpetas que coinciden con los nombres de las aplicaciones que los componen). En este listado de carpetas deberemos seleccionar la de la aplicación con la que nos interesa trabajar.

Supongamos que hemos seleccionado la subcarpeta kdeedu/kalzium. En la lista de imágenes se mostrarán dos columnas que contienen las Original images (en inglés) del programa Kalzium y las Translated images (en el idioma de destino), si están disponibles. En esta lista, la columna de la derecha (la de las imágenes traducidas) puede mostrar información visual adicional para indicarnos si una imagen se debe borrar de la copia local del repositorio (se mostrará rodeada de un cuadro rojo que significa que sobra) o si se debe añadir a la copia local del repositorio (se mostrará rodeada de un cuadro verde que significa que la imagen todavía no ha sido añadida). Estos colores se pueden modificar en el diálogo de configuración de &kmyapplication;, en la sección SVN.

Si hace doble clic sobre una imagen, se mostrará en una ventana independiente con un tamaño mayor y algunos detalles sobre la misma.

#### The images context menu

La lista de imágenes dispone de un menú de contexto que será distinto según la columna sobre la que se muestre.

En la columna de las Original images contiene una única opción que nos permite copiar un archivo de imagen original (&ie;, en inglés) en la columna de Translated images. En realidad, lo que hace es copiar el archivo original de la carpeta `documentation/[paquete]/[aplicación]` a la carpeta `[idioma]/docs/[paquete]/[aplicación]` de nuestra copia local del repositorio. Esto puede resultar útil si la imagen original no contiene información visual que necesite traducirse al idioma de destino (por ejemplo, porque la imagen original es un icono o no contiene texto en inglés).

El menú de contexto que se muestra en la columna Translated images contiene varias opciones que nos permiten:

- Capture an image usando el programa de capturas de pantalla por omision. La imagen capturada se añade automáticamente a la copia local del repositorio con el mismo nombre que la imagen original.

- Add image a la copia local del repositorio. Se usa cuando hemos colocado una imagen en la copia local del repositorio de forma externa.

- Delete image de la copia local del repositorio. Se usa cuando la correspondiente imagen original ya no está presente en el repositorio.

- Copy an image to the other branch de la copia local del repositorio. Se usa cuando queremos copiar una imagen de la rama actual en la misma carpeta y aplicación de la otra rama.

### Synchronization

La pestaña Synchronization de la ventana principal de &kmyapplication; contiene una herramienta que le permite sincronizar algunas traducciones entre los archivos de idéntico nombre contenidos en diversas ramas de traducción.

Captura de pantalla de la pestaña Sincronización de &kmyapplication; Captura de pantalla de la pestaña Sincronización

Para usar esta herramienta, en primer lugar habrá que seleccionara una translation branch de las diponibles en la lista desplegable que hay en la parte superior izquierda de la herramienta. Al hacerlo, se mostrarán los distintos archivos y carpetas que contiene en la lista de la parte izquierda. A continuación, seleccionamos un determinado archivo en esta lista para mostrar las cadenas coincidentes en la ventana de la parte superior derecha.

Esta lista de cadenas coincidentes contiene todas las cadenas sin traducir (es decir, en inglés) que contiene el archivo seleccionado, y que también están presentes en los demás archivos de igual nombre (y contenidos en la misma carpeta) presentes en el resto de las ramas de traducción, cuya traducción difiere entre sí.

Por ejemplo, supongamos que tenemos tres ramas de traducción llamadas A, B y C, y que todas ellas contienen un archivo denominado `example1` con idéntico contenido, aunque la cadena número 3 del mismo ha sido traducida de diferente forma en las tres ramas. Al seleccionar dicho archivo en la lista de archivos de la rama A, la lista de cadenas coincidentes contendrá una única línea con el contenido de la cadena número 3 en inglés. Esto indica que dicha cadena está presente en varios archivos que se llaman `example1` contenidos en varias de las ramas A, B y C, y que se ha traducido de forma distinta en ellos.

Si selecciona una cadena coincidente, en la lista inferior se mostrarán las distintas traducciones de la misma en todos los archivos que la contienen en todas las ramas de traducción. Esta lista contiene un menú de contexto que se muestra al seleccionar una traducción y pulsar sobre ella el botón derecho del ratón. Este menú de contexto contiene una única opción que permite copiar la traducción seleccionada en el resto de archivos de las ramas de traducción.

#### What's a translation branch?

Una translation branch no tiene por qué corresponderse con una de las dos ramas que normalmente suele contener proyecto de traducción. En la práctica, una rama de traducción debe ser una ruta de su copia local del repositoro que termine con el código de su idioma (por ejemplo, `/home/user/l10n/trunk/l10n-kde4/es/`).

Normalmente, si está trabajando en un proyecto que contiene archivos tanto en la rama estable como en la rama de desarrollo, tendrá dos ramas de traducción para dicho proyecto. Puede añadir tantas ramas de traducción como desee a la herramienta de sincronización, ya que esta herramienta es independiente del proyecto sobre el que se esté trabajando y funciona de forma simultánea en todas las ramas de traducción añadidas. Esto le será de gran utilidad si está trabajando en varios proyectos que contienen varias ramas, tanto estables como de desarrollo (por ejemplo, si está traduciendo para KDE4 y para KF5).

Puede añadir ramas de traducción desde el diálogo de configuración de &kmyapplication;, usando la sección Synchronization.

## Command reference

### &kmyapplication;'s main window

#### The File menu

File &pology;

- Este submenú contiene diversas acciones para la gestión de la copia local de &pology;.

File &pology; Download or update

- Descarga o actualiza su copia local de &pology;.

File &pology; Cleanup

- Limpia la copia local de &pology; de posibles bloqueos ocurridos al descargar datos.

File &pology; Upgrade

- Permite renovar el formato del almacenamiento de los metadatos de la copia local de &pology;. Esta operación puede ser necesaria cuando se usa una versión reciente de la orden `svn` con una copia local de &pology; obtenida con una versión anterior.

&Ctrl;S File Save changes

- Saves the translation files modified using the synchronization tool.

&Esc; File Cancel process

- Interrumpe un proceso en marcha, como, por ejemplo, la ejecución de una orden de Subversion.

&Ctrl;Q File Quit

- Sale de &kmyapplication;.

#### The Project menu

&Ctrl;N Project New project...

- Crea un nuevo proyecto de traducción. El nuevo proyecto se añadirá a la ventana de proyectos del programa (columna situada a la izquierda de la ventana principal, por omisión).

Project Add project...

- Añade un proyecto de traducción existente. El proyecto se añadirá a la ventana de proyectos del programa.

Project Delete project

- Borra el proyecto seleccionado en la ventana de proyectos.

Project Configure project...

- Permite configurar algunos parámetros del proyecto seleccionado en la ventana de proyectos.

F5 Project Update statistics

- Actualiza la página de estadísticas del proyecto actual.

Project Restore default paths in selection dialogs

- Borra las rutas seleccionadas por omisión en los diálogos de selección de rutas del proyecto seleccionado en la ventana de proyectos. Cuando se realizan algunas acciones sobre la copia local del repositorio, los diálogos de selección de rutas contienen una opción para usar siempre todas las rutas disponibles en la lista de rutas y no volver a preguntar nunca más. Esta opción hace que se vuelvan a mostrar de nuevo esos diálogos de selección de rutas.

Project Download or update glossary

- Descarga o actualiza el glosario del equipo de traducción para el proyecto actual. Puede configurar la dirección remota que contiene el glosario en el diálogo de preferencias del programa.

#### The Tools menu

Tools Checkout local copy...

- Descarga la copia local del repositorio. Puede realizar esta acción de forma automática inmediatamente después de crear un nuevo proyecto de traducción.

&Ctrl;U Tools Update local copy...

- Actualiza su copia local del repositorio. Para realizar esta acción de forma automática cada cierto período de tiempo, vaya al diálogo de configuración del programa.

Tools Open in &lokalize; (trunk)

- Abre &lokalize; con la rama trunk de nuestra copia local del repositorio.

Tools Open in &lokalize; (stable)

- Abre &lokalize; con la rama branches/stable de nuestra copia local del repositorio.

&Ctrl;F Tools Search in PO files...

- Busca textos en nuestra copia local del repositorio.

Tools Checks

- Este submenú contiene diversas acciones que puede realizar la orden posieve de la utilidades &pology; sobre la copia local del repositorio.

&Ctrl;K Tools Checks Check &kde; messages validity...

- Comprueba la validez de los mensajes de &kde;. Es válido tanto para mensajes de interfaz como de documentación.

Tools Checks Fancy quotes...

- Cambia de forma inteligente las parejas de comillas inglesas (tanto simples como dobles) por las comillas del idioma al que se está traduciendo.

&Ctrl;R Tools Checks Check language rules...

- Comprueba en los mensajes traducidos las reglas definidas para el idioma al que se está traduciendo.

Tools Checks Check language spelling...

- Comprueba la ortografía de los mensajes traducidos.

Tools Checks Remove obsolete...

- Elimina los mensajes obsoletos que pudieran existir al final de los archivos traducidos. Tenga cuidado al usar esta opción, ya que la información eliminada podría servirle de ayuda para traducir futuros mensajes.

Tools Checks Remove previous...

- Elimina las traducciones previas que han cambiado. Estas traducciones suelen ser incorrectas, aunque podrían servirle de ayuda en la traducción.

Tools Local file

- Este submenú contiene diversas acciones que puede realizar sobre su copia local del repositorio.

Tools Local file Differences with repository

- Muestra las diferencias entre el archivo local seleccionado y su copia existente en el repositorio.

Tools Local file Undo changes

- Deshace la última operación realizada sobre el archivo seleccionado. Por ejemplo: si fue modificado, se recuperará la última versión existente antes de realizar las modificaciones.

Tools Local file Add to local copy

- Añade el archivo seleccionado a la copia local del repositorio.

Tools Local file Delete from local copy

- Borra el archivo seleccionado de la copia local del repositorio.

Tools Local file Resolve conflict

- Lanza una aplicación externa (&kdiff3;) para tratar de resolver los conflictos de actualización existentes en el archivo seleccionado. Tras la ejecución de esta herramienta se le pedirá que confirme manualmente si resolvió todos los conflictos del archivo.

Tools Local file Mark as resolved

- Marca el archivo seleccionado como resuelto (sin conflictos). Por lo general, debería usar esta opción si ha resuelto los conflictos de un archivo de forma manual (por ejemplo, mediante el uso de un editor de texto externo).

Tools Local file Open in &lokalize;

- Abre el archivo PO seleccionado en &lokalize;.

Tools Local file Open in editor

- Abre el archivo seleccionado en un editor de texto sin formato.

&Ctrl;D Tools Generate documentation...

- Genera la documentación de una rama completa, de un paquete o de una determinada aplicación. Esta opción también actualiza previamente la documentación que se va a generar.

Tools Download documentation...

- Descarga la documentación de una rama completa, de un paquete o de una determinada aplicación.

Tools Cleanup local copy...

- Limpia la copia local del repositorio de posibles bloqueos realizados al enviar o descargar datos.

Tools Upgrade local copy...

- Permite renovar el formato del almacenamiento de los metadatos de la copia local del repositorio. Esta operación puede ser necesaria cuando se usa una versión reciente de la orden `svn` con una copia local del repositorio obtenida con una versión anterior.

Tools Relocate local copy...

- Permite reubicar la copia local del repositorio cuando se ha modificado el URL del que se descargó. Esta operación también es necesaria si se accede al repositorio usando un protocolo distinto al que se usó para descargarlo (por ejemplo, si se descargó usando `https://` y se ha cambiado el modo de acceso a `svn+ssh://`).

F2 Tools Show changes...

- Muestra una lista de los archivos modificados en la copia local del repositorio.

&Ctrl;E Tools Send changes...

- Muestra una lista de los archivos modificados en la copia local del repositorio, los empaqueta en un archivo comprimido y llama al programa de correo por omisión para enviar dicho archivo al coordinador del equipo de traducción. Esta opción solo aparece cuando no se tiene permiso de escritura en el repositorio.

&Ctrl;E Tools Commit changes...

- Muestra una lista de los archivos modificados en la copia local del repositorio para enviarlos al repositorio de &kde;. Esta opción solo aparece cuando se tiene permiso de escritura en el repositorio.

#### The Settings menu

Settings Show Toolbar

- Muestra u oculta la barra de herramientas principal.

Settings Show Statusbar

- Muestra u oculta la barra de estado.

Settings Configure Shortcuts...

- Configura los accesos rápidos de teclado de la aplicación.

Settings Configure Toolbars...

- Configura las barras de herramientas de la aplicación.

Settings Configure &kmyapplication;...

- Muestra el diálogo de preferencias de &kmyapplication;.

#### The Help menu

F1 Help &kappname; Handbook

- Inicia el sistema de ayuda de &kde; mostrando las páginas de ayuda sobre &kappname; (este documento).

&Shift;F1 Help What's This?

- Modifica la forma del puntero transformándola en una combinación de flecha e interrogación. Al pulsar sobre los elementos que hay dentro de &kappname; se abrirá una ventana de ayuda (si existe para cada caso particular) con una descripción de la función de dichos elementos.

Help Check new version

- Comprueba la existencia de una nueva versión del programa en la página web del mismo. En caso afirmativo, muestra un mensaje ofreciendo las posibilidades de descargar o de instalar la aplicación.

Help Report Bug...

- Abre un cuadro de diálogo para informar de fallos donde puede notificar un fallo o solicitar una mejora o nueva propiedad deseable.

Help Switch Application Language...

- Abre un diálogo donde puede modificar el Idioma principal de esta aplicación y el Idioma al que recurrir en caso de que el principal no esté disponible.

Help About &kappname;

- Muestra información sobre la versión de la aplicación y su autor.

Help About &kde;

- Muestra la versión de &kde; y otra información básica.

### The Main Toolbar

Captura de pantalla de la barra de herramientas principal del programa The program's main toolbar

La barra de herramientas principal del programa consta, por omisión, de los siguientes botones:

Cancel process

- Cancels the current process.

Save changes

- Saves the translation files modified using the synchronization tool.

Update local copy

- Actualiza el estado de la copia local descargando la última versión de la misma a partir del repositorio.

Update statistics

- Actualiza la información sobre las estadísticas de la copia local del repositorio.

Open in Lokalize (trunk)

- Abre en Lokalize el archivo de traducción seleccionado (perteneciente a la rama trunk).

Open in Lokalize (stable)

- Abre en Lokalize el archivo de traducción seleccionado (perteneciente a la rama stable).

Generate documentation

- Genera la documentación correspondiente al paquete seleccionado (también se puede indicar el nombre de un archivo individual).

Show changes

- Muestra una lista con los archivos que han cambiado en la copia local del repositorio.

Send changes or Commit changes

- Envía los archivos modificados actualmente en la copia local del repositorio al coordinador del equipo de traducción o directamente al repositorio (si se cuenta con permiso de escritura en él).

## Questions and Answers

¿Cómo comprobar si existe una nueva versión de &kmyapplication;?

Use la opción del menú Help Check new version para saber si existe una nueva versión del programa en su página web. En caso afirmativo, se le ofrecerán la posibilidades de descargarlo y de instalarlo en su sistema.

¿Es posible automatizar algunas de las tareas básicas del programa?

Sí. Use la opción del menú Settings Configure &kmyapplication;... para mostrar el diálogo de configuración del programa y vaya a la sección Others. Allí puede automatizar la comprobación de la existencia de nuevas versiones del programa (cada inicio del programa, cada día, cada semana o cada mes), la actualización de &pology; (cada inicio del programa o cada día), y la actualiación durante cada inicio del programa de la copia local del repositorio y del glosario del equipo de traducción (solo para el primer proyecto de la lista de proyectos).

Cada vez que el programa accede al repositorio de &kde; me pide la contraseña de usuario. ¿Se puede automatizar este proceso para que no me la pida más veces?

Esto solo ocurre cuando se está usando una conexión no anónima para acceder al repositorio de &kde;. En la actualidad, &kmyapplication; no está preparado para gestionar este tipo de conexiones de forma automática, pero es posible usar el agente SSH para este propósito. Para ello, en una sesión de consola, lance el programa `ssh-agent` y ejecute luego la orden `ssh-add` (que le solicitará su contraseña una única vez) para que el agente SSH se encargue de proporcionar su contraseña SSH cada vez que sea necesario para acceder al repositorio de &kde;.

## Credits and License

&kmyapplication;

Program copyright © 2008-2015 Eloy Cuadra ecuadra@eloihr.net

Documentation copyright © 2010-2015 Eloy Cuadra ecuadra@eloihr.net

&underFDL; &underGPL;

## Installation

### How to obtain &kmyapplication;

&kmyapplication; can be found at &kmyapplication;'s webpage (in Spanish).

### Requirements

In order to successfully use &kmyapplication;, you need &kde; 4.4.0 or later, although it is possible that the program works in earlier versions..

You can find a list of changes at &kmyapplication;'s webpage (in Spanish).

### Compilation and Installation

&install.compile.documentation;
&documentation.index;