how to translate apache cloudstack docs
DESCRIPTION
Slide Deck describing how to translate the Apache CloudStack documentation using transifex an publican. CloudStack has an extensive documentation built using docbook xml files and publican. Localization i.e translation of that documentation is handled by transifex a web service that translators can use to submit translated strings. These translations are then pulled from transifex and committed to the cloudstack source tree to build the documentation in multiple languages. This same workflow is used to translate the graphical user interface elements. We currently have support for several languages in the GUI including: Japanese, Chinese, Taiwanese, Russian, Italian, French etc... check http://transifex.com and search for CloudStack. This talk shows you how to use transifex from the web UI as well as from the transifex command line client and submit translations.TRANSCRIPT
Transla'ng Apache CloudStack (ACS)
Documenta'on Sebas'en Goasguen
@sebgoa
Outline
• CloudStack documenta'on • Transla'on concepts • Using Transifex website • Using the Transifex client • Working with the ACS source code
Based on: hFp://sebgoa.blogspot.ch/2012/11/transla'ng-‐apache-‐cloudstack-‐docs-‐with.html
hFp://sebgoa.blogspot.ch/2012/12/using-‐transifex-‐client-‐to-‐translate.html
ACS Documenta'on
• Apache CloudStack documenta'on is wriFen in DocBook xml format.
• The various documenta'on ar'facts are built with Publican
• Documenta'on source files are part of the ACS source tree under the docs directory.
hFp://www.docbook.org hFp://jfearn.fedorapeople.org/en-‐US/Publican/2.7/html/Users_Guide/
hFps://git-‐wip-‐us.apache.org/repos/asf/incubator-‐cloudstack
ACS Documenta'on
• To modify/correct the documenta'on: – Submit a jira 'cket to track your modifica'on and highlight the issue.
– Clone the git repository – Prepare a patch – Submit the patch via Review Board
hFps://issues.apache.org/jira/browse/CLOUDSTACK hFps://git-‐wip-‐us.apache.org/repos/asf/incubator-‐cloudstack
hFps://reviews.apache.org/dashboard/
Transla'on concepts
• With Publican we can build the documenta'on in different languages.
• To do this we need every string of the documenta'on to be translated in the targeted language.
• Anyone can contribute string transla8on without even working with the source code.
• To do so we use Transifex hFp://rlandmann.fedorapeople.org/pug/sect-‐Users_Guide-‐Preparing_a_document_for_transla'on.html
hFps://www.transifex.com
Sign up
Your dashboard
Search for ACS projects
ACS projects
• There are currently three ACS projects that need transla'on: – ACS UI (The Web UI) – ACS Runbook (a.k.a Quick Install Guide) – ACS DOCS (The en're documenta'on)
Pick a project
Check the Resources
Resources correspond to the DocBook XML files in the source tree
Pick One and Add transla'on
Pick the target language
Translate strings
Save your transla'ons
NB: Check poten'al sugges'on, enter the transla'on, submit it
Check Progress for your language
Transifex Client
• The website is really easy to use, but you can also use the transifex client (tx) if you want to work from the command line.
• You s'll need to signup on the website
pip install transifex-client!
hFp://help.transifex.com/features/client/ hFps://pypi.python.org/pypi/transifex-‐client/
Setup the Project
• This part is not linked to the ACS source, it can be done without checking the ACS code.
• Ini'alize a transifex project on your computer
$ mkdir txproject!! !$ cd txproject!! !$ tx init!
Point to ACS Transifex project
• For the main documenta'on: ! !$ tx set --auto-remote https://www.transifex.com/! ! !projects/p/ACS_DOCS/!
• Pull all resources for the project $ tx pull –s!
• Pull exis'ng transla'ons $ tx pull –a !
Translate
• Pick a resource and make a copy with the language code of your target language, for example: $ cp translations/ACS_DOCS.pod-add/en.po translations/ACS_DOCS.pod-add/fr.po!
• Enter your transla'on in the msgstr lines: $ vi translations/ACS_DOCS.pod-add/fr.po!
• Push your transla'on (replace the language code and the resource name with yours): $ tx push -l fr -r ACS_DOCS.pod-add -t!
Build final documenta'on
• Once transla'on strings appear on Transifex • An ACS commiFer will pull them directly into the source code
• Build the guides with publican • And Voila…
Working with the source
• You can translate directly in the ACS source and submit patches or commit directly (if you are a commiFer)
• Go to the docs directory, note the pot directory.
• Create a directory corresponding to your target language if it does not exist yet (use publican commands)
• Use the publican language codes hFp://rlandmann.fedorapeople.org/pug/sect-‐Users_Guide-‐Preparing_a_document_for_transla'on.html
Example
• The docs/runbook directory contains: !en-US!!fr-FR!!it_IT!!ja-JP!!pot!!publican.cfg!!tmp!!zh-CN!!zh-TW!
Example
• In docs/runbook/it_IT you see the PO files which contain the strings that need to be translated ! !Book_Info.po!! !Environment.po!! !Management.po!! !Overview.po!! !Preface.po!! !Revision_History.po!! !config.po!! !kvm.po!
Example
• Pick a resource, use your text editor to view it, edit the missing strings
• Commit the changed files via review board or git
#. Tag: title!#, no-c-format!msgid "Database Installation and Configuration"!msgstr "Installazione e Configurazione del Database"!
Conclusions
• We are aiming to release ACS 4.1 on March 22nd 2013.
• We need as much transla'on as possible. • We need your help • Even if you can do one string it’s great. • If you cannot complete the en're transla'on for the 4.1 release, keep at it, it will make it for 4.2.