From owner-freebsd-doc@FreeBSD.ORG Mon Aug 19 17:07:27 2013 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 9A3FFBB5 for ; Mon, 19 Aug 2013 17:07:27 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 336222B36 for ; Mon, 19 Aug 2013 17:07:27 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r7JH7QXD017115 for ; Mon, 19 Aug 2013 11:07:26 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r7JH7P66017112 for ; Mon, 19 Aug 2013 11:07:25 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 19 Aug 2013 11:07:25 -0600 (MDT) From: Warren Block To: doc@FreeBSD.org Subject: Updating translation workflow Message-ID: User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 19 Aug 2013 11:07:26 -0600 (MDT) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Aug 2013 17:07:27 -0000 We have some problems with our translation workflow, and updating it could make life easier for everyone. Note that as an American, I barely speak English, so there may be misconceptions in the following. Please correct me if necessary. * Translators work too hard. No automation, no assistance from the computer to see what needs to be translated, no reuse of previously-translated terms. Because of this, updating translations after the English version changes can take a long time. * Few new translators are willing to work that hard, so we are missing up-to-date translations to several important world languages. * Separating whitespace and content patches makes it more difficult for writers to edit existing English documents. The current workflow, such as it is, is very, very old. Since it was created, new ways to translate have come about. PC-BSD is using Pootle (textproc/pootle, http://pootle.translatehouse.org/) for their documentation: http://pootle.pcbsd.org/ I think we can use a combination of tools to work with our existing documents. The workflow would be like this: 1. Use textproc/itstool to create a "strings to be translated" file (.pot) from an XML file. 2. Use pootle as a database to translate any of those strings that have not already been translated. 3. Use itstool to merge the translated strings back into the XML file. 4. Build the translated document (DocBook or XHTML) as normal. The first difficulty I've found is that itstool does not like entities. It could be modified to accept them, but probably the more correct procedure for translations is to expand them before using itstool. This would be more correct for translations, as it's been explained to me, because some languages modify nouns depending on how they are used. (In other words, our use of entities can be English-centric.) Is there an easy way to expand entities?