Help+Manual News

Archive for category Translation

Smartcat is a cloud-based translation ecosystem that is already widely used, supporting both advanced machine translation and translation by traditional human translators, or a combination of the two. Recently, customers have started asking the staff at Smartcat whether the system could process Help+Manual XML topic files. They looked into it, contacted us for the specifications and the result is now a working beta version that is ready for testing.

Call for beta testers

If you are looking for alternative ways to translate your Help+Manual documents you are invited to participate in the free beta test of the new Smartcat system. Pavel Doronin and his team would really appreciate your feedback and suggestions for possible improvements.

How to participate

You just need to register an accountat Smartcat, or use your existing one if you already have one. Then send a message to the Smartcat support team at support@smartcat.ai with a request that you want to enable Help+Manual support in your account.

About H+M support in Smartcat

Currently you can import individual/multiple XML files (both topic files and TOC files), not entire projects. You can then translate them yourself, assign them to a translator or apply machine translation. Both H+M’s traditional XML and the new TidyXML introduced with version 7.3 are already fully supported.

Full project import may be added in a future update. Any and all other suggestions you may have are very welcome, of course.

We are glad to announce that Help+Manual 7.3 Public Beta is available for download! Version 7.3 implements a slightly modified XML format that is more translation-friendly. We had announced this feature before, now you can try it for the first time.

You can download and install the 7.3 beta version like any previous 7.x update from this direct link:

The link will be kept active during the beta phase and will be updated 2 or 3 times a week.

About TidyXML

As you know, Help+Manual saves a project in XML format, enabling external translation programs to parse the XML and translate it. The XML code, that Help+Manual creates, however, is a bit more complicated than many translation programs would like to have it. It is best explained with an example…

Please run Help+Manual and paste the following 2 lines of text into a topic:

Now let’s switch the editor to “XML View” and have a look at the XML code created for these 2 lines:

The XML colored in yellow is the code created for the two lines. These are 2 paragraphs (<para> tags in XML) and several separate text elements (<text> tags in XML). A translation program that parses the XML code, does not see the visual representation like you do in Help+Manual. It sees the XML structure only and has to make sense of it.

Changing the XML format

Version 7.3 has a switch that you can activate to apply a new and cleaner (tidier) XML syntax. The switch applies per help project and is placed under Configuration > Common Properties > Miscellaneous Options.

To activate the function, perform the following steps:

Make a backup of your help project (!)

Make sure the backup can be restored any time

Open the help project and navigate to the configuration section as shown below

Enabe the option “Write translation-friendly XML“, then click “Apply to all topics“

The difference in XML

The new XML syntax writes <text> tags only where necessary. If the text style is identical with the paragraph style, the text is simply placed between the <para>…</para> tags, making it much easier to read for an external translator. Explicit <text> tags are inserted if the text has a different format than the paragraph. Furthermore, style classes are inherited. The new XML syntax omits redundant “styleclass” attributes for <text> tags and links.

The entire XML structure becomes smaller and more readable.

This new XML structure, however, is not compatbile with older versions of Help+Manual. While you won’t lose content when opening such a converted help project with an older version of H&M, the style inheritance is not recognized and the format might look distorted. Do not open a converted project with an older version of Help+Manual!

This topic is all about translation of Help+Manual projects. As you know, Help+Manual saves a project in XML format, enabling external translation programs to parse the XML and translate it.

The XML code, that Help+Manual creates, however, is a bit more complicated than many translation programs would like to have it. And we are going to change this with the next update(s). I mentioned this detail in the 7.2 maintenance update already, here’s more about it. It is best explained with an example…

Please run Help+Manual and paste the following 2 lines of text into a topic:

Now let’s switch the editor to “XML View” and have a look at the XML code created for these 2 lines:

The XML colored in yellow is the code created for the two lines. These are 2 paragraphs (<para> tags in XML) and several separate text elements (<text> tags in XML). A translation program that parses the XML code, does not see the visual representation like you do in Help+Manual. It sees the XML structure only and has to make sense of it.

What makes it difficult for translation programs and translators are the <text> tags in particular. It would be much easier to read and less error-prone to translate if the XML structure was more simple and – nested. For example, the very same text could be represented by an XML code like this:

You see in the picture above, that there is just a simple <para> tag that starts the paragraph. There is not even a style attribute to it, which makes Help+Manual assume that the paragraph style will be formatted with the default style “Normal”. Text follows immediately after the <para> tag, no extra <text> tag is used here. The text will as well be formatted with the default style “Normal”, to be exact: with the same style that is already defined by the <para> tag. Just when a text part with a different style comes along, an additional nested <text> tag with modified style attributes is inserted.

This simplification of the XML code makes it much easier to translate those two sentences with an external translation program. It’s not only more compact, but the translation program doesn’t have to worry about moving plain text around. It’s just plain text between and opening <para> and a closing </para> tag. The same rule applies to links and other objects with meta information: easier to read, easier to re-group text, easier to translate.

There is just one caveat with this new more compact XML code: it is not backwards-compatible with older versions of Help+Manual. So we decided to implement it in 3 steps:

Version 7.2 (that last update out already) implemented the first step and has a modified XML reader to be able to read the simplified XML code. If you have installed 7.2 already, give it a try! Open H&M, switch to the “XML view” and paste the XML code below into the XML editor:

When you switch back to WYSIWYG view, the result should look more or less like in the first picture – depending on your own style settings for “Normal” and “Heading1”. Version 7.2, however, does not write this XML code. That’s planned for the next update.

Version 7.3 will implement an optional switch for TidyXML. We expect a relatively long beta-phase for this update and the TidyXML switch will remain off by default and can be switched on per help project for extensive testing. If you don’t do anything, Help+Manual 7.3 will behave as before. If you switch it on, it will create the new XML code.

After version 7.3, we plan to keep the switch, but might eventually switch it on by default for new projects, once the function is mature and widely tested.

Help+Manual’s XML code has been back- and forward compatible through many versions. We have introduced additional attributes, new objects and new features (think: publishing tasks) over the years, but basically, you can still open a help project created with version 7.2 with an old version 5.0 of Help+Manual. It will work, topic content is the same.

The new TidyXML format breaks this backward compatibility and the step-by-step introduction decreases the risk that people who still work with older versions will run into a problem when opening or editing content.

Stay tuned for the announcement of a 7.3 beta to test it. We will publish it in this blog.