This document covers guidelines on writing for internationalization (i18n) and localization (l10n).
Contents
Examples Are Universal
When writing, there are times when you need to use examples to explain the subject matter. Always make examples universal. Regardless of the written language, use examples that appeal to as wide an audience as possible. To make your examples "universal," here are some tips that can help you:
- When using screen captures, be consistent in their look and feel. If there is no localized equivalent of the screen capture, chances are that your sample will be used.
- Make your subjects simple. For example, a name like "Joe" is likely to be more familiar to your reader than "Pyotr" or "Shigetaka".
Consider cultural differences between nations when making examples. See Cultural Considerations below for guidelines.
Use of Numerals and Figures
Improper use of numerals and figures can provide the most confusion when translated to another language. Numerals are very important when it comes to measurements. Even simple figures like date and time can have big differences between countries.
When writing dates, remember that different cultures have different ways of describing it. You are encouraged to consider the following conventions in writing dates:
- Use the correct date convention for your audience.
- Do not abbreviate days and months. This will prevent confusion when translation work has begun on the finished document.
- Consider adding a small note in the document about the date convention being used.
When there is a need to write the time, you are encouraged to use the 24-hour format. You should inform your audience the timezone and naming convention being used.
Using Correct Terminology
Terminology is an aspect of writing that can cause a lot of confusion among translators. The following guidelines may help you prepare a language-friendly document suitable for translation.
- Choose words with one or very few meanings.
- Use simple verb forms in writing. Most verbs in the simple form will likely have an equivalent in another language.
- Avoid jargon and slang words.
- Whenever necessary, define all special and technical terms in a glossary section of your document.
- Choose words that are easy to pronounce. Not all readers of your document are native English speakers.
- Limit difficult words to technical terms so as not to slow down your audience when reading.
- Expressions for time, place, and relationship should be as simple as possible.
- Always make sure your spelling is correct! Use a spell checker and a dictionary when in doubt.
Cultural Considerations
When writing documentation, always keep in mind that your work might be translated to another language. For this reason, you need to consider cultural differences on a global scale. Names, places, events, and actions should be chosen as carefully as possible so as to avoid misunderstanding between the parties concerned. Consider the following guidelines when writing:
- Do not use names of places, events, and actions that are historically bound to certain countries and their cultures. Some people may find such names offensive for various reasons. The same applies to the use of religious references as it may inject a clash of beliefs among readers of your work.
- Informal expressions must be avoided at all times and may only be used when absolutely necessary. The end product of a translated document filled with colloquial expressions would make no sense at all to the reader.
- Date and time are expressed differently in many countries. Consider writing them according to the ISO 8601 standard. Make sure to indicate the date and time conventions used in your document so that a translator can easily adjust the text to be translated.