Difference between revisions of "TestPage"

From Inkscape Wiki
Jump to navigation Jump to search
Line 46: Line 46:
  
 
== Man pages ==
 
== Man pages ==
A reminder for the moment. Will fill it later (matiphas)
+
The man pages consist in a standard user documentation, available from the command line on Unix systems simply type "man inkscape" from the prompt of a command window).  
  
 +
Some distributions also generate a browsable (html) man page, accessible from dedicated help shortcut.
 +
 +
The man page of Inkscape provides some insightful information about the software, aspecially foused on operations that do not require GUI (example: export to png from the command line, or extract one object from a svg file).
  
 
== Release notes ==
 
== Release notes ==

Revision as of 12:24, 5 June 2006

Introduction

Community based, user oriented

The translations of the various documents focusing on Inkscape rely on the work of volunteers. Motivation for this work can range from the simple pleasure to contribute to take the opportunity of learning a lot about Inkscape and translation processes. It is very important not to forget that Inkscape is an open source, community based and user oriented software, which implies that software developpers/contributors are generaly users. It also implies that the translation efforts are also user oriented, with a strong focus on interface, user documentation and website.

Guidelines/workflow

  1. Contact to a local translation group, to get support and help on your language. Rather than working alone, you should work with an experienced translation team for your language. Thus you will benefit from their knowledge, as well as being able to communicate with them on your own mother tongue. Moreover, translation teams use to have style guidelines and a standarized vocabulary for technical terms that you should be aware of. There may be many communities working on translations for your own language, but a good start point is subscribing to your local GNOME translation team or KDE translation team.
  2. Subscribe to Inkscape translator mailing list. By subscribing on Inkscape's translator list you will be able to ask for help on some questions more related to Inkscape issues to other Inkscape translators, as well as the mantainers.
  3. Get files for your language. If you only want to translate the interface messages, you can get the files from Inkscape's svn repository web interface. Besides getting files from web interface, you can obtain the full repository; instructions on how to do this are found here. See section #Translatable_content for which files you have to modify to translate each part of Inkscape.
  4. Submit finished work to patch tracker. Finished translations must be sent to patch tracker and/or mailing list in order to be integrated into the trunk. You will need a Sourceforge.net account to commit patches to Inkscape's patch tracker. Before sending a file, remember to check that the file you are submitting doesn't have syntax errors that would break the building process.
  5. Send a mail on the translator mailing list. Your contribution will be reviewed/commited as soon as possible.

Best practices

Best case for a good translation : translate from English to your mother tongue.

Test the behavior of the interface before starting translation

Translatable content

Inkscape's translation effort covers many areas, from aplication UI itself to web pages and tutorials. This is a summary of all those areas, ordered by priority.

These tasks, rather than being for hackers only, can be achieved by most software enthusiasts, whether they have a technological background or just plain users. The main requirement is the wish to provide support for Inkscape on your language: the technology required for do that has been developed in a simple approach, and it involves mainly text files and applications used to verify its syntax. Supporting applications exists to make this tasks even easier.

User interface

PO files contain the strings for the Inkscape user interface (main software and extentions). A PO file is a text file which contains the original English message and its translation. That's why it is obviously the translation to start with.

See section #Interface_Translation for information on PO files.

Tutorials

As you know, Inkscape comes with some very nice SVG tutorials. By translating them, users will learn how to use the application, as well its tips and tricks.

See section #Tutorial_Translation for information on translating tutorials.

Windows installer

High value for users, even if the installation process of Inkscape is quite simple, translating the Windows installer helps a lot potential users feeling good with Inkscape. More information in #Windows_installer_translation section.

Templates

The default template of Inkscape document can be localized to make the localization consistent. Localized can be size of the default document and also the name of default layer. For information about translation of default document's template, please see #Default_template_translation section.

Man pages

The man pages consist in a standard user documentation, available from the command line on Unix systems simply type "man inkscape" from the prompt of a command window).

Some distributions also generate a browsable (html) man page, accessible from dedicated help shortcut.

The man page of Inkscape provides some insightful information about the software, aspecially foused on operations that do not require GUI (example: export to png from the command line, or extract one object from a svg file).

Release notes

Translating release notes helps giving a lot of visibility to Inkscape

- give a general overview of the possibilities of the software to potential users

- can be used for local marketing (local Free Software/Linuw/Graphics oriented web sites, articles in fanzines, e-magazines and even magazines...)

User manual

Just a reminder for the moment. Will first take a look at user-manual process, get some info from cedric and then fill this section (matiphas).

News displayed on Inkscape web site

Web pages

English is generaly the exchange-tongue of developppers, and developper/user documentation is mainly written in English.

Translation efforts should be first oriented on user documentation.

See the main pages of Inkscape and of this wiki to get some exemple of the translations of websites.

Others

Text files found in the inkscape directory ...

Interface Translation

Introduction to PO file format

If you've never translated a PO file before, you will find its syntax very simple. The PO format is a really simple format, which probably at least partly explains its success and widespread use. The format is basically a hash list consisting of msgid and msgstr pairs, with the msgid being the original English string and key, and the msgstr being the translated value of it. Below is an example of a message.

  #: gedit/dialogs/gedit-plugin-program-location-dialog.c:78
  #: gedit/dialogs/program-location-dialog.glade2.h:2
  msgid "Set program location..."
  msgstr "Ställ in programplats..."

In addition to the msgid and msgstr parts, a message usually also has lines starting with #: that tells what source files and what lines the string used as msgid was extracted from. These lines have no syntactic value. They are only there as a help for translators and developers to know where a message came from.

A message in a PO file can be in one of essentially three different states. The message can be translated, fuzzy, or untranslated. A message counts as translated as soon as the msgstr part of it is non-empty. In a similar manner, an untranslated message is one where the msgstr is empty. The fuzzy state is special and essentially means that there is a translation in the msgstr part, but that this translation is most likely not entirely correct, and that it thus needs manual attention by a translator. A message can become fuzzy in one of two ways:

  • The original string that the msgid represents was changed in the source code. A typo in the string may have been fixed or the string altered in some other way. The translator needs to check that the msgstr is still valid and make changes if necessary.
  • A new string has been added to the source, and the string is very similar, but not identical, to the msgid of an already existing, translated message. Then the msgstr of that message will be automatically reused for the new message, but the new message will also at the same time be marked fuzzy so that the translator knows there is some difference that he or she needs to adapt the translation to match.

There is always one special message in each valid PO file: the PO file header. It is encoded with the msgid for the empty string ("") as the key, and the actual header values are in the msgstr part. This unfortunately means that if you mark an empty string for translation, you will get the entire PO file header back as the "translation". In almost all cases this is probably not what you want. Hence, do not mark empty strings for translation.

Get the PO file for your language

Download the .po file for your language from here:

   http://svn.sourceforge.net/viewcvs.py/inkscape/inkscape/trunk/po/

If a .po file for your language does not yet exist, then you will have to get an empty template file to start a new translation. The most straightforward way to obtain the inkscape.pot template is from the SVN repository above. Alternatively, you can checkout the full SVN project repository and generate the project template. Information on how to get the source tree can be found here. Then, you have to follow some steps in order to generate the template:

1. "./autogen.sh"
2. "./configure"
3. enter the "po" directory: "cd po"
4. generate the current PO template: "intltool-update --pot"

To make an absolutely up-to-date translation (in case the PO file in SVN is not up-to-date enough),

1. update your local copy of Inkscape in the usual way: "svn update"
2. merge your existing translations into the new POT file (inkscape.pot):
   "msgmerge your_latest_PO_file inkscape.pot > new_PO_file"

If you want to update ALL .po files in po/, cd there and run:

make update-po

Now that you have an empty PO template, you can start translating the messages.

Tools for translators

You can edit PO files from any plain text editor, since they are simple text files. However, many useful tools have been developed to provide a simple experience translating PO files.

And last but not least, gettext utils, which are installed on every linux distribution. You can see a complete reference too from installed info pages by running the command:

 info gettext

A few important things to remember

  • Some strings that can be ambiguous or having several meanings according to different contexts may have a context prefix : "Context|Amibiguous string". In this case, simply translate "Ambiguous string", the "Context|" string is just a not to translate indication.
  • After translating a fuzzy string (one that is marked with a ", fuzzy" comment), please remove its "fuzzy" tag -- otherwise this translation will be discarded by the build process, meaning that this string will show up untranslated. KBabel can do this automatically (see KBabel settings).
  • Before publishing your work (after you have finished updating the PO file), please update the "PO-Revision-Date" and "Last-Translator" fields in the PO file header. KBabel can do this automatically.

Review

This is the start of a list of places to get translation reviews done. So far:

 http://www.linux.it/tp/

Verification

Before submitting your file in the patch tracker, please make sure it is valid:

  • Make sure the file is encoded in UTF-8
  • Make sure it is a valid po file and obtain some statistics about it: simply run "msgfmt --statistics -cv translationFile.po" from a command window
  • Make sure it is correctly formatted: run "check-markup translationFile.po" from a command window and verify it doesn't output any error message. "check-markup" perl script can be found in the /po directory of Inkscape svn trunk

Locale Testing

Before reporting that a locale doesn't work in Inkscape, you need to make sure that your system has that locale correctly set up. To do this, you need to generally find a way to run "locale-gen". (Under Debian/Ubuntu this is via "dpkg-reconfigure locales".) If you set both the LANG and LANGUAGE variables and check a regular tool, you should see the correct language for both the libc error (first line) and the tool error (second line):

LANG=es_MX LANGUAGE=es_MX ls -z
ls: opción inválida -- z
Pruebe `ls --help' para más información.

If it reports the regular C messages, your locale has not been correctly configured, and you'll need to find the right way to run "locale-gen" for your distribution:

LANG=es_ES LANGUAGE=es_MX ls -z
ls: invalid option -- z
Try `ls --help' for more information.

Submit finished work

Upload your work via the SourceForge patch tracker:

   http://sourceforge.net/tracker/?func=add&group_id=93438&atid=604308

(Check the Upload checkbox and add your file or patch.)

(Don't forget to compress your file before uploading it, as sourcefoge tracker doesn't accept large files.)

Additionally, you may send a message to Inskcape's translators mailing list.

Programmers

Please make sure you use dgettext for any pluralized strings.

Windows installer translation

Strings for Windows installer are saved in *.nsh files. Each translation has its own file located in packaging\win32\ directory of subversion checkout. Get this file in similar way of getting *.po file.

Translating

  1. Get the file according to your language. If there is not such a file, copy english.nsh file and rename it to yourlanguage.nsh.
  2. Translate strings in the file
  3. Change !insertmacro MUI_LANGUAGE "English" and each occurence of ${LANG_ENGLISH} to values corresponding with your language. For example !insertmacro MUI_LANGUAGE "Czech" and ${LANG_CZECH}.
  4. Change header information in yourlanguage.nsh file, like "windows code page" and "Authors" to proper values.

Testing the translation

  1. This part is optional but recommended. For this part you need NSIS installer and run
    make -f Makefile.mingw dist
    command after succesfull compilation of Inkscape. This command prepares binary of Inkscape for installator creation.
  2. Add filename of your file to inkscape.nsi file, "STRING LOCALIZATION" section, "Language files" subsection.
  3. Right click on the inkscape.nsi file and choose "Compile NSIS Script". The installer compilation will start.
  4. When the installer is finished, run it to test translations of strings in Installer and Uninstaller parts.
  5. If the translation is tested succesfully, submit it to the patch tracker at sourceforge.net and mark as "Translation". If you haven't tested your translation yet, submit it too but enter this information to the patch information. You will be contacted about its correctness.

Default template translation

  • To translate default template, modify the default.svg file and save it as default.xx.svg where "xx" is ISO code of your language. The file can be found in /usr/share/inkscape/templates/ directory on Linux, or C:\Program Files\Inkscape\share\templates\ directory on MS Windows(tm). Also you can get it from SVN repository.
  • You need to modify your PO translation as well to use your localized default template. Look up for a msgid "default.svg" on the PO file and translate it accordingly to the file name of the localized template.
  • To test it, save it to the proper location and restart Inkscape. Default document should be now based on your localized template. (This is valid if your system is properly set to your locales).
  • Upload default.xx.svg to the patch tracker.

To translate default template can be used Inkscape as well as any UTF-8 encoding capable text editor.

Tutorial Translation

Inkscape tutorial sources are in DocBook format, with illustrations in SVG. If you want to translate one or more tutorials, first download the DocBook source here:

http://svn.sourceforge.net/viewcvs.cgi/inkscape/doc-docbook/trunk/

Each tutorial is in its own subdirectory. You need the *.xml file, for example basic/tutorial-basic.xml. Get it and simply replace all English text in it with the text in your language, preserving all XML markup. See README at that location for some notes on markup.

  • If there's already such a file in SVN, you can edit it instead :) If there's no xml file at the above location but there's a translation of this tutorial in SVG format (in share/tutorials in Inkscape distribution), you'll need to convert it to DocBook (and probably update). Conversion can be done simply by: select the text blocks of an SVG tutorial in Inkscape, Ctrl+C, and Ctrl+V in your text editor, then add the markup.
  • Save your file as <original name>.<language suffix>.xml, for example basic/tutorial-basic.es.xml for Spanish.
  • Do not use symbolic entities like &aacute; (they're not defined in XML without a DTD). Instead use either numeric entities such as &#225; or simply write your text in UTF-8.
  • Most illustrations don't need translations, so you leave the references to them from English XML intact. If however an illustration has some text that you want to translate, open the illustration file in Inkscape (e.g. basic/basic-f12.svg), edit it as needed, and save under a different name (e.g. basic/basic-f12-es.svg). Then change the filename reference in the XML source appropriately.
  • When finished, run xmllint on your file to make sure it's well-formed.
  • Send the file to Joshua Andler <scislac at users dot sf dot net>, and he'll convert it to SVG and HTML and upload it to SVN and the web site.
  • If after that you want to make any changes, download the file from the above location again, because it may have changed compared to the one you have.

Tools

Transforming XML into PO files

One can also use xml2po to get PO files out of the XML sources, and also transform the PO files back to XML. After you have a PO file, follow the instructions for editing those files below.

xml2po is available in gnome-doc-utils (http://ftp.gnome.org/pub/gnome/sources/gnome-doc-utils/).

Here are some command lines that were used to translate a German tutorial (the de-locale), please adapt accordingly until we nicely integrate this into our Makefiles.

## use this at the very beginning, when there is no translation at all:
xml2po --output=basic/tutorial-basic.pot basic/tutorial-basic.xml

## use this when there is a *.de.xml, but you want a de.po:
xml2po --output=basic/de.po --reuse=basic/tutorial-basic.de.xml basic/tutorial-basic.xml

## xml2po is not happy when this directory doesn't exist:
mkdir .tmp.basic

## use this when the tutorial-basic.xml has been updated and you
## want the new stuff in your de.po:
xml2po --update-translation=basic/de.po basic/tutorial-basic.xml

## use this to create a tutorial-basic.de.xml from your de.po (ScislaC
## will use this file to create the final tutorial SVG file)
## WARNING: Unfortunately, this doesn't put localized screenshot 
## file names into the xml file!
xml2po --po-file=basic/de.po basic/tutorial-basic.xml > basic/tutorial-basic.de.xml

Keyboard and mouse translation

Wiki and web site

Translation of web site

  1. There are two ways of getting files that you need to translate website:
    1. Checkout actual svn version of inkscape_web module (Working with SVN). To checkout the inkscape_web module use command:
      svn co https://svn.sourceforge.net/svnroot/inkscape/inkscape_web/trunk inkscape_web
      You need subversion client to do this.
    2. OR Use online browser of subversion repository and download files manually.
    3. Files you probably want to translate are:
      • includes/localized.inc (file contains string to translate menu)
      • index-en.inc (main page of inkscape.org)
      • discussion-en.inc
      • download-en.inc
      • mailing-lists-en.inc
      • report-bugs-en.inc
      • submit2webmaster-en.inc
      • submit2webmaster-en-form.inc
      • svn-en.inc
  2. Copy these files and replace "en" string in their name according to the ISO code of your language ("de" for german, "fr" for french, etc...).
  3. Now you can start your translation. Files are simple text files with HTML tags and in UTF-8 encoding.
  4. If you have the file translated and really want to submit it, read it once more and correct errors ;)
  5. Submit the file to the patch tracker at Sourceforge and mark it as a translation.
  6. Announce the translated file in the patch tracker in inkscape-translator(and optionally in inkscape-devel) mailing list. Persons responsible for updates of website will reply to you and/or submit the new "patch" directly.

If the translation of website is new, the process of making new translation available can take a bit longer because of a need to create corresponding flag and check consistency of the translation.

Translating news and status

News and status information are available for translation too. News items are stored in the /news directory of inkscape_module in separate subdirectories named by language version. The structure of directory with news is:

 /news
  - en
   \- 2005
    - 2006
     \- 04
      - 05
       \- 001.inc
        - 002.inc
        ...
  - de
  - fr

To translate news into your language download/checkout 00x.inc file from "en" directory, translate and submit to the directory of your language(file has to be in UTF-8 encoding) or submit to the patch tracker and announce on the inkscape-translator list. If you want to translate status information, the structure of directories is like in the case of news, only the name of directory is different.

Status

See this [dedicated page]