Translating the Docs

As we approach the eventual release of 1.4, and beyond, we are trying to make an effort to improve the online docs. So far, we are concentrating on the English version (you have to start somewhere), but we hope to have volunteers come forward to help us, not only with the traditional translations to French, German, Czech, and Polish, but also as many others as we can get volunteers for. So we don't have duplicated effort, contact Christoph Schäfer (you can find his email in the mailing list archives) if you plan to begin working on these files. He would also be the one to send your translated files to, so that they can be incorporated into the version.

Since the Scribus online manual is shown with a simple browser, the files are in HTML. Perhaps the best way to get the most up to date manual is by downloading from svn. Even if you don't plan to compile Scribus, you can download source files, which include the docs. Go HERE for instructions. You must have subversion on your computer (there are ways to use subversion on Windows, but I have not tried).

Where are the docs?

Let's say you put your svn checkout into a directory named MyScribus:

• MyScribus
  • scribus
    • doc
      • en – The menu and HTML files are in this directory.
        • images – The images used in the HTML files are in here. Each language directory will have its own images subdirectory.

So each of these is a subdirectory of the one above. Inside en/ are the HTML files that make up the documentation, and there is also a file named menu.xml:

<?xml version="1.0" encoding="UTF-8"?>
<menu>
	<area text="Welcome" file="index.html">
		<submenuitem text="Readme First" file="readme.html"/>
	</area>
	<area text="Documentation" file="intro.html">
		<submenuitem text="Introduction" file="documentation.html">
			<submenuitem text="About the team" file="about1.html"/>
			<submenuitem text="Specifications" file="specs.html"/>
		</submenuitem>
		<submenuitem text="Installation" file="install.html">
			<submenuitem text="Scribus Source & SVN" file="install1.html"/>
			<submenuitem text="Requirements" file="install2.html"/>
			<submenuitem text="Compiling using CMake" file="install4.html"/>
			<submenuitem text="Compiling using CMake on OS X" file="install5.html"/>                     
			<submenuitem text="Parallel Install" file="parallel-install.html"/>
			<submenuitem text="Debian dpkg Information" file="install-dpkg.html"/>
		</submenuitem>
		<submenuitem text="Cross Platform" file="cross-platform.html">
			<submenuitem text="Mac OSX Readme" file="readme-macosx.html"/>
			<submenuitem text="Mac OSX/Fink" file="machints1.html"/>
			<submenuitem text="Mac OSX/Fink & SVN" file="machints2.html"/>
			<submenuitem text="OS/2 Readme" file="readme-os2.html"/>
			<submenuitem text="Windows Readme" file="readme-win32.html"/>

and so on ...

If you compare this to the menu in the Help Browser you will see how the structure of the menu is created. More importantly, you will see the name of the HTML file associated with each menu item. So the menu item About the team links to about1.html. This is important, since unlike the browsers we're used to, the Help Browser in Scribus doesn't give us this information. The other thing to note is that you need to edit this menu.xml file for the language you are translating to, so the menu items make sense to users.

Workflow

It's best to just leave these files in HTML and edit in a plain text editor. Once you edit and save, you can view them in a browser to make sure there are no typos and the layout is still Ok. What we see on the wiki is that someone will copy the English version of a page, then paragraph by paragraph translate the English, deleting the English as they go, but leaving the HTML tags and links intact. Thus you can recurrently view in a browser to see your work in progress.

What I have done when working on the docs was to copy the en/ and images/ directories and their files out to another directory outside of the svn download, so I can work more easily and protect my edits. Since the page links to images are relative, as long as you have images/ inside of your en/ or fr/ or /other directory, the page will find images Ok.

Image Translations

Some of the images have English-language labels on them. With time, we want to localize these also, but the first thing I would point out is to respect the intelligence of your users. They can probably manage for a while with the English words on a dialog, since placement is important even when they don't understand English. Afterward, you can begin to replace images one by one. If you want help with this, you just need to ask.