The ability to work with comments in a managed localisation process is an important part of communication between translator, reviewer, project manager and the end client… and not necessarily in that order!  Comments are used to clarify misunderstandings in the source text, questioning completed translations you’ve been told to ignore that just don’t look right, suggesting improved terminology, explaining why you translated something in a particular way, clarifying why you changed a translation in review, providing additional context from the client, adding notes to the target file for an in country review, they could even be comments that are just there to be translated, or ignored… the list of reasons could be pretty long and so could the comments.  So it’s very important to be able to keep them linked to the context so it’s easy to deal with the referred text, and also to be able to get to the comments quickly when they might only relate to a couple of segments in three files that are part of a five hundred file project nested within a complex folder structure.

So this post is going to deal with two things… first of all the places where comments can be used in Studio out of the box and secondly a very neat OpenExchange plugin that I reckon many project managers, and translators, have wished for and didn’t know it was there already!

Working with Comments

First of all comments can be added to the SDLXLIFF (Studio bilingual file) for any source file type.  They can’t always be transferred into the target file type however and this is because not all filetypes will support this.  We’ll look at source file types further down, but first let’s just consider how you work with them in an SDLXLIFF within the Studio Editor.

Comments in Studio can be added to the entire segment, to individual words/phrases or to the entire file.  You do this by either by selecting the text and then adding the comment via the ribbon, in the review tab, or just by using a customisable keyboard shortcut… the default is Ctrl+Shift+N:

There’s also a severity level you can choose from for each comment, and this can refer to it being informational, warning or an error.  The colours used are customisable by going to File -> Options -> Colors where you’ll see the option to select the colours used under “Comment colors:”.  The default settings look like the screenshot below where segment #1 is informational, segment #2 is a warning and #3 is an error.  You can’t see the comment on the file as a whole:

Screenshot: en-da machine translation… apologies for the quality if it’s poor.

In addition to the visual stimulus, you can also work with the “comments” window which is shown here above the editor.  This is pretty useful for several reasons:

1. You can see all the comments in the file in one go,
2. You can identify comments by their severity, location (segment number and source or target indicator), which file they relate to, the scope (file, segment, range) and the date the comment was created.

You might also find it’s helpful to move this comment window to the left/right-hand side of the screen where you can see much more of the list and use it to navigate through the comments.  For one or two it’s not worth it, but if you have a lot it appears aesthetically pleasing to the eyes… mine anyway!

Importing files with comments

Probably the first thing to clarify here is which filetypes have supporting features in the settings for comments and then we can look at what they are.  In a nutshell they are;

• DOC, DOCX
• PPT, PPTX
• XLS, XLSX
• RTF
• PDF
• CSV
• Tab Delimited TXT
• Java Properties

I’m going to ignore XLIFF for this article because this is probably an article all on its own dedicated to the extensibility of XLIFF and how different tools manage the information within.  I’ll ignore TTX too!  Comments for both of these filetypes are taken care of in the software without the user having any control over how they are used at all… so less interesting for me this time around!  If they are in the file, then they will be in Studio as comments to help with the context of the translation.

I’m also going to ignore XML and HTML as these are also “special”.  XML is user defined and the best way to handle comments if you just want to read them is usually to create a stylesheet… see Translate with style… for more information on how to do this.  HTML has its own tag for comments but these are not supported in Studio at all.  I would be quite interested to learn if translating the html comment is ever a requirement?

The file types in my list above however are different.  These all have special comment options in the filetype settings and they all allow you to import comments and decide whether you wish to translate them or not.  But they have different ways of making them available to you.

DOC, PPT, PPTX, XLS, XLSX, RTF

These all have a single option to extract comments for translation or not.  Looks like this and is found under the common node in the filetype settings of each filetype.  The actual description varies a little from filetype to filetype but it’s not hard to figure out which one it is… the main point is that there is just one option which is to extract the comments for translation or not:

If you select this option then comments in the file are extracted and added to the translation in the Editor.  You can tell that they are comments because the Document Structure Information (DSI) column on the right handside when the file is open in the Editor View provides this level of granularity by using a code COM:

Here we see COM and COM+.  The plus symbol just tells you that there is at least one more field relevant to this segment in addition to it being a comment.  So the RTF for example also tells you than this is a paragraph of text… maybe not too interesting this time but sometimes this can be very helpful depending on the context of the text, so maybe an index entry, or a list item, for example.  You can also use this DSI column in interesting ways with the SDLXLIFF Toolkit from the OpenExchange.  This application can extract segments based on the DSI information alone.  So you can select all the comments in your Project in one go and lock them for example… very handy if the comments are extracted but should not be translated, or if they should be locked to ensure they are not counted in an analysis.

CSV, Tab Delimited TXT

These file types work in a different way and don’t allow for comments to be translated at all… at least not if the comments are in a different column. These are really bilingual filetypes and the way they work is by providing a mechanism for the user to specify the source language column, the target language column and a column for comments. Like this:

The image is based on the CSV filetype but it’s exactly the same for the tab delimited. In this example the source is in column 1, the target will be placed into column 2 (and read from column 2 if there are any in the file), and the comments are in column 3. So in both of these filetypes this is only for providing a mechanism to do two things:

1. Determining whether or not to extract the comments at all and displaying them in the DSI information box,
2. Excluding text from being parsed for translation at all if there is a comment in the comment column

In the previous file types the DSI box was purely information to tell you that the extracted text in the Editor was a comment.  In this case the text for the comment itself is held in the DSI box. So you can’t extract it for translation, but you can extract it for information.  I think it’s debatable how useful this is and I would prefer to see some preview capability here that allowed you to see the comments as you work without having to click on the DSI column to see what it said… maybe in a future release! For the time being this is what it looks like:

So you can read the comment in the Additional Information column. As I’m writing this it occurred to me that it would be an improvement if it was at least possible to specify a keyboard shortcut for activating the DSI window as opposed to having to use the mouse… but a preview would be better!

The second option on the filetype is quite useful as a way to exclude specific text from being translated. You can add anything at all into the comments column using Microsoft Excel and then use this option to exclude text that doesn’t have a comment next to it.

If you need to translate the comments then you have two options really (based on the example so far):

1. Copy the comments into column 4 and then process the file using column 4 as the source and column 3 as the target. Delete column 4 when you’re finished… or
2. Copy the comments to the source column, translate with the rest of the file and copy them over the original comments in the target file when the job is complete

If you try the first way and are using column headings in the file then just make sure you give column 4 a different name to column 3, otherwise Studio will present you with an error and won’t process the file.

Java Properties

The filetype works in similar ways to all the filetypes mentioned so far.  You can extract the text for translation and the same text that is extracted is also displayed in the DSI information box… although this is only useful when you don’t choose to extract the comments for translation.  The option in the fietype settings allows you to extract comments for translation or not.  You also have to make sure that the comment identifier is listed in the box. There are two there by default, the hash and the explanation mark, but if the speficic Java resource file you are translating used something different then you can add it in here:

If you choose not to translate the comments then they can be seen in exactly the same way as the CSV and Tab Delimited filetypes… by clicking on the DSI column:

If you choose to extract the comments for translation then they are presented as a normal segment in the editor with the TAG attribute (as opposed to COM) showing in the DSI column.  The order of text is as if the comment line is a translatable line, so checking this option just makes it translatable.

DOCX, PDF

DOCX and PDF files both have the same option, and then two that separate them from the rest:

Both of these filetypes state that they can not only extract comments from a file but they can also convert Studio comments into usable comments in the filetype itself, and convert filetype comments into Studio comments.  These last two options set them apart from all other filetypes.  But there are some interesting things to note when considering this capability.

1. When you open a PDF file it becomes a DOCX and you are actually translating a DOCX converted from a PDF.  So the target file is a DOCX.  Only significant in that it’s clear why the options are the same for saving.
2. PDF comments are what?

I’m asking this second question for myself too because my own reaction was to wonder how you get comments into a PDF file in the first place!  I created a small file with one segment and then added two comments to it.  One using InFix and then one with Adobe Reader.  Irrespective of whether I check the box to extract “As Studio comments” or not the comments are extracted as translatable text.  So I’m not convinced this is working functionality in the current version of the filetype for PDF… it’s also interesting, but a red herring, that the timestamp is some 2-hrs adrift from reality.  Must be set to GMT by default as it’s two hours behind me!  If it is working then I wonder how you put the comments in the PDF?

For DOCX files it’s more straightforward.  The options to extract as translatable text or as Studio comments work like this… the image shows the comments in the Word source file and then the result of opening the file in Studio with either option:

This is pretty neat, and it’s the only filetype that behaves this way.  This is most likely because the way Word files are used commenting like this is very common and is something everyone knows how to use.  Similarly it works the other way too… so if I add some comments into Studio and save my target file the final formatted target DOCX can include my Studio comments (the final option to “Retain Studio target comments in target file“).  I wrote a separate article on this feature here if you are interested, so will try not to repeat myself below.

In the screenshot below you can see the two original source file comments in the message box, also the two new comments I added in Studio into the target text which I also left untranslated (just copied source to target) and what this looks like in the target Word file:

The important point to note is that whilst the Studio comments are now in the target file, the original comments are gone.  So you need to be very careful with comments in a DOCX file, not only in terms of deciding how you wish them to be handled for translation but also in terms of whether it’s important to retain the original comments in the translated file or not.

If it’s important for you to retain the original comments in the translated file, and perhaps even add new comments as I did above then the option to use would be to “Extract comments as translatable text” and “Retain Studio target comments in target file“.  This way both sets of comments are retained.  I don’t know why Word formats the first pair the way it does but I can click on the “2 comments” and this expands to show me both comments.  It might be related to the selection I made being seen at file level (segment zero) and also causing the problem I noted in the Export for External Review below.The second two are clear to see:

So even though I added my Studio comments to exactly the same word as the source comments this is no problem.  All comments are retained.

Perhaps a useful tip at this point is how to lock all source comments extracted as translatable text so they are not touched if you use the option above.  I have mentioned a few times how the Document Structure Column contains the code COM whenever a comment extracted for translation.  This is no different with DOCX.  In Studio out of the box this is purely informational, but if you use the SDLXLIFF Toolkit you can generate the DSI in the files in your project, select the comment tag as shown below and then lock all these segments before you start work.  Very handy!

Using the Export for External Review

Let’s come back to Studio comments for all filetypes now.  There is a feature in Studio called “Export for External Review” which I have covered in the past, but not in relation to comments.  You can find the two articles I wrote, which I hope are useful, here:

• Making use of the Studio track changes features
• Export for external review – a detour

I’m bringing this up again here because this features allows you to add comments in Studio to help with clarification during the translation/review process, for any filetype at all.  This is because the exported file is always Word, so the comments are rendered in the familiar Word style:

Similarly any comments made in the Word review document will be imported back into Studio as Studio comments.  This feature is not for translatable comments at all.

Perhaps one final point on this feature is about source comments.  If the comments were extracted as Studio comments and you export for external review then the source comments will be retained in the Word review file and will survive the round trip.  I also noted an additional problem to be aware of when using the Export for External Review.  If you have a comment in the first segment that encompasses the entire segment then the Export for External Review will fail… at least this is the experience I have found testing this a few times as I wrote this article (I’ll add this to the list in the appropriate article above about troubleshooting problems with this feature).

Comment View Plugin

Now that we see how comments can be used in various places in Studio the last thing I wanted to do was quickly expand on where I started which was making use of comments that are Studio comments as opposed to translatable text.  If you have a large project, with many files, and you’re sharing the work between many translators you may end up with a project full of comments requesting information, explaining where there were problems etc.  But how do you know where these comments are?

The easiest method out of the box is probably to open all the files up in one go and read the comments window that I showed at the start.  This works until you have a project with really large files, or just a project with so many files that the time taken to do this can be a little wasteful.  This is where the comments view plugin can really help.  Once installed and with the view in place all you have to do is select all the files in your project (Ctrl+A with all files showing in the files view) and the plugin tells you two things.  First of all which files contain comments and how many there are:

And secondly you can navigate through the comments themselves and see the source and target text for the associated segment at the same time:

If you need to action any of the comments you can do it quickly without even having to open the files, and if you do need to open a file you just double click the comment in this window and the file opens up at the correct location.  Very handy!

The Comment View Plugin was developed by Junya Takaichi, actually Junya is quite a prolific developer for the OpenExchange and I’d recommend you taking a look at his other apps:

• Regex Match AutoSuggest Provider
• SegmentSearcher
• QuickTmExport

I think his combination of translator, localization engineer and developer gives him a unique insight and ability to be able to use the OpenExchange to create the tools he wants and I think you may find them useful too.