Difference between revisions of "Documentation translation"

From Inkscape Wiki
Jump to navigation Jump to search
(39 intermediate revisions by 10 users not shown)
Line 1: Line 1:
Go Back to the main [http://wiki.inkscape.org/wiki/index.php/Translation_information Translation information] page.
Go back to the main [[Translation information]] page.


= Tutorial Translation =
== Tutorials ==


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


http://svn.sourceforge.net/viewcvs.cgi/inkscape/doc-docbook/trunk/
The ''translations'' of the tutorials however are in the well-known [[Translation information#PO translation files|PO format]]. If you want to help, download them [http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs/trunk/files/head%3A/tutorials/ here]. You will find each tutorial in its own subdirectory, with a .pot template.


Each tutorial is in its own subdirectory. You need the *.xml file, for example basic/tutorial-basic.xml. You could 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. Other (better) ways are described below.
Once you are satisfied with what you have done, [[Translation information#Submit finished work|submit it]].


* 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.
=== Header and footer ===


* Save your file as <original name>.<language suffix>.xml, for example basic/tutorial-basic.es.xml for Spanish.  
The header and footer for the translation can as well be translated. Their translation is to date still a bit different from the tutorial translation as the header and footer SVG files need to be modified directly (so without using a PO file). To translate the tutorial header and footer, download and rename the following files (in the browser, save the page as _tutorial-header.<your two-letter language code here>.svg or _tutorial-footer.<your two-letter language code here>.svg, respectively):
* [https://gitlab.com/inkscape/inkscape-docs/documentation/raw/0.92.x/tutorials/_tutorial-header.svg Last revision of header]
* [https://gitlab.com/inkscape/inkscape-docs/documentation/raw/0.92.x/tutorials/_tutorial-footer.svg Last revision of footer]


* Do not use symbolic entities like &amp;aacute; (they're not defined in XML without a DTD). Instead use either numeric entities such as &amp;#225; or simply write your text in UTF-8.
You should notice that some strings in the header are paths, not editable texts — this is to ensure that the text will render correctly to the end user. To translate it, you will have to recreate the text object yourself (use a generic sans-serif font with appropriate license, e.g. ‘DejaVu Sans’ or ‘Bistream Vera Sans’, in italic) and convert it to a path when you're done. Also consider the translucent ‘tutorial’ text path in the background.


* 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.
=== Committing a translation to the Inkscape trunk ===


* When finished, run [http://xmlsoft.org/xmllint.html xmllint] on your file to make sure it's well-formed: <code>xmllint --noout --noent --valid <filename></code>
When you have a gitlab account, so you can fork the repository and make a merge request, and when you are adding a new tutorial SVG to it ([https://gitlab.com/inkscape/inkscape/tree/master/share/tutorials to the tutorial directory]), it's recommended to also perform the following steps:
 
* 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 ==
* OmegaT - http://www.omegat.org/omegat/omegat_en/omegat.html
* Transolution - http://transolution.python-hosting.com/
* xml2po, see below
* see also [[Talk:DocumentationTranslation#Ideas for Improving the Translation Process|Ideas for Improving the Translation Process]]
 
=== 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.


* Add the filename of the tutorial SVG (and any additional files it needs, like PNG images referenced from the SVG) to ‘share/tutorials/Makefile.am’ in the [https://gitlab.com/inkscape/inkscape/tree/master/ main Inkscape trunk].
* If the SVG refers to a PNG, then that PNG should exist in the SVG's directory — make sure to also commit that PNG.
* Modify the translation of the tutorial filename in the main PO file so as to make Inkscape display the localized tutorial instead of the default (English) one. An example: if the <code>"tutorial-basic.svg"</code> string is translated the following way in ‘po/fr.po’:
<pre>
<pre>
## use this at the very beginning, when there is no translation at all:
msgid "tutorial-basic.svg"
xml2po --output=basic/tutorial-basic.pot basic/tutorial-basic.xml
msgstr "tutorial-basic.fr.svg"
 
</pre>
## use this when there is a *.de.xml, but you want a de.po:
: then whenever the locale is French, Inkscape will display the French (and not the default English) basic tutorial for users.
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:
You may also check the tutorials with the [https://gitlab.com/inkscape/inkscape/blob/master/po/check_for_tutorial_problems.sh check_for_tutorial_problems.sh] script. See the comments inside the script for more information.
mkdir .tmp.basic


## use this when the tutorial-basic.xml has been updated and you
=== Verification ===
## 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
To create up-to-date tutorials (the ‘tutorial-*.svg’ files), you'll need to build them from the tutorial PO files.
## 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
</pre>


= Keyboard and mouse translation =
'''The section below is outdated!'''


* TBD
[First of all, you need to check whether you have the necessary software. You need a Java SDK, Saxon, and the GNOME documentation utils, before you can actually build the SVGs of the tutorials:
# Install Saxon 6.5.x if it's not already installed. It is a tool that converts XML to SVG using XSLT. You need to have version 6.5.x, because the build process doesn't work with newer versions. Preferably, you install it with your package manager under Linux. For example, under openSUSE, install '''saxon-6.5.5''' or a similarly named package — NOT '''saxon8''' or similar.<br/> You can also download it manually from the project page on SourceForge ([http://saxon.sf.net saxon.sf.net]). Look for the section ‘Older products’ and its subsection ‘Saxon 6.5.5’. Download the zip file and unzip it into a suitable directory that's accessible by the build script (e.g. in /usr/share/java). The build scripts needs to find ‘saxon.jar’ in your Java classpath, so you may want to check your classpath in case of a Java problem.
# Install the Java SDK (JRE is not enough) if it's not already installed. You can check your installation with <code>type java</code> from the command line — check that '''java''' actually points to the SDK's '''java''' executable that you installed.


= User Manual =
When this is complete create or update the tutorial SVG files:
* See also [[Embedded Help]]
# Update your local copy of the [http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs/trunk/files/ inkscape-docs trunk] and the [https://gitlab.com/inkscape/inkscape/tree/master/ main inkscape trunk] from bzr (see also [[Working with Bazaar]] for some more information on the commands and workflow of Bazaar).
* First download the user manual xml document from [http://svn.sourceforge.net/viewcvs.cgi/inkscape/user_manual/trunk/xml/ SVN]
# <code>javac javaclasses/org/inkscape/xslt/files.java</code> (this rebuilds ‘files.class’, which is a Java class file)
* edit the trunk/xml/inkscapeUTF.xml file. All languages are inside.
# <code>cd tutorials/</code>
* Just read the file, choose the language reference you want to use (en, fr...) and translate by duplicating the node and changing lang attribute to yours.  
# <code>make svg</code> (this creates all tutorial SVGs for all languages — can take long)
* when finishing editing, if necessary edit the Makefile and add your language to the Makefile. In every case test your file with some tools (xmllint...) or just type again "make your_language" : syntax errors will be displayed : please correct them.
# Check the newly created tutorial SVGs (which you'll find in their specific tutorial directories: ‘advanced/’, ‘basic/’, etc.) for overlapping text (often caused by font settings) and other problems. It's recommended to perform the check under a different operating system. If the SVGs have overlapping text, check the default fonts on your computer.
* submit your work as a patch in the patch tracker and warn Cédric Gemy (cedric at le-radar.com) by email.
# If you want to commit the newly created tutorial SVGs, then copy the new ‘tutorial-*.svg’ files to the ‘share/tutorials/’ directory of your local copy of the main Inkscape trunk and commit them to the main Inkscape trunk.


= Man pages =
For more information, see ‘tutorials/README’ (web version [http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs/trunk/annotate/head%3A/tutorials/README here]) and ‘tutorials/Makefile.targets’ (web version [http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs/trunk/annotate/head%3A/tutorials/Makefile.targets here]).]


* first download inkscape.pod from [http://svn.sourceforge.net/viewcvs.cgi/inkscape/inkscape/trunk/inkscape.pod?view=log SVN]
== Keyboard shortcuts and command line references ==
* rename it to inkscape.xx.pod, where xx is the code for your language
* open inkscape.xx.pod in your favourite text editor (pay attention to encoding which must be UTF8), and directly translate in the file.
* you can take a look at a first example of translation with inkscape.fr.pod
* finally, submit your work in the patch tracker and drop a mail to the inkscape devel mailing list.


= Polishing Translations - Microtypography =
Just translate the [[Translation information#PO translation files|PO file]] for your language in the ‘keys/’ and ‘man/’ directories of the [https://gitlab.com/inkscape/inkscape-docs/documentation/ inkscape-docs repository], then [[Translation information#Submit finished work|send us your work]].
Here are some things to note in order to achieve good microtypography (typography at the word or character level).
* use the proper quotes (e.g. »foo«)
* use the proper kind of dashes (with the proper amount of whitespace around them) - EN DASH (U+2013): "–", MINUS (U+2212): "−"
* use non-breakable space where appropriate (e.g. before units; some countries use a halfspace here) - NO-BREAK SPACE (U+00A0): " "
* use halfspace where appropriate (example: "z. B.") NARROW No-BREAK SPACE U+202F: " "
* use "24×24", not "24x24"
* use "90°", not "90 degrees" where appropriate
* use the proper Unicode codepoint for "..." - "…"


== Links ==
== User Manual ==
* http://de.wikipedia.org/wiki/Typografie (German)
* [http://www.dante.de/dante/DTK/dtk96_4/Text/dtk96_4_neubauer_feinheiten.pdf  Marion Neubauer: ''Feinheiten bei wissenschaftlichen Publikationen – Mikrotypographie-Regeln, Teil I''] (PDF, German)
* [http://www.dante.de/dante/DTK/dtk97_1/Text/dtk97_1_neubauer_feinheiten.pdf  Marion Neubauer: ''Feinheiten bei wissenschaftlichen Publikationen – Mikrotypographie-Regeln, Teil II''] (PDF, German)
* [http://www.zvisionwelt.de/typokurz.pdf Christoph Bier: ''typokurz – Einige wichtige typografische Regeln''] (PDF, German)


'''Obsolete!'''


= Translation information =
* See also [[Embedded Help]].
Go Back to the main [http://wiki.inkscape.org/wiki/index.php/Translation_information Translation information] page.
* First download the user manual xml document from [http://inkscape.svn.sourceforge.net/viewcvs.cgi/inkscape/user_manual/trunk/xml/ SVN].
* Edit the trunk/xml/inkscapeUTF.xml file. All languages are inside.
* Just read the file, choose the language reference you want to use (en, fr…) and translate by duplicating the node and changing lang attribute to yours.
* When finishing editing, if necessary edit the Makefile and add your language to the Makefile. In every case test your file with some tools (xmllint...) or just type again "make your_language"; syntax errors will be displayed: please correct them.
* Submit your work as a patch in the patch tracker and warn Cédric Gemy (cedric at le-radar.com) by email.


[[Category: Developer Discussion]]
[[Category: Translation]]

Revision as of 00:42, 13 February 2018

Go back to the main Translation information page.

Tutorials

Inkscape's tutorial sources are in Docbook XML format, with illustrations in SVG.

The translations of the tutorials however are in the well-known PO format. If you want to help, download them here. You will find each tutorial in its own subdirectory, with a .pot template.

Once you are satisfied with what you have done, submit it.

Header and footer

The header and footer for the translation can as well be translated. Their translation is to date still a bit different from the tutorial translation as the header and footer SVG files need to be modified directly (so without using a PO file). To translate the tutorial header and footer, download and rename the following files (in the browser, save the page as _tutorial-header.<your two-letter language code here>.svg or _tutorial-footer.<your two-letter language code here>.svg, respectively):

You should notice that some strings in the header are paths, not editable texts — this is to ensure that the text will render correctly to the end user. To translate it, you will have to recreate the text object yourself (use a generic sans-serif font with appropriate license, e.g. ‘DejaVu Sans’ or ‘Bistream Vera Sans’, in italic) and convert it to a path when you're done. Also consider the translucent ‘tutorial’ text path in the background.

Committing a translation to the Inkscape trunk

When you have a gitlab account, so you can fork the repository and make a merge request, and when you are adding a new tutorial SVG to it (to the tutorial directory), it's recommended to also perform the following steps:

  • Add the filename of the tutorial SVG (and any additional files it needs, like PNG images referenced from the SVG) to ‘share/tutorials/Makefile.am’ in the main Inkscape trunk.
  • If the SVG refers to a PNG, then that PNG should exist in the SVG's directory — make sure to also commit that PNG.
  • Modify the translation of the tutorial filename in the main PO file so as to make Inkscape display the localized tutorial instead of the default (English) one. An example: if the "tutorial-basic.svg" string is translated the following way in ‘po/fr.po’:
msgid "tutorial-basic.svg"
msgstr "tutorial-basic.fr.svg"
then whenever the locale is French, Inkscape will display the French (and not the default English) basic tutorial for users.

You may also check the tutorials with the check_for_tutorial_problems.sh script. See the comments inside the script for more information.

Verification

To create up-to-date tutorials (the ‘tutorial-*.svg’ files), you'll need to build them from the tutorial PO files.

The section below is outdated!

[First of all, you need to check whether you have the necessary software. You need a Java SDK, Saxon, and the GNOME documentation utils, before you can actually build the SVGs of the tutorials:

  1. Install Saxon 6.5.x if it's not already installed. It is a tool that converts XML to SVG using XSLT. You need to have version 6.5.x, because the build process doesn't work with newer versions. Preferably, you install it with your package manager under Linux. For example, under openSUSE, install saxon-6.5.5 or a similarly named package — NOT saxon8 or similar.
    You can also download it manually from the project page on SourceForge (saxon.sf.net). Look for the section ‘Older products’ and its subsection ‘Saxon 6.5.5’. Download the zip file and unzip it into a suitable directory that's accessible by the build script (e.g. in /usr/share/java). The build scripts needs to find ‘saxon.jar’ in your Java classpath, so you may want to check your classpath in case of a Java problem.
  2. Install the Java SDK (JRE is not enough) if it's not already installed. You can check your installation with type java from the command line — check that java actually points to the SDK's java executable that you installed.

When this is complete create or update the tutorial SVG files:

  1. Update your local copy of the inkscape-docs trunk and the main inkscape trunk from bzr (see also Working with Bazaar for some more information on the commands and workflow of Bazaar).
  2. javac javaclasses/org/inkscape/xslt/files.java (this rebuilds ‘files.class’, which is a Java class file)
  3. cd tutorials/
  4. make svg (this creates all tutorial SVGs for all languages — can take long)
  5. Check the newly created tutorial SVGs (which you'll find in their specific tutorial directories: ‘advanced/’, ‘basic/’, etc.) for overlapping text (often caused by font settings) and other problems. It's recommended to perform the check under a different operating system. If the SVGs have overlapping text, check the default fonts on your computer.
  6. If you want to commit the newly created tutorial SVGs, then copy the new ‘tutorial-*.svg’ files to the ‘share/tutorials/’ directory of your local copy of the main Inkscape trunk and commit them to the main Inkscape trunk.

For more information, see ‘tutorials/README’ (web version here) and ‘tutorials/Makefile.targets’ (web version here).]

Keyboard shortcuts and command line references

Just translate the PO file for your language in the ‘keys/’ and ‘man/’ directories of the inkscape-docs repository, then send us your work.

User Manual

Obsolete!

  • See also Embedded Help.
  • First download the user manual xml document from SVN.
  • Edit the trunk/xml/inkscapeUTF.xml file. All languages are inside.
  • Just read the file, choose the language reference you want to use (en, fr…) and translate by duplicating the node and changing lang attribute to yours.
  • When finishing editing, if necessary edit the Makefile and add your language to the Makefile. In every case test your file with some tools (xmllint...) or just type again "make your_language"; syntax errors will be displayed: please correct them.
  • Submit your work as a patch in the patch tracker and warn Cédric Gemy (cedric at le-radar.com) by email.