# Documentation Translation Help



## wblock@ (Jan 29, 2014)

Major FreeBSD documentation like the Handbook is written in DocBook XML.  Translators watch the English versions for changes and then manually update their translations.  This is tedious, manual work, and the difficulty level can discourage new translators.  We have some amazing translators who do excellent work, but could always use more.

We would like to use modern translation tools to make translating easier.  PC-BSD uses Pootle, and it seems to be effective.  Command-line tools like textproc/itstool might fit our workflow better, and not require as much overhead.  These tools keep track of translated and untranslated strings, let translators share work and reuse previous translations.

If you have experience with XML translation tools, particularly DocBook XML, please describe what you use and the workflow process.


----------



## ondra_knezour (Mar 20, 2014)

@wblock: Today translators have to watch for changes and translate without tools.
Remko: We don't use any tools and I am not aware of anyone who does.

Both look almost same to me.

The OP was about the automation of the translation workflow, not "Hey, who here can run some English text through Google Translate, optionally with several steps using Chinese, French and Eskimo and add some noise from the cosmic microwave background at the end?"


----------



## remko@ (Mar 20, 2014)

I do not approve that @apple or whatever his name is posts my email conversation with him on the Internet without notifying me.

He is hard to follow and understand and keeps asking the same questions per email so I will repeat what I have just told him (after that for me the conversation with him is over):
Warren is looking for ways to ease translations, which is correct and I applaud that.
We currently do not use translation tools.
Google Translate produces rubbish so that will not be used.

Thanks,
Remko


----------



## fonz (Mar 21, 2014)

remko@ said:
			
		

> I do not approve that @apple or whatever his name is posts my email conversation with him on the Internet without notifying me.


Removed.


----------



## ondra_knezour (Mar 22, 2014)

And now for something completely different.

To be also a little constructive:

One of my clients uses Pootle for managing translations of both interface and manuals of six hardware projects into thirty languages and seems pretty happy with it. Translated materials are further transformed into HTML web interfaces, Java applications and printed manuals (using LaTeX) and it works.
The po4a package can teach Pootle to speak in Docbook tribe language.
Virtaal is a desktop application which can feed translations into Pootle.

Other tools known to me (mostly by name only) are Weblate and PHP Documentation Editor (live site). The KDE project uses something named Rosetta. I also found a thesis named Adopting Standards Based XML File Formats In Open Source Localisation, but haven't have time to read it yet.

Two side notes - it may be nice from the user experience view, if such a tool can also incorporate PRs for a given document/language in some way. Also many users don't have enough confidence to do something so complicated and quality demanding as create official documentation, but may have useful comments and small additions. Those breadcrumbs of knowledge coming in large quantities may help a lot. There was an excellent tool on the Django Book site, which enabled users to add comments to paragraphs. It is gone now, but I found ucomment which does almost same and I am considering it as a possible way to incorporate maybe huge knowledge (or noise) from random by-passers.


----------



## wblock@ (Mar 22, 2014)

Thanks for that!  textproc/po4a works on FreeBSD, and has the interesting possibility of working on man pages.  textproc/itstool is newer and might do a better conversion.

After creating the .po or .pot, editors/poedit can be used to edit it.  Virtaa looks like a much fancier version of that.

There are sites that are essentially implementations of Pootle, like Transifex.  They get a huge translation memory, and projects don't have to maintain their own Pootle site.  But if a project decided to leave, they would have to start their translation memory all over.

The nice thing about these sites is that they shield the user from all the documentation build details.  Anyone can create an account and translate strings.  I think both Pootle and Transifex have some provision for people rating translations, to pick out the better ones.


----------



## wblock@ (Mar 22, 2014)

Here's a quick start at a textproc/virtaal port: http://www.wonkity.com/~wblock/tmp/virtaal/.  It starts, runs, but is not useful because the text disappears, maybe due to lack of py-gtkspell.  That's part of x11-toolkits/py-gnome-extras, but it includes things I don't particularly want.  (Ignore that maintainer field, I just wanted to try this.)


----------

