Developing training websites in multiple languages

by Alan Pringle , Tina Meißner on November 21, 2016

This case study shows how Scriptorium Publishing created the free DITA learning website by combining the DITA learning and training specialization, GitHub, XSLT, video, and WordPress—and how parson AG adapted those technologies to develop the German site,

DITA, which stands for Darwin Information Typing Architecture, is an open XML-based standard for creating, organizing, and managing content. The LearningDITA websites use multiple approaches to educate students about DITA. Lessons include step-by-step instructions, guided and independent exercises, and assessment questions. Courses also provide resources, such as links to instructional videos.

Managing source content and video

The LearningDITA project is created as DITA XML files. The DITA learning and training specialization provides specific structures for training content (for example, lesson objectives and test questions). The LearningDITA source content includes conceptual information, step-by-step instructions, exercises, and quiz questions.

For file storage, Scriptorium chose GitHub, a web-based repository based on the open-source Git version control system. With a free GitHub account, authors from all over the world can contribute and revise content in the LearningDITA repository.

Anyone can download the open-source files from GitHub and adapt the content for their own purposes.

In addition to source control, GitHub provides a project wiki. In the LearningDITA project, the wiki provides editorial and content development guidelines. The guidelines promote consistency in the source files.

The video content in courses is not part of the DITA source. Instead, we record and edit video clips with Adobe Captivate. Although we could have used an open-source tool to create the video content, we already had a license for Captivate. We post the videos to YouTube, the free video hosting service. YouTube provides a no-cost alternative to the challenges of hosting and maintaining video content on your own web server.

Creating the site

Scriptorium already had experience with WordPress, an open-source system for managing and publishing web content, so we decided to publish as a WordPress-based site. We identified a learning management system (LMS) that integrates into WordPress. The LMS is a commercial system with a small licensing fee, but it supported our major requirements, including interactive quizzes and management of student accounts. There was no business justification to spend time and money creating our own LMS in WordPress when we could buy an inexpensive tool.

Scriptorium developed a process that transforms the DITA XML files into WordPress-compatible XML. This solution was based on the DITA Open Toolkit, a collection of open-source technologies that convert DITA XML into HTML, PDF, and other formats. We built an Extensible Stylesheet Language Transformations (XSLT) stylesheet in the toolkit to convert DITA XML into WordPress-compatible XML. We imported the transformed XML content into WordPress, made some minor manual adjustments in the LMS to ensure that test questions are associated with the right lessons, and published the course.

Localizing the DITA content

To localize the course files created in DITA, parson downloaded the English files from the GitHub project and copied them. We kept the structure of DITA elements and replaced the textual content inside the elements with the German translation.

The LearningDITA courses provide a large number of code snippets that are embedded in step-by-step instructions. Users can follow the instructions and compare their result with a sample solution presented in an associated DITA sample file. parson localized the sample files to match the code snippets in the instructions. We also localized the id attributes and the file names of the sample files. This does not cause any problems because the sample files are not referenced by DITA maps or topics. In addition, we replaced screenshots of the sample solution that were taken in the visual mode of an XML editor.

parson also needed to decide whether to localize the file names of the course files. As they form part of the resulting URL, a German name is easier for German users. But that also implied adapting all topic references.

Finding the right DITA terms in German

Finding established equivalents for DITA terms was another difficult task. parson mostly used direct translations to describe the function of DITA elements in the text, such as paragraph = Absatz, note = Hinweis, and substeps = Teilschritte. If there was no established German translation, parson needed to create one; for example, Auswahltabelle for a choice table.

Another challenge was to find a compromise between comprehensibility (that is, using German translations) and recognition by users (that is, using Anglicisms). parson tried to avoid Anglicisms as much as possible. Nevertheless, we decided to keep frequently used, DITA-specific terms to make them easily recognizable. Examples are: (task) topic = (Task-)Topic, map = Map, and body = Body.

We also used the Anglicism if a term did not have a German equivalent and paraphrasing would have been too complicated or too long in the context. These were case-by-case decisions. For example, we translated “inline element” with Inline-Element to align it with the translation for “block element” (= Block-Element) because both terms are often mentioned in one breath.

Setting up the website

Scriptorium provided parson with a list of required WordPress plugins and settings for setting up, so a hosting agency could reproduce the structure and layout of the English website. parson changed colors and fonts according to the corporate design. We also adapted the logo by changing the colors and by localizing the text “learningDITA” to “DITA lernen.”

parson localized the HTML contents on the website (that is, all but the DITA course contents) and the explanatory texts that come with the plugins. The explanatory texts confirm input by users or indicate errors during registration, login, and so on.

We customized the transformation from DITA to WordPress-compatible XML by localizing auto-texts that are used by the transformation. We also implemented the transformation in our XML editor oXygen to enhance usability. We can now start the transformation directly from oXygen.

Legal requirements for websites differ from one country to another. In Germany, Austria, and Switzerland, websites must state the publishing organisation or person, including name, contact information, trade registry number, etc. parson added this information, commonly known as Impressum. We also localized the privacy policy (Datenschutz) according to German legislation.


  • Open-source solutions are free but often expensive in terms of effort. If a licensed add-on to an open-source solution does what you need, does it make more financial sense to use it instead of creating your own solution? Is it worth the development effort to completely automate a process if that process is used infrequently?
  • Do not make assumptions about the cloud-based services people use. For example, not everyone wants a Google account because of privacy concerns, and Google services are blocked in some locations.
  • When content is translated, be prepared for that process to uncover errors. Need a workflow to address them.
  • Try to balance between translating DITA terms and adopting the original terms. These decisions can depend on the amount and the kind of Anglicisms used in your language, and on your target group.
  • When thinking about what to localize (id attributes, file names), weigh the work you would have to put in against the benefit of the consistency.
  • Consider legal requirements for different countries.
  • Establish a change process for subsequent changes after publication. The content always lives longer than you think.

Slideshare presentation

Add new comment

Your email address will not be published.

You might also be interested in

Adobe DITAWORLD 2023: parson as Gold Sponsor and with two presentations on intelligent content

May 25, 2023

As a leading DITA ambassador, parson is happy to support the next Adobe DITAWORLD 2023 again as a Gold Sponsor. We are also looking forward to the presentation of Ulrike Parson on "Intelligent content for the manufacturing industry" and the presentation of Frank Ralf and Lukas Jetzig "From DITA to Smart Content." more...

parson develops sustainable information architecture for proALPHA

April 20, 2023

We are happy that we have successfully completed an information architecture project with proALPHA. To improve the usability of its technical documentation, the company introduced the content delivery platform Zoomin. parson supported the project by developing a new information architecture and providing content engineering services. more...

New knowledge article on creating a PDF from HTML with CSS

March 21, 2023

Martin Fiebig finished his studies of Technical Information Design and Technical Editing with a bachelor's thesis on the conversion of HTML or DITA XML files into PDF files. He wrote his thesis with a practical focus at parson. In the recently published knowledge article, he summarizes his findings. more...

Creating a PDF from HTML – Formatting documents with CSS Paged Media

by Martin Fiebig on March 14, 2023

There are several ways and tools you can use to create a PDF from a technical documentation in DITA-XML or a website in HTML. In the first part of this knowledge article, I look at the advantages and disadvantages of the languages commonly used in this process: XSL-FO and CSS Paged Media. In the second part I compare programs for rendering HTML files to PDF files via CSS and compare their functions.  more...