I’m developing an application which has a lot of text and also different modules which can be included or not in every build.
For each saved project we generate automatically a report with all the details (i.e. description of algorithms used in that project and so on). Currently we embed all text as strings in the source code and we also support different languages through po and mo files.
The good points of the system is that it is very easy to dynamically generate documentation and report files. The bad point is that having a lot of text in source code is ugly and the formatting (i.e. with html) is not comfortable, editing of the text is difficult, no easy spell check and terrible to translate.
So, the final question is: whould you rather embed documentation in code or write external documentation files (for example html) for different languages and parse them on runtime? Obviously the core text of the software, such us message boxes will stay in code anyway.
If it matters, I’m working in C++ with wxWidgets.
I think all text which may change between different versions of the code should be kept in separate property files. You can build a mechanism which maps message ids to the proper string from a property file, say map id 15 to ‘search’ or to ‘busca’ in the English and Spanish property files respectively. So a property file may be an XML or a CSV with id-message pairs. When running your program, you supply it with the property file(s) as parameters. When it starts, it first loads the property strings into a map, and then you will use property[15] instead of the string ‘search’. Of course, you can use a textual label instead of a numerical id. I would also consider generating the documentation from the property files automatically, maybe using CSS. This makes it a lot easier to edit and translate the messages.