Translating in Help & Manual

Help+Manual itself is really the best XML editor for editing and translating your projects. The inexpensive Basic version costs less than most professional XML editors and can do much more. It can edit both compressed and uncompressed projects created with the Professional or Floating license version without restriction. It is just lacking some features, but they are not features the translator needs – for example ePUB and Visual Studio output. Unlike a normal XML editor, you can work in WYSIWYG mode and you also have access to all of Help+Manual's advanced tools and features.

Translating projects in Help+Manual is basically exactly the same as working on a project in your own language. You just make a sibling copy of the project with the Project Synchronization Tool, set up the language settings appropriately for the target language and work you way through the project, translating as you go. When a new version of your project becomes available you can then use the Project Synchronization tool to create an updated version of the translated project containing all the topics with new material to be translated.

Protecting text against changes and translation

You can explicitly protect text against translation and editing changes. To do this select the text in the editor and then select the "padlock" tool in Write > Font. The text will then be displayed shaded in the Help+Manual editor and it will be tagged with the attribute translate="false" in the XML topic file.

Procedure for translating projects in Help+Manual

Click on the individual steps below to display more detailed instructions.

When you are using Help+Manual as the translation editor you can use either the compressed .hmxz format or the uncompressed XML .hmxp format – which you use is up to you. However, both the original project and the translated version must be saved in the same format, otherwise you will not be able to use the Project Synchronization tool later to update your translations.

1.Make sure your graphics are included in the project folder

Graphics files:
The translator will be able to understand the project better if you include the graphics files. The easiest way to enable this is to make sure that all the graphics are included in the project folder as well. You can move them there easily, and generally they should always be kept there. See Managing your graphics for instructions.

Graphics containing text:
If you create your graphics using the Impict editor included with Help+Manual you can have it store the text they contain in linked XML files that can be translated by translation memory programs. See Translating texts in images for more details.

2.Check whether you need to include any snippet files for the translator

If your files contain linked snippets from external sources you may need to include copies of these embedded files for the translator.

If you include the files with the translation package you should put them in a separate folder inside the project folder you are going to send to the translator and add an entry to Configuration > Common Properties > Project Search Path pointing to the folder containing the snippet files so that Help+Manual will find them.

3.Make a sibling copy for the translator to work on

If you have the Basic version of Help+Manual you must just make a copy with Save As... in the File menu. The Project Synchronization tool is not included with the Basic version.

In the Professional or Floating license version select Synchronize in Project > Tools and make a sibling copy of the original project. This copy will have exactly the same internal IDs as the original, which will make it possible to identify changes and update the translated version with the Synchronize tool later.

See The Project Synchronization Tool for more details.

4.Set up the language settings for the target language in the translation version

This is very important and can lead to unexpected errors in your output if you forget it. For details on the settings you need to make and the issues you need to consider study International languages setup.

5.Translate the project in Help+Manual

Obviously, the first thing you will translate will be the texts of your topics. But there are also a number of other things that you should not forget, and a few things that you should not translate:

•Remember to translate all the normal index keywords in the Topic Options tab and the Index Tool. See Keywords and Indexes for details on working with index entries.

•Don't translate any A-keywords in the tab. These keywords are never seen by the user and they will work best if you leave them unchanged.

•Check through all the sections of Project Configuration and translate any texts that will be visible to the user, including the values of text variables.

•Don't translate the names of variables or include options (build conditions). You can translate the display texts for include options if you want but you don't have to, they are never seen by the user.

See Instructions for translators and editors for a full list of guidelines.

6.Publish your output, check and distribute

Publish your output as normal. Before distributing it check it to make sure that everything is OK for the target language. For example, if your language settings are not correct special characters in the target language may not be displayed correctly.

Procedure for updating translated projects

Translating the first version of your project is straightforward, you just make a copy and translate it. The next challenge is to produce an updated version of the translation when a new version of your original documentation is released.

If you are using the Basic version of Help+Manual you must make notes of all your changes and tell the translator where they are.

If you have Help+Manual Professional you can use the Project Synchronization Tool to make an updated version of the translated project. Project Synch will delete removed topics, add new topics and mark changed topics as changed. Full copies of the original text of all new and changed topics, topic titles in the TOC and topic headings can be inserted for the translator if you want. (Otherwise you must provide a copy of the original version for the translator to refer to.)

Click on the individual steps below to display more detailed instructions.

1.Create an updated version of the project for the translator

Basic version:
If you have the Basic version of Help+Manual you must send the translator a copy of the new version of the original project with annotations showing where the changes are located. The translator must then use Help+Manual to update the old version of the translation.

Professional/Floating license version:
Follow the instructions in The Project Synchronization Tool for synchronizing the new version of your documentation with the translated version. This will create a new version of the old translated project for the translator, with deleted topics removed, new topics inserted and changed topics marked as changed. You can also choose to insert full copies of the new content of all new and changed topics for the translator to work with.

2.Make copies of all new and changed graphics and other external files

Before sending the updated project to the translator, make sure that you also include all new and modified graphics in the translation package, along with any new and changed external files. Here too, keeping everything in one project folder makes things a lot easier.

Also check whether there are any changes in linked snippets – if there are you will probably need to include copies of the new versions of the source files for the translator.

3.Translate the changes and generate your output

Once the translator has produced the new version you can generate your output as normal. Don't forget to check through the Configuration settings in the Project Explorer to make sure that all relevant texts visible to the user have been translated.

After generating your output check the finished product carefully to make sure that everything is OK in the target language. For example, make sure that special characters are rendered correctly – if they are not you may need to adjust the language settings for your project.

Please enable JavaScript to view this site.