Translate only marked strings

This Forum is for general issues about MadCap Lingo
Post Reply
KendeWachter
Jr. Propeller Head
Posts: 8
Joined: Fri Dec 08, 2017 4:17 am

Translate only marked strings

Post by KendeWachter »

We're just starting to translate our software package and user manuals. The software itself is already translated into French. Before translating the whole 500 page manual into French, we would like to publish a user guide in English, but with references to the French software strings instead of the English.

Example:
EN: On the File menu, click Open.
FR: On the Fichier menu, click Ouvrir.

In Lingo, I only want to see two segments:
  • File
  • Open
Can Lingo handle that?

What we tried but didn't work:
  • We marked our translatable strings in a label span (e.g. On the <span class="label">File</span> menu...). I found that Lingo does not support custom file types for HTM files (which is a bit odd since all topics in Flare are HTML).
  • We marked our translatable strings in a condition (e.g. On the <span class="label" MadCap:conditions="Translate.Labels">File</span> menu...). While you can exclude conditions in Lingo, more advanced include/exclude rules have to be done in a target. So I did... I created a target that includes Translate.Labels and excludes Translate.DoNotTranslate. Because I 'only' want my Translate.Labels, I marked entire topics or parts of topics as DoNotTranslate. The problem is that Lingo does not look inside of conditions. I.e. If a topic or HTML element is marked as Translate.DoNotTranslate, it ignores its content, even if there is content that is marked as Translate.Labels... (e.g. <p MadCap:conditions="Translate.DoNotTranslate">On the <span class="label" MadCap:conditions="Translate.Labels">File</span> menu...</p>.)
The only workaround I can think of, is putting all our translatable strings in snippets, or in a glossary file. Both sounds rather tedious... Since there is already markup, I'd expect Lingo to support it, in the same way SDL Trados Studio and Memsource do.

Any help would be appreciated!
Dafra08
Propeller Head
Posts: 45
Joined: Fri Aug 16, 2019 1:02 am

Re: Translate only marked strings

Post by Dafra08 »

I know this is old and completely out-of-date, but since I have some experience both from the translation and tech writer industries I thought I'd share my thoughts, if someone has the same question (found the post when googling other things).

Software references are one of the biggest sources of confusion and errors when translating documentation (and time consuming), so I think you are on the right track when considering handling them separately. I would go one step further and handle them separately directly in the source language project, by creating variable sets in Flare for your software strings. It takes some preparation time, but it's nothing compared to what you save when you start updating your Flare project, and translating it.

So instead of writing like this in Flare:
On the File menu, click Open.
you would have (in this example the variable set is called ”UI”):
On the <MadCap:variable name="UI.stringIDFile" /> menu, click <MadCap:variable name="UI.stringIDOpen" />.
If you already had variables in your project, you could have achieved what you are after instantly, documentation in EN with software references in FR, without any extra translation effort at all. Just create a variable set of the French software strings and replace the variable set in your EN Flare project, and voilà! A semi-FR project. (I have done this, EN help with Estonian software references, so it's tested and verified).

To start using variables in your Flare project you need the following:
- Access to the software strings from your development department.
- Translated software strings. This is a separate process.
- Same string ID's for all languages.

How to create a variable set out of your software files. This is the fun part :)
1. Compare your software files with a Flare variable set.
2. Work out a sequence of regexes to search and replace strings, so that the file is converted to the format of a Flare variable set. This is where you might have to invest some time. One tip is to write your search and replace steps down as you are doing them, to keep track of what you have tried, and to have the final version documented.
3. Create a macro of your search and replace sequence in whatever tool you use. (I use Notepad++ since we have our software strings in TXT files, previously SQL files.)
4. Rename the file ”<filename>.flvar”. Note that the name of the FLVAR file has to be the same every time you update it, and across all languages, so no language codes or anything like that. Tip: Choose a short name, since it will take up less space in the suggestion window in Flare when you write. I use ”UI” (= user interface). The file name is part of the variable (see example above).
5. Whenever the software strings have been updated, copy the software file, run the macro and replace your existing variable set with the new one.

Notes:
- You might have to work a little on your regex sequence to make it catch all variations and strange strings that are usually included in the software.
- Whenever the developers introduce new ways of writing texts, the sequence might have to be adjusted. Example: I used the placeholder ”AAA” in some instance, to shift things around during the conversion, since I know that there is no word spelled with three A's. But at some point string ID's that started with ”AAA_”. That broke my sequence, so I had to adjust it. I think I use ”AAAAA” for that placeholder now :)
- Check the undefined variables analysis in Flare after updating a variable set. This is to find any string ID's that have been removed or changed, that you might use in your documentation.
- Don't include the software FLVAR files when sending files out for translation through Lingo. No need to translate them, since the software has already been translated in a separate process.

Benefits:
- Keeping the software references in your documentation up to date is a matter of a few clicks.
- Translators don't need to bother checking software references and their translations. They are all automated, and always correct (provided that you have used the correct string in the source text of course :) Inconsistencies in the software is a very common question from translators (different translations of ”File” in different occasions, so which one to use in which contexts). Those questions are eliminated completely.
- When creating your variable sets with the macro you will notice whenever there is an error, or other deviances in the software files, which you can feedback to your developers. You will function as an extra QA step.
KendeWachter
Jr. Propeller Head
Posts: 8
Joined: Fri Dec 08, 2017 4:17 am

Re: Translate only marked strings

Post by KendeWachter »

Hi Dafra08,

Thanks for the answer! I like your idea. We actually considered putting our strings in a variable set. Theoretically it makes sense, though it's hard to implement in practice...

We have a database of UI strings that we could (relatively) easily convert to a Flare variable set. However...
[*] Our software is developed in an agile way, in a multitude of Git branches. In other words, there are many versions of the UI string set at the same time.
[*] We document before the release of the software to reduce the time to market. So typically we're ahead of the actual software implementation. In other words, the UI string set is not finished yet when we document the software.

These problems may be overcome, but it would cost time for every documentation task...

In Lingo's competitors (Trados Studio, Memsource), I can use a RegEx or, even better, an XPath to filter content based on XML elements and their attributes. Took me a few hours to configure it in Memsource, but it has been working smoothly for years now. We don't require any workarounds in Flare and we can just re-use the translation memory for the UI string database. All's good, but it's a pity having to go outside the MadCap ecosystem...
doloremipsum
Sr. Propeller Head
Posts: 290
Joined: Mon Aug 26, 2019 2:11 pm

Re: Translate only marked strings

Post by doloremipsum »

This is certainly something I struggle with as well... For I while I thought that Term Bases in Lingo would be the answer - it seems like the perfect use-case for a list of strings with fixed translations. Unfortunately, the translation service we use doesn't use Lingo (or, um, any professional translation software) so they can't use the automated suggestions from a term base. I'd hoped that I could apply the terms automatically before sending the content for translation like I do with the translation memory, but that doesn't seem to be possible. Does Memrise do something similar?

My current solution is to create a excel glossary from the downloaded software terms and ask the translators to use it, which is obviously not ideal. But easy to do since I can pull our software strings as CSVs.

Using variables sounds neat in theory, but in practice - well, let's just say we don't need 6000 variables clogging up our Flare projects.
in hoc foro dolorem ipsum amamus, consectimur, adipisci volumus.
Dafra08
Propeller Head
Posts: 45
Joined: Fri Aug 16, 2019 1:02 am

Re: Translate only marked strings

Post by Dafra08 »

KendeWachter wrote: We have a database of UI strings that we could (relatively) easily convert to a Flare variable set. However...
[*] Our software is developed in an agile way, in a multitude of Git branches. In other words, there are many versions of the UI string set at the same time.
[*] We document before the release of the software to reduce the time to market. So typically we're ahead of the actual software implementation. In other words, the UI string set is not finished yet when we document the software.
That sounds almost like our situation as well. UI strings developed continuously, and documentation ahead of release (at least we try to :) ). In our case though the UI strings are usually finished when we write the documentation. Occasionally we are ahead and use some sort of placeholder to be able to go back and replace with the variable. More often than not I have opinions on the UI strings as well, so they are sometimes updated (which is no problem documentationwise when using variables).

On another note, our translation agency use Memsource as well. We have set up a continuous job for our software, and get translations back at noon every Friday. One of our wizards have created a neat solution. In short, whenever our software is updated, a file is placed in an MS Azure directory (also works with Dropbox, OneDrive etc.). The file in Memsource is updated. The translators are free to translate whenever it fits their schedule, as long as the file is complete at noon on Friday. At that time the translated file is sent back by Memsource to another MS Azure directory, where our system picks it up and creates a pull request, and I, or anyone can review and accept it into the code.
Dafra08
Propeller Head
Posts: 45
Joined: Fri Aug 16, 2019 1:02 am

Re: Translate only marked strings

Post by Dafra08 »

doloremipsum wrote:This is certainly something I struggle with as well... For I while I thought that Term Bases in Lingo would be the answer - it seems like the perfect use-case for a list of strings with fixed translations. Unfortunately, the translation service we use doesn't use Lingo (or, um, any professional translation software) so they can't use the automated suggestions from a term base. I'd hoped that I could apply the terms automatically before sending the content for translation like I do with the translation memory, but that doesn't seem to be possible. Does Memrise do something similar?

My current solution is to create a excel glossary from the downloaded software terms and ask the translators to use it, which is obviously not ideal. But easy to do since I can pull our software strings as CSVs.
Hmm, yes, you would really think that Lingo could do that ... I am not entirely sure how it works in Memsource, but I know it can match part of strings with a termbase. But I am curious, if the translation agency does everything manually every time, since they are not using any tool, don't you get the same questions over and over again?
doloremipsum wrote:Using variables sounds neat in theory, but in practice - well, let's just say we don't need 6000 variables clogging up our Flare projects.
Yep, that's the downside, but it has actually been no problems at all so far. I have four variable sets. Three very small (two apps, and some database things), less than 100 kB each, a few hundred entries. And one fairly large with the main UI, 15,000-16,000 variables, approx. 2 MB. Occasionally there is a slight delay with the autosuggest feature, or if you insert a variable manually (when opening the list), but in general it is quite smooth (or I have got used to it ...). The payoff is just too big to do it any other way :)
doloremipsum
Sr. Propeller Head
Posts: 290
Joined: Mon Aug 26, 2019 2:11 pm

Re: Translate only marked strings

Post by doloremipsum »

Dafra08 wrote:But I am curious, if the translation agency does everything manually every time, since they are not using any tool, don't you get the same questions over and over again?
Late response sorry - but you're actually overestimating how professional our translation agency is. We use Gengo, which is basically a gig service (think Uber for translation). You post a file and instructions, a translator picks it up and has a certain amount of time to turn it around. It's quite a short time limit so most of them don't really take the time to ask questions.

Creates a lot of extra work for me and has patchy results, but it is very cheap! :roll:
in hoc foro dolorem ipsum amamus, consectimur, adipisci volumus.
Dafra08
Propeller Head
Posts: 45
Joined: Fri Aug 16, 2019 1:02 am

Re: Translate only marked strings

Post by Dafra08 »

Well, the question is, as always, is it really cheap in the long run if it creates a lot of extra work for you ...? :)
Post Reply