Task documentation
Guidelines for preparing your code and documentation for translation

The following are some rules of thumb to help you prepare your code and documentation for translation. These tips are based on my experience and lessons learned the hard way.
  1. Put the English message in plugin.properties only for plugin.xml and MANIFEST.MF If the string to be translated is in plugin.xml or MANIFEST.MF, put the corresponding English in plugin.properties. When Eclipse is started, every plugin.xml and its corresponding plugin.properties is loaded. Multiply that by the number of plugins to realize that the smaller plugin.properties is, the faster Eclipse loads and the less memory it takes.
  2. Put the English message in message.properties if the string to be translated is not in plugin.xml or MANIFEST.MF (e.g. UI). Follow the technique outlined in the related article Message bundles below rather than using the standard Java mechanism if possible. message.properties can be located anywhere in a plug-in.
  3. To translate a feature, put the feature.properties AND its translations in the feature.
  4. Do not check in any translated files into CVS. TPTP only posts the translations on the download site when those files are delivered to TPTP; it doesn't maintain the files.
  5. Avoid abbreviations For example, use "cannot" and "do not" rather than "can't" and "don't". Use "for example" instead of "e.g." and "so on" instead of "etc.". Translators have difficulty with abbreviations.
  6. Avoid using a slash for and/or. Rewrite the sentence to indicate the exact meaning because the slash construct does not exist in all other languages. The translators will be forced to guess if you meant "and" or "or" and they may guess incorrectly.
  7. Write in complete sentences. English shorthand, such as "Out of memory" is not easily translated. Say the entire sentence, for example, "There is insufficient memory to complete the operation." to ensure that the translation conveys the meaning that you intended.
  8. Avoid programmatically concatenating phrases together. For example, say you have several keys in your resource bundle and some code in your .java program to concatenate them:
    	KEY1 = An error occurred; perform the following action:
    	KEY2 = exit the workbench.
    	KEY3 = check that the port is available.
    	...
    	KEYN = check that you have enough permissions on the machine.
    
    	String preMessage = ResourceBundle.get("KEY1"); // line 1
    	String errMessage = ResourceBundle.get("KEY"+errorId); // line 2
    	Logger.log(preMessage + " " + errMessage); // line 3
    	
    While the concatenated message in line 3 makes sense in English, in other languages it may sound like Yoda is speaking. Other languages may use a different ordering of adjectives, verbs, etc. It's also harder for a translator to translate part of a sentence rather than a complete sentence.
  9. Make sure that the translatability log is clean. If you run into something that you don't know how to fix, you can find the answer in the list of common translation problems.
  10. Avoid adding a screen capture Screen captures are high maintenance.
    Why screen captures are high maintenance:
    • Every graphic has to be reviewed during the technical review of a release. If you use text alone to describe the instructions to the user, you remove the dual maintenance of reviewing both the text and the graphics. (You can't remove the text from the page because blind people use a screen reader to read the documentation to them and screen readers can read only the "alt" text of a graphic.)
    • During the accessibility test of a release, every page that has a graphic has to be reviewed with a screen reader to ensure that the alt text that describes the graphic matches the graphic and explains what the graphic is trying to convey to a blind user. Note that the accessibility test is needed only on files that have changed since the last accessibility test. That said, based on my experience, it takes on average five minutes to listen to a page in its entirety or one to two minutes if you listen to only the text around the graphic. Save yourself time and remove screen captures where possible.
    Rule of thumb for when to add a screen capture:
    • Do Use a screen capture to summarize a result of a complex series of steps. In this case the user is given some reassurance that they have performed the steps correctly and can proceed to the next stage of the instructions. If their result doesn't match the result then they know to go back and find out what part of the instruction that they missed.
    • Do not Use a screen capture to show a dialog that appears easily or quickly, e.g. File > New > Project. Avoid graphics unless they clarify something in the text.
    If you must use a screen capture, you can put it into the docs as-is. No further action required. The translators are responsible for capturing the equivalent screen capture in the translated product.
  11. Graphics, excluding screen captures, must not contain text. If the graphic is not a screen capture and does contain text, then the text must be translated, and translators will not recreate graphics.

    A. If the information can be conveyed by text alone easily, then remove the graphic and use only text instead.

    B. If the information is easier to understand when a graphic is used, then use the numbering technique (example below) to replace text in graphics.

    Show the example

    Example of numbering technique
    If you want to run a TPTP JUnit Test remotely, you must create and configure a test deployment. At a basic level, test deployments are TPTP entities which relate other TPTP entities, artifacts and locations, in pairs:

    Figure 1:
    1. Deployment
    2. Artifact
    3. Location
    4. Test suites, datapools, and so on
    5. Host name, and so on

Related articles

How to internationalize your eclipse plug-in
Message Bundles