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.
